Liquid Glass Overlay

Draggable glass that refracts the live content below.

Experimental · Chrome origin trialChecking support…

Built on the WICG HTML-in-Canvas proposal, which is not a web standard and changes between Chrome versions. Every component works without it: other browsers get the same live DOM with a CSS approximation of the effect.

To try the native version locally, open Chrome Canary and enable chrome://flags/#canvas-draw-element. In production, register for the origin trial and set NEXT_PUBLIC_HTML_IN_CANVAS_OT_TOKEN.

Checking support…

Notes from the glass studio

Light bends where glass gets thin. That is why the rim of a lens shows the world pulled outward with a fringe of color, while the middle stays clear enough to read through. Drag the toolbar across this text to see it.

Every word here is still real text: links work, and you can select a sentence right under the glass.

Installation

CLI

npx shadcn@latest add https://hantui-theta.vercel.app/r/liquid-glass-overlay.json

Manual

Install the dependencies

npm install clsx lucide-react motion tailwind-merge

Add the shared helpers

Components use cn() from lib/utils.ts and the motion tokens below. See Installation if you have not set them up yet.

lib/html-canvas/gl.ts

/**
 * Small WebGL2 helpers shared by the HTML-in-Canvas components. Shaders work in the canvas's CSS
 * pixels, so a DOMMatrix used to draw an element is the same one passed to `syncElementGeometry`.
 */

/**
 * GLSL: projects a CSS-px position (already multiplied by the draw matrix, so it may carry a
 * perspective w) to clip space. Keeps w for perspective-correct texturing. Needs `uniform vec2 u_canvas`.
 */
export const PROJECT_GLSL = /* glsl */ `
uniform vec2 u_canvas;
vec4 projectCss(vec4 q) {
  return vec4(2.0 * q.x / u_canvas.x - q.w, -(2.0 * q.y / u_canvas.y - q.w), 0.0, q.w);
}`;

/** GLSL: signed distance to a rounded rectangle centered at the origin (half size `b`, radius `r`). */
export const ROUND_RECT_GLSL = /* glsl */ `
float sdRoundRect(vec2 p, vec2 b, float r) {
  vec2 q = abs(p) - b + r;
  return length(max(q, 0.0)) + min(max(q.x, q.y), 0.0) - r;
}`;

function compile(gl: WebGL2RenderingContext, type: number, source: string) {
  const shader = gl.createShader(type);
  if (!shader) throw new Error("Could not create a shader");
  gl.shaderSource(shader, source);
  gl.compileShader(shader);
  if (!gl.getShaderParameter(shader, gl.COMPILE_STATUS) && !gl.isContextLost()) {
    const log = gl.getShaderInfoLog(shader);
    gl.deleteShader(shader);
    throw new Error(`Shader compile failed: ${log}`);
  }
  return shader;
}

export interface Program {
  program: WebGLProgram;
  /** Cached uniform location lookup. */
  u: (name: string) => WebGLUniformLocation | null;
}

/** Compiles and links a program. Attribute 0 is always `a_pos`. */
export function createProgram(gl: WebGL2RenderingContext, vertex: string, fragment: string): Program {
  const program = gl.createProgram();
  if (!program) throw new Error("Could not create a program");
  gl.attachShader(program, compile(gl, gl.VERTEX_SHADER, vertex));
  gl.attachShader(program, compile(gl, gl.FRAGMENT_SHADER, fragment));
  gl.bindAttribLocation(program, 0, "a_pos");
  gl.linkProgram(program);
  if (!gl.getProgramParameter(program, gl.LINK_STATUS) && !gl.isContextLost()) throw new Error(`Program link failed: ${gl.getProgramInfoLog(program)}`);
  const cache = new Map<string, WebGLUniformLocation | null>();
  return {
    program,
    u: (name) => {
      if (!cache.has(name)) cache.set(name, gl.getUniformLocation(program, name));
      return cache.get(name) ?? null;
    },
  };
}

export interface Mesh {
  vao: WebGLVertexArrayObject;
  count: number;
}

/** A unit grid over [0, 1]² as indexed triangles, in attribute 0. One cell is a plain quad. */
export function createGrid(gl: WebGL2RenderingContext, cols = 1, rows = 1): Mesh {
  const vao = gl.createVertexArray();
  if (!vao) throw new Error("Could not create a vertex array");
  gl.bindVertexArray(vao);
  const positions: number[] = [];
  for (let y = 0; y <= rows; y++) for (let x = 0; x <= cols; x++) positions.push(x / cols, y / rows);
  const indices: number[] = [];
  for (let y = 0; y < rows; y++) {
    for (let x = 0; x < cols; x++) {
      const i = y * (cols + 1) + x;
      indices.push(i, i + 1, i + cols + 1, i + 1, i + cols + 2, i + cols + 1);
    }
  }
  const vbo = gl.createBuffer();
  gl.bindBuffer(gl.ARRAY_BUFFER, vbo);
  gl.bufferData(gl.ARRAY_BUFFER, new Float32Array(positions), gl.STATIC_DRAW);
  gl.enableVertexAttribArray(0);
  gl.vertexAttribPointer(0, 2, gl.FLOAT, false, 0, 0);
  const ibo = gl.createBuffer();
  gl.bindBuffer(gl.ELEMENT_ARRAY_BUFFER, ibo);
  gl.bufferData(gl.ELEMENT_ARRAY_BUFFER, new Uint32Array(indices), gl.STATIC_DRAW);
  gl.bindVertexArray(null);
  return { vao, count: indices.length };
}

/** Draws a mesh from `createGrid`. */
export function drawMesh(gl: WebGL2RenderingContext, mesh: Mesh, instances = 0) {
  gl.bindVertexArray(mesh.vao);
  if (instances > 0) gl.drawElementsInstanced(gl.TRIANGLES, mesh.count, gl.UNSIGNED_INT, 0, instances);
  else gl.drawElements(gl.TRIANGLES, mesh.count, gl.UNSIGNED_INT, 0);
  gl.bindVertexArray(null);
}

/** Uploads a DOMMatrix to a mat4 uniform. */
export function setMatrix(gl: WebGL2RenderingContext, location: WebGLUniformLocation | null, matrix: DOMMatrix) {
  gl.uniformMatrix4fv(location, false, matrix.toFloat32Array());
}

/** Parses "#rrggbb" into 0–1 RGB. */
export function rgb(hex: string): [number, number, number] {
  const h = hex.replace("#", "");
  const n = Number.parseInt(h.length === 3 ? h.replace(/./g, (c) => c + c) : h, 16) || 0;
  return [((n >> 16) & 255) / 255, ((n >> 8) & 255) / 255, (n & 255) / 255];
}

lib/html-canvas/setup.ts

import type { HtmlCanvasSupport } from "@/lib/html-canvas/support";

/* eslint-disable @typescript-eslint/no-explicit-any -- the API is not in lib.dom yet */

/**
 * Attributes that make a canvas lay out and paint its children, for use in JSX so the canvas is
 * drawable from its first layout: `content="drawable"` on 155+, `layoutsubtree` before that.
 */
export function drawableCanvasAttributes(support: HtmlCanvasSupport): Record<string, string> {
  if (support.version === "155+") return { content: "drawable" };
  if (support.version === "none") return {};
  return { layoutsubtree: "" };
}

/** Makes a canvas drawable after the fact (idempotent). */
export function prepareDrawableCanvas(canvas: HTMLCanvasElement) {
  const c = canvas as any;
  if ("content" in HTMLCanvasElement.prototype) {
    if (canvas.getAttribute("content") !== "drawable") canvas.setAttribute("content", "drawable");
  } else if (!canvas.hasAttribute("layoutsubtree")) {
    canvas.setAttribute("layoutsubtree", "");
    if ("layoutSubtree" in c) c.layoutSubtree = true;
  }
}

/**
 * Attributes for an element the canvas draws on its own. On 155+ it must carry `drawable`; on older
 * versions it must instead be a direct child of the canvas, which callers arrange in their markup.
 */
export function drawableElementAttributes(support: HtmlCanvasSupport): Record<string, string> {
  return support.version === "155+" ? { drawable: "" } : {};
}

/** Asks the canvas for a `paint` event on the next frame, where supported. */
export function requestCanvasPaint(canvas: HTMLCanvasElement) {
  const c = canvas as any;
  if (typeof c.requestPaint === "function") c.requestPaint();
}
/* eslint-enable @typescript-eslint/no-explicit-any */

lib/html-canvas/support.ts

/**
 * Feature detection for the experimental HTML-in-Canvas API (WICG html-in-canvas). The API is a
 * Chrome origin trial, not a standard, and its shape changed in Chrome 150 and 155. Nothing outside
 * `src/lib/html-canvas/` may touch it: every call goes through these adapters.
 *
 * - 155+: `content="drawable"`, `drawable` descendants, `texElementSubImage2D`,
 *   `canvas.updateElementGeometry()` and automatic hit-testing for 2D draws.
 * - 150–154: `layoutsubtree`, `drawElementImage()` returning a DOMMatrix, `texElementImage2D(target,
 *   internalformat, element)` and `canvas.getElementTransform(element, drawTransform)`.
 * - legacy (< 150): `texElementImage2D(target, level, internalformat, format, type, element)`.
 */

export type HtmlCanvasVersion = "155+" | "150-154" | "legacy" | "none";

export interface HtmlCanvasSupport {
  /** `drawElementImage` on 2D contexts. */
  twoD: boolean;
  /** Element textures in WebGL2. */
  webgl: boolean;
  /** Element textures in WebGPU. */
  webgpu: boolean;
  version: HtmlCanvasVersion;
}

export const NO_SUPPORT: HtmlCanvasSupport = { twoD: false, webgl: false, webgpu: false, version: "none" };

/* eslint-disable @typescript-eslint/no-explicit-any -- the API is not in lib.dom yet */
let cached: HtmlCanvasSupport | null = null;

/** What this browser supports. Always "none" on the server. Cached after the first call. */
export function getHtmlCanvasSupport(): HtmlCanvasSupport {
  if (typeof window === "undefined" || typeof HTMLCanvasElement === "undefined") return NO_SUPPORT;
  if (cached) return cached;
  const canvasProto = HTMLCanvasElement.prototype as any;
  const ctx2d = typeof CanvasRenderingContext2D !== "undefined" ? (CanvasRenderingContext2D.prototype as any) : {};
  const gl2 = typeof WebGL2RenderingContext !== "undefined" ? (WebGL2RenderingContext.prototype as any) : {};
  const gpuQueue = typeof (window as any).GPUQueue !== "undefined" ? (window as any).GPUQueue.prototype : {};

  const twoD = "drawElementImage" in ctx2d;
  const sub = "texElementSubImage2D" in gl2;
  const tex = "texElementImage2D" in gl2;
  const webgpu = "drawElementImageToTexture" in gpuQueue || "copyElementImageToTexture" in gpuQueue;

  let version: HtmlCanvasVersion = "none";
  if (sub || "content" in canvasProto || "updateElementGeometry" in canvasProto) version = "155+";
  else if (tex) version = typeof gl2.texElementImage2D === "function" && gl2.texElementImage2D.length >= 6 ? "legacy" : "150-154";
  else if (twoD || "layoutSubtree" in canvasProto) version = "150-154";

  cached = { twoD, webgl: sub || tex, webgpu, version };
  return cached;
}

/** True when the API can draw into the given context type. */
export function supportsContext(support: HtmlCanvasSupport, context: "2d" | "webgl2") {
  return support.version !== "none" && (context === "2d" ? support.twoD : support.webgl);
}

/** A short label for status chips: "Chrome 150–154 API". */
export function describeSupport(support: HtmlCanvasSupport) {
  if (support.version === "none") return "Not supported";
  return { "155+": "Chrome 155+ API", "150-154": "Chrome 150–154 API", legacy: "Pre-150 API" }[support.version];
}
/* eslint-enable @typescript-eslint/no-explicit-any */

lib/html-canvas/sync-geometry.ts

import { getHtmlCanvasSupport } from "@/lib/html-canvas/support";

/* eslint-disable @typescript-eslint/no-explicit-any -- the API is not in lib.dom yet */

/**
 * Tells the browser where an element is drawn, so clicks, text selection, focus rings and screen
 * reader focus land on the drawn pixels. `canvasTransform` maps the element's own CSS px (origin at
 * its top-left) to the canvas's CSS px, and may include perspective; it is converted to the device
 * pixels the API expects.
 *
 * Canvas children are laid out at the canvas's top-left corner (they do not stack), so the transform
 * is the element's whole position.
 *
 * For non-affine warps (ripples, curls, cloth), pass the closest affine approximation and calm the
 * warp while an input inside the element has focus.
 */
export function syncElementGeometry(canvas: HTMLCanvasElement, element: HTMLElement, canvasTransform: DOMMatrix) {
  const c = canvas as any;
  const support = getHtmlCanvasSupport();
  const cssWidth = canvas.clientWidth || canvas.width;
  const cssHeight = canvas.clientHeight || canvas.height;
  // The API works in device pixels on both sides (the element's rendered image and the canvas's backing
  // store), so the CSS-px matrix is conjugated by the pixel ratio: S · M · S⁻¹.
  const toBackingStore = new DOMMatrix().scale(canvas.width / cssWidth, canvas.height / cssHeight, 1);
  const pixels = toBackingStore.multiply(canvasTransform).multiply(toBackingStore.inverse());
  try {
    if (support.version === "155+" && typeof c.updateElementGeometry === "function") {
      c.updateElementGeometry(element, { canvasTransform: pixels });
      return;
    }
    if (typeof c.getElementTransform === "function") {
      element.style.transform = c.getElementTransform(element, pixels).toString();
      return;
    }
  } catch {
    // Fall through to the manual mapping below.
  }
  // Manual: children sit at the canvas origin, so the CSS-px transform applies as is.
  element.style.transformOrigin = "0 0";
  element.style.transform = canvasTransform.toString();
}

/** Clears geometry set by `syncElementGeometry` or a legacy `drawElement2D`. */
export function clearElementGeometry(element: HTMLElement) {
  element.style.transform = "";
  element.style.transformOrigin = "";
}

/** A CSS-px perspective matrix, like `perspective(d)` in CSS. */
export function perspective(distance: number) {
  return new DOMMatrix([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, -1 / distance, 0, 0, 0, 1]);
}
/* eslint-enable @typescript-eslint/no-explicit-any */

lib/html-canvas/texture-webgl.ts

import { getHtmlCanvasSupport } from "@/lib/html-canvas/support";

/* eslint-disable @typescript-eslint/no-explicit-any -- the API is not in lib.dom yet */

/** A WebGL texture that holds a live element's pixels. */
export interface ElementTexture {
  texture: WebGLTexture;
  /** Natural size of the last upload, in CSS px. */
  width: number;
  height: number;
  /** Allocated size on 155+, where the storage is reused until the element resizes. */
  allocated: { width: number; height: number } | null;
}

/** Creates an empty, linearly filtered, edge-clamped texture for `uploadElementTexture`. */
export function createElementTexture(gl: WebGL2RenderingContext): ElementTexture {
  const texture = gl.createTexture();
  if (!texture) throw new Error("Could not create a texture");
  gl.bindTexture(gl.TEXTURE_2D, texture);
  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
  return { texture, width: 0, height: 0, allocated: null };
}

/**
 * Uploads an element's current rendering into `target`. Call it from the canvas `paint` event or on
 * resize, never every frame. Returns false when the element could not be uploaded.
 *
 * - 155+: measures with `captureElementImage`, allocates once with `texImage2D(…, null)` (again only
 *   when the size changes), then copies with `texElementSubImage2D`.
 * - 150–154: `texElementImage2D(target, internalformat, element)`.
 * - legacy: `texElementImage2D(target, level, internalformat, format, type, element)`.
 */
export function uploadElementTexture(gl: WebGL2RenderingContext, target: ElementTexture, element: Element) {
  const g = gl as any;
  const support = getHtmlCanvasSupport();
  const box = element.getBoundingClientRect();
  const html = element as HTMLElement;
  // Layout size, unaffected by the CSS transform used for hit-testing.
  const width = html.offsetWidth || box.width;
  const height = html.offsetHeight || box.height;
  if (!width || !height) return false;
  gl.bindTexture(gl.TEXTURE_2D, target.texture);
  try {
    if (support.version === "155+" && typeof g.texElementSubImage2D === "function") {
      const canvas = gl.canvas as any;
      let natural = { width, height };
      if (typeof canvas.captureElementImage === "function") {
        const image = canvas.captureElementImage(element);
        natural = { width: image.width, height: image.height };
        image.close?.();
      }
      if (!target.allocated || target.allocated.width !== natural.width || target.allocated.height !== natural.height) {
        gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA8, natural.width, natural.height, 0, gl.RGBA, gl.UNSIGNED_BYTE, null);
        target.allocated = natural;
      }
      g.texElementSubImage2D(gl.TEXTURE_2D, 0, 0, 0, element);
    } else if (support.version === "legacy") {
      g.texElementImage2D(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, element);
    } else if (typeof g.texElementImage2D === "function") {
      g.texElementImage2D(gl.TEXTURE_2D, gl.RGBA8, element);
    } else {
      return false;
    }
  } catch {
    return false;
  }
  target.width = width;
  target.height = height;
  return true;
}
/* eslint-enable @typescript-eslint/no-explicit-any */

lib/html-canvas/use-html-canvas.ts

"use client";

import { useCallback, useEffect, useLayoutEffect, useRef, useState, useSyncExternalStore } from "react";
import { useReducedMotion } from "motion/react";
import { drawableCanvasAttributes, prepareDrawableCanvas, requestCanvasPaint } from "@/lib/html-canvas/setup";
import { getHtmlCanvasSupport, NO_SUPPORT, supportsContext, type HtmlCanvasSupport } from "@/lib/html-canvas/support";

export type HtmlCanvasMode = "auto" | "native" | "fallback";
type ContextType = "2d" | "webgl2";
type ContextFor<C extends ContextType> = C extends "2d" ? CanvasRenderingContext2D : WebGL2RenderingContext;

export interface HtmlCanvasFrame<C extends ContextType> {
  ctx: ContextFor<C>;
  canvas: HTMLCanvasElement;
  /** Canvas size in CSS px. */
  width: number;
  height: number;
  /** Device pixels per CSS px used for the backing store (capped). */
  dpr: number;
  /** Seconds since the hook started. */
  time: number;
  /** Seconds since the previous render. */
  delta: number;
  /** Why this render happened: drawn elements repainted, the canvas resized, or an animation frame. */
  reason: "paint" | "resize" | "frame" | "request";
  /** Elements that repainted (from the paint event), when known. */
  changed: readonly Element[];
}

export interface UseHtmlCanvasOptions<C extends ContextType> {
  /** Context to draw with. */
  context: C;
  /** "auto" uses the API when available, "fallback" never does, "native" requires it. @default "auto" */
  mode?: HtmlCanvasMode;
  /** Run a render every frame while true (e.g. while a ripple is fading). Paused offscreen and in hidden tabs. */
  animating?: boolean;
  /** Called once per context (again after a lost context is restored). Return a cleanup. */
  setup?: (ctx: ContextFor<C>, canvas: HTMLCanvasElement) => void | (() => void);
  /** Draws a frame. Upload element textures only when `reason` is "paint" or "resize". */
  render: (frame: HtmlCanvasFrame<C>) => void;
  /** Highest device pixel ratio for the backing store. @default 2 */
  maxDpr?: number;
  /** Context attributes for WebGL. */
  contextAttributes?: WebGLContextAttributes;
}

export interface HtmlCanvasController {
  /** True when the canvas path is active; render the fallback DOM otherwise. */
  native: boolean;
  /** What the browser supports (none on the server and during hydration). */
  support: HtmlCanvasSupport;
  /** Ref for the <canvas>. */
  canvasRef: (canvas: HTMLCanvasElement | null) => void;
  /** Spread onto the <canvas> so it lays out and paints its children from the first layout. */
  canvasProps: Record<string, string>;
  /** Asks for one more render (and a browser paint event where supported). */
  invalidate: () => void;
}

const noop = () => () => {};

/**
 * Ties the HTML-in-Canvas adapter together: decides native vs. fallback (never during SSR or
 * hydration, never under reduced motion), prepares the canvas, renders on the canvas `paint` event
 * and on resize, runs a frame loop only while `animating`, pauses offscreen and in hidden tabs,
 * recovers from a lost WebGL context and cleans up on unmount.
 */
export function useHtmlCanvas<C extends ContextType>({
  context,
  mode = "auto",
  animating = false,
  setup,
  render,
  maxDpr = 2,
  contextAttributes,
}: UseHtmlCanvasOptions<C>): HtmlCanvasController {
  const hydrated = useSyncExternalStore(
    noop,
    () => true,
    () => false,
  );
  const reduceMotion = useReducedMotion();
  const support = hydrated ? getHtmlCanvasSupport() : NO_SUPPORT;
  const [failed, setFailed] = useState(false);
  const native = hydrated && !failed && mode !== "fallback" && !reduceMotion && supportsContext(support, context);

  // The element lives in a ref (it is mutated: size, attributes); the counter re-runs the effect when it changes.
  const canvasEl = useRef<HTMLCanvasElement | null>(null);
  const [canvasVersion, setCanvasVersion] = useState(0);
  const canvasRef = useCallback((el: HTMLCanvasElement | null) => {
    if (canvasEl.current === el) return;
    canvasEl.current = el;
    setCanvasVersion((v) => v + 1);
  }, []);
  const renderRef = useRef(render);
  const setupRef = useRef(setup);
  const animatingRef = useRef(animating);
  useLayoutEffect(() => {
    renderRef.current = render;
    setupRef.current = setup;
    animatingRef.current = animating;
  });
  const kick = useRef<(reason: HtmlCanvasFrame<C>["reason"]) => void>(() => {});

  useEffect(() => {
    const canvas = canvasEl.current;
    if (!native || !canvas) return;
    prepareDrawableCanvas(canvas);
    const ctx = canvas.getContext(context, context === "webgl2" ? { alpha: true, premultipliedAlpha: true, antialias: true, ...contextAttributes } : undefined) as ContextFor<C> | null;
    if (!ctx) {
      // Defer so the state change happens outside the effect body.
      const t = window.setTimeout(() => setFailed(true), 0);
      return () => window.clearTimeout(t);
    }
    let cleanupSetup: void | (() => void);
    let ready = false;
    const runSetup = () => {
      try {
        cleanupSetup = setupRef.current?.(ctx, canvas);
        ready = true;
      } catch (error) {
        console.error(error);
        ready = false;
        window.setTimeout(() => setFailed(true), 0);
      }
    };
    runSetup();

    const start = performance.now();
    // Frame time is measured between loop frames only, so the first frame after idling has a normal step.
    let lastFrame = 0;
    let size = { width: 0, height: 0, dpr: 1 };
    let visible = true;
    let frame = 0;
    let changed: readonly Element[] = [];

    const draw = (reason: HtmlCanvasFrame<C>["reason"]) => {
      if (!ready || !size.width || !size.height) return;
      const now = performance.now();
      const delta = reason === "frame" && lastFrame ? Math.min(1 / 20, (now - lastFrame) / 1000) : reason === "frame" ? 1 / 60 : 0;
      if (reason === "frame") lastFrame = now;
      try {
        renderRef.current({ ctx, canvas, width: size.width, height: size.height, dpr: size.dpr, time: (now - start) / 1000, delta, reason, changed });
      } catch (error) {
        console.error(error);
      }
      changed = [];
    };

    const loop = () => {
      frame = 0;
      if (!visible || document.hidden || !animatingRef.current) {
        lastFrame = 0;
        return;
      }
      draw("frame");
      frame = requestAnimationFrame(loop);
    };
    const ensureLoop = () => {
      if (!frame && visible && !document.hidden && animatingRef.current) frame = requestAnimationFrame(loop);
    };
    kick.current = (reason) => {
      draw(reason);
      ensureLoop();
    };

    const resize = () => {
      const rect = canvas.getBoundingClientRect();
      const dpr = Math.min(maxDpr, window.devicePixelRatio || 1);
      const width = Math.max(1, Math.round(rect.width));
      const height = Math.max(1, Math.round(rect.height));
      if (width === size.width && height === size.height && dpr === size.dpr) return;
      size = { width, height, dpr };
      canvas.width = Math.round(width * dpr);
      canvas.height = Math.round(height * dpr);
      draw("resize");
      requestCanvasPaint(canvas);
    };
    const resizeObserver = new ResizeObserver(resize);
    resizeObserver.observe(canvas);
    resize();

    const onPaint = (event: Event) => {
      changed = ((event as Event & { changedElements?: Element[] }).changedElements ?? []) as Element[];
      draw("paint");
      ensureLoop();
    };
    canvas.addEventListener("paint", onPaint);

    const io = new IntersectionObserver(([entry]) => {
      visible = entry?.isIntersecting ?? true;
      ensureLoop();
    });
    io.observe(canvas);
    const onVisibility = () => ensureLoop();
    document.addEventListener("visibilitychange", onVisibility);

    const onLost = (event: Event) => {
      event.preventDefault();
      ready = false;
      cancelAnimationFrame(frame);
      frame = 0;
    };
    const onRestored = () => {
      runSetup();
      draw("resize");
      requestCanvasPaint(canvas);
    };
    canvas.addEventListener("webglcontextlost", onLost);
    canvas.addEventListener("webglcontextrestored", onRestored);

    requestCanvasPaint(canvas);

    return () => {
      cancelAnimationFrame(frame);
      resizeObserver.disconnect();
      io.disconnect();
      canvas.removeEventListener("paint", onPaint);
      canvas.removeEventListener("webglcontextlost", onLost);
      canvas.removeEventListener("webglcontextrestored", onRestored);
      document.removeEventListener("visibilitychange", onVisibility);
      kick.current = () => {};
      if (typeof cleanupSetup === "function") cleanupSetup();
    };
    // contextAttributes and maxDpr are read once per canvas.
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [native, canvasVersion, context]);

  // Start or stop the loop when `animating` flips.
  useEffect(() => {
    if (animating) kick.current("frame");
  }, [animating]);

  const invalidate = useCallback(() => {
    kick.current("request");
    if (canvasEl.current) requestCanvasPaint(canvasEl.current);
  }, []);

  return { native, support, canvasRef, canvasProps: drawableCanvasAttributes(support), invalidate };
}

Copy the source

components/ui/liquid-glass-overlay/liquid-glass-overlay.tsx

"use client";

import { useEffect, useRef, useState, type ReactNode } from "react";
import { GripVertical } from "lucide-react";
import { cn } from "@/lib/utils";
import { createGrid, createProgram, drawMesh, PROJECT_GLSL, ROUND_RECT_GLSL, setMatrix, type Mesh, type Program } from "@/lib/html-canvas/gl";
import { createElementTexture, uploadElementTexture, type ElementTexture } from "@/lib/html-canvas/texture-webgl";
import { syncElementGeometry } from "@/lib/html-canvas/sync-geometry";
import { useHtmlCanvas, type HtmlCanvasMode } from "@/lib/html-canvas/use-html-canvas";

export interface LiquidGlassOverlayProps {
  /** The live content under the glass. */
  children: ReactNode;
  /** Real controls inside the glass, e.g. buttons. */
  toolbar: ReactNode;
  /** Starting position of the glass's top-left corner, in px within the content. @default { x: 24, y: 24 } */
  defaultPosition?: { x: number; y: number };
  /** How strongly the edges bend the content beneath, 0–1. @default 0.6 */
  refraction?: number;
  /** Accessible name for the toolbar. @default "Toolbar" */
  label?: string;
  /** "auto" uses HTML-in-Canvas when available, "fallback" never does. @default "auto" */
  rendering?: HtmlCanvasMode;
  /** Called when the rendering mode is known. */
  onModeChange?: (native: boolean) => void;
  /** Classes for the root. */
  className?: string;
}

const VERT = /* glsl */ `#version 300 es
in vec2 a_pos;
uniform vec2 u_size;
uniform mat4 u_matrix;
out vec2 v_uv;
${PROJECT_GLSL}
void main() {
  v_uv = a_pos;
  gl_Position = projectCss(u_matrix * vec4(a_pos * u_size, 0.0, 1.0));
}`;

const CONTENT_FRAG = /* glsl */ `#version 300 es
precision highp float;
in vec2 v_uv;
uniform sampler2D u_tex;
uniform vec2 u_size;
uniform vec4 u_glass;
uniform float u_refraction;
out vec4 outColor;
${ROUND_RECT_GLSL}

void main() {
  vec2 px = v_uv * u_size;
  vec2 half_ = u_glass.zw * 0.5;
  vec2 center = u_glass.xy + half_;
  float radius = min(half_.x, half_.y);
  vec2 p = px - center;
  float d = sdRoundRect(p, half_, radius);
  vec4 base = texture(u_tex, v_uv);
  if (d > 0.0) {
    // A soft shadow under the glass.
    float shadow = (1.0 - smoothstep(0.0, 18.0, sdRoundRect(p - vec2(0.0, 6.0), half_, radius))) * 0.16;
    outColor = vec4(base.rgb * (1.0 - shadow * base.a), max(base.a, shadow));
    return;
  }
  // Edge band: the content is pushed outward near the rim, more for red than for blue.
  float band = 1.0 - smoothstep(0.0, min(10.0, radius * 0.6), -d);
  float e = 0.01;
  vec2 grad = normalize(vec2(sdRoundRect(p + vec2(e, 0.0), half_, radius) - sdRoundRect(p - vec2(e, 0.0), half_, radius), sdRoundRect(p + vec2(0.0, e), half_, radius) - sdRoundRect(p - vec2(0.0, e), half_, radius)) + 1e-5);
  float bend = band * band * 14.0 * u_refraction;
  vec2 o = -grad * bend;
  float r = texture(u_tex, (px + o * 1.12) / u_size).r;
  float g = texture(u_tex, (px + o) / u_size).g;
  float b = texture(u_tex, (px + o * 0.88) / u_size).b;
  float a = texture(u_tex, (px + o) / u_size).a;
  vec3 col = mix(vec3(1.0), vec3(r, g, b), a);
  // Glass tint, a specular rim along the top and a faint inner edge.
  col = mix(col, vec3(1.0), 0.18);
  float rim = 1.0 - smoothstep(0.0, 1.6, -d);
  float top = smoothstep(0.2, -1.0, p.y / half_.y);
  col += rim * (0.35 + 0.4 * top);
  col += band * 0.06 * top;
  outColor = vec4(col, 1.0);
}`;

const TOOL_FRAG = /* glsl */ `#version 300 es
precision highp float;
in vec2 v_uv;
uniform sampler2D u_tex;
out vec4 outColor;
void main() { outColor = texture(u_tex, v_uv); }`;

/**
 * A draggable liquid-glass toolbar floating over live DOM content through HTML-in-Canvas: the content
 * beneath is refracted at the glass's edges with a chromatic fringe and a specular rim, while the
 * middle stays readable and the glass holds real buttons. Without the API, the glass is a
 * backdrop-filter blur with a gradient rim.
 */
export function LiquidGlassOverlay({ children, toolbar, defaultPosition = { x: 24, y: 24 }, refraction = 0.6, label = "Toolbar", rendering = "auto", onModeChange, className }: LiquidGlassOverlayProps) {
  const contentRef = useRef<HTMLDivElement>(null);
  const glassRef = useRef<HTMLDivElement>(null);
  const [pos, setPos] = useState(defaultPosition);
  const posRef = useRef(defaultPosition);
  const [height, setHeight] = useState<number | null>(null);
  const drag = useRef<{ dx: number; dy: number } | null>(null);
  const gl = useRef<{ content: Program; tool: Program; mesh: Mesh; tc: ElementTexture; tt: ElementTexture } | null>(null);

  const { native, canvasRef, canvasProps, invalidate } = useHtmlCanvas({
    context: "webgl2",
    mode: rendering,
    setup: (ctx) => {
      gl.current = { content: createProgram(ctx, VERT, CONTENT_FRAG), tool: createProgram(ctx, VERT, TOOL_FRAG), mesh: createGrid(ctx), tc: createElementTexture(ctx), tt: createElementTexture(ctx) };
      return () => {
        const g = gl.current;
        if (!g) return;
        ctx.deleteProgram(g.content.program);
        ctx.deleteProgram(g.tool.program);
        ctx.deleteTexture(g.tc.texture);
        ctx.deleteTexture(g.tt.texture);
        gl.current = null;
      };
    },
    render: ({ ctx, canvas, width, height: h, reason, changed }) => {
      const g = gl.current;
      const content = contentRef.current;
      const glass = glassRef.current;
      if (!g || !content || !glass) return;
      const at = new DOMMatrix().translate(posRef.current.x, posRef.current.y);
      const all = reason === "resize" || reason === "request" || !g.tc.width;
      if (all || changed.some((el) => el === content || content.contains(el))) {
        uploadElementTexture(ctx, g.tc, content);
        syncElementGeometry(canvas, content, new DOMMatrix());
      }
      if (all || changed.some((el) => el === glass || glass.contains(el))) uploadElementTexture(ctx, g.tt, glass);
      syncElementGeometry(canvas, glass, at);

      ctx.viewport(0, 0, canvas.width, canvas.height);
      ctx.clearColor(0, 0, 0, 0);
      ctx.clear(ctx.COLOR_BUFFER_BIT);
      ctx.enable(ctx.BLEND);
      ctx.blendFunc(ctx.ONE, ctx.ONE_MINUS_SRC_ALPHA);
      ctx.activeTexture(ctx.TEXTURE0);

      ctx.useProgram(g.content.program);
      ctx.uniform2f(g.content.u("u_canvas"), width, h);
      ctx.uniform2f(g.content.u("u_size"), width, h);
      setMatrix(ctx, g.content.u("u_matrix"), new DOMMatrix());
      ctx.uniform4f(g.content.u("u_glass"), posRef.current.x, posRef.current.y, glass.offsetWidth, glass.offsetHeight);
      ctx.uniform1f(g.content.u("u_refraction"), Math.max(0, Math.min(1, refraction)));
      ctx.bindTexture(ctx.TEXTURE_2D, g.tc.texture);
      ctx.uniform1i(g.content.u("u_tex"), 0);
      drawMesh(ctx, g.mesh);

      ctx.useProgram(g.tool.program);
      ctx.uniform2f(g.tool.u("u_canvas"), width, h);
      ctx.uniform2f(g.tool.u("u_size"), g.tt.width || glass.offsetWidth, g.tt.height || glass.offsetHeight);
      setMatrix(ctx, g.tool.u("u_matrix"), at);
      ctx.bindTexture(ctx.TEXTURE_2D, g.tt.texture);
      ctx.uniform1i(g.tool.u("u_tex"), 0);
      drawMesh(ctx, g.mesh);
    },
  });

  useEffect(() => onModeChange?.(native), [native, onModeChange]);

  useEffect(() => {
    const el = contentRef.current;
    if (!native || !el) return;
    const observer = new ResizeObserver(() => setHeight(el.offsetHeight));
    observer.observe(el);
    return () => observer.disconnect();
  }, [native]);

  const bounds = () => {
    const content = contentRef.current;
    const glass = glassRef.current;
    return { w: (content?.offsetWidth ?? 0) - (glass?.offsetWidth ?? 0), h: (content?.offsetHeight ?? 0) - (glass?.offsetHeight ?? 0) };
  };
  const moveTo = (x: number, y: number) => {
    const b = bounds();
    const next = { x: Math.max(0, Math.min(b.w, x)), y: Math.max(0, Math.min(b.h, y)) };
    posRef.current = next;
    setPos(next);
    invalidate();
  };

  const onPointerDown = (event: React.PointerEvent<HTMLDivElement>) => {
    // Buttons inside the glass keep their clicks; the rest of the glass drags it.
    if ((event.target as HTMLElement).closest("button:not([data-glass-handle]), a, input")) return;
    drag.current = { dx: event.clientX - posRef.current.x, dy: event.clientY - posRef.current.y };
    event.currentTarget.setPointerCapture(event.pointerId);
  };
  const onPointerMove = (event: React.PointerEvent<HTMLDivElement>) => {
    if (!drag.current) return;
    moveTo(event.clientX - drag.current.dx, event.clientY - drag.current.dy);
  };
  const onPointerUp = () => {
    drag.current = null;
  };
  const onHandleKey = (event: React.KeyboardEvent<HTMLButtonElement>) => {
    const step = event.shiftKey ? 40 : 10;
    const moves: Record<string, [number, number]> = { ArrowLeft: [-step, 0], ArrowRight: [step, 0], ArrowUp: [0, -step], ArrowDown: [0, step] };
    const m = moves[event.key];
    if (!m) return;
    event.preventDefault();
    moveTo(posRef.current.x + m[0], posRef.current.y + m[1]);
  };

  const glass = (
    <div
      ref={glassRef}
      role="toolbar"
      aria-label={label}
      onPointerDown={onPointerDown}
      onPointerMove={onPointerMove}
      onPointerUp={onPointerUp}
      onPointerCancel={onPointerUp}
      className={cn(
        "flex w-max cursor-grab touch-none items-center gap-1 rounded-full p-1.5 active:cursor-grabbing",
        native ? "" : "absolute border border-white/60 bg-white/35 shadow-[0_8px_24px_-8px_rgb(0_0_0/0.3),inset_0_1px_0_rgb(255_255_255/0.9)] backdrop-blur-md backdrop-saturate-150",
      )}
      style={native ? undefined : { left: pos.x, top: pos.y }}
    >
      <button
        type="button"
        data-glass-handle
        aria-label="Move toolbar (arrow keys)"
        onKeyDown={onHandleKey}
        className="relative after:absolute after:-inset-1 grid size-8 cursor-grab place-items-center rounded-full text-foreground/60 outline-none focus-visible:ring-2 focus-visible:ring-ring"
      >
        <GripVertical className="size-4" aria-hidden="true" />
      </button>
      {toolbar}
    </div>
  );

  if (!native) {
    return (
      <div className={cn("relative w-full", className)}>
        <div ref={contentRef}>{children}</div>
        {glass}
      </div>
    );
  }

  return (
    <div className={cn("relative w-full", className)} style={{ height: height ?? undefined }}>
      <canvas ref={canvasRef} {...canvasProps} className="absolute inset-0 block size-full">
        <div ref={contentRef} className="w-full">
          {children}
        </div>
        {glass}
      </canvas>
    </div>
  );
}

Usage

import { LiquidGlassOverlay } from "@/components/ui/liquid-glass-overlay/liquid-glass-overlay";

<LiquidGlassOverlay
  toolbar={<><button aria-label="Bold">B</button><button aria-label="Italic">I</button></>}
>
  <Article />
</LiquidGlassOverlay>

API reference

Prop	Type	Default	Description
`children*`	`ReactNode`	–	The live content under the glass.
`toolbar*`	`ReactNode`	–	Real controls inside the glass, e.g. buttons.
`defaultPosition`	`{ x: number; y: number }`	`{ x: 24, y: 24 }`	Starting position of the glass's top-left corner, in px within the content.
`refraction`	`number`	`0.6`	How strongly the edges bend the content beneath, 0–1.
`label`	`string`	`"Toolbar"`	Accessible name for the toolbar.
`rendering`	`HtmlCanvasMode`	`"auto"`	"auto" uses HTML-in-Canvas when available, "fallback" never does.
`onModeChange`	`(native: boolean) => void`	–	Called when the rendering mode is known.
`className`	`string`	–	Classes for the root.

Experimental: uses the HTML-in-Canvas origin trial through src/lib/html-canvas/. Works in every browser via the fallback.
Refraction happens only in a band along the rim (shaped by the glass's signed distance field), with red bent a little more than blue; the middle is tinted but undistorted so it stays readable.
Moving the glass only redraws; the content and toolbar textures are re-uploaded only when they repaint.

Accessibility

The glass is a labelled role="toolbar" of real buttons. Its grip is a button that moves the glass with the arrow keys (Shift for bigger steps).
The content beneath stays live: text can be selected and links followed around and under the glass, since only the glass's own buttons sit on top.
With reduced motion, or without the HTML-in-Canvas API, the glass is a backdrop-filter blur with a gradient rim and stays draggable.

Notes from the glass studio

Installation#

CLI

Manual

Install the dependencies

Add the shared helpers

Copy the source

Usage#

API reference#

Accessibility#

Notes from the glass studio

Installation

Usage

API reference

Accessibility