DOCSEARCHbyAlgolia
Submit Docs

liquidGL Documentation

repository·main·Indexed 20 days ago

https://github.com/naughtyduk/liquidgl

An ultra-light WebGL-based library for creating high-quality glassmorphism effects, including refraction, bevels, and chromatic aberration, for any DOM element. It features an offscreen rendering technique for real-time refraction of dynamic content, built-in rasterization (v2.0.1), and synchronization support for smooth-scrolling libraries like Lenis and Locomotive Scroll.

Tokens
6.4K
Snippets
17
Records
29
Agent score
23%

What's inside liquidGL

  1. Configure `z-index` for `shadow` and `tilt` effects

    main

    When using the shadow or tilt effects, liquidGL creates new stacking layers behind your target element:

    • shadow is placed at z-index: -2
    • tilt helper canvas is placed at z-index: -1

    Ensure your target element's z-index is high enough to allow these layers to exist behind it without being clipped or causing overflow issues.

  2. Manage multiple glass elements and `z-index` constraints

    main

    You can apply the glass effect to multiple elements on a single page by using the same class defined as your target.

    Critical Constraint: All target elements must use the same z-index. Because liquidGL uses a shared canvas for all instances to optimize performance and prevent WebGL context issues, it cannot handle multiple different z-index values for targets. If you provide different values, liquidGL will default to using the highest z-index for all of them.

  3. Exclude elements from refraction using `data-liquid-ignore`

    main

    To prevent specific elements (like preloaders or UI overlays) from being captured in the background snapshot and appearing inside the glass effect, add the data-liquid-ignore attribute to their top-level container.

    This is particularly useful when using preloaders or page animations to ensure the 'snapshot' of the background only contains the intended content.

    `<div data-liquid-ignore>...</div>`

  4. Install liquidGL via npm

    main

    As of v2.0.1, liquidGL is available as an npm package. You can install it using the following command:

    npm install liquid-gl

    Note that the package/ directory in the repository contains the source and is not required if you are using the CDN or a browser script.

  5. Quick start: Set up the HTML structure

    main

    To create a glass effect, you need a specific HTML hierarchy:

    1. A target element: This is the element that will receive the glass/refraction effect. It should have a high z-index so it sits over your page content.
    2. A content child element: This contains the actual content (text, images, etc.) that will appear on top of the glass and will not be affected by the refraction.

    Any content with a higher z-index than the target will be excluded from the lens (e.g., a modal window).

    <!-- Example HTML structure -->
<body>
  <!-- Target (glassified) -->
  <div class="liquidGL">
    <!-- Content -->
    <div class="content">
      <img src="/example.svg" alt="Alt Text" />
      <p>This example text content will appear on top of the glass.</p>
    </div>
  </div>
</body>

  6. Best practices for content visibility and legibility

    main

    To ensure text and UI elements inside your glass container remain readable:

    1. Set the content inside your target element to z-index: 3; so it sits on top of the lens.
    2. Consider using mix-blend-mode: difference; on the content for improved legibility against the refracted background.

  7. Install liquidGL via CDN/Browser Script

    main

    To use liquidGL directly in the browser, include the library script before you initialize the effect (typically at the end of your <body> tag).

    liquidGL has no runtime dependencies. Since v2.0.1, it includes a built-in rasteriser, so you do not need to include html2canvas.

    <!-- liquidGL.js – the library itself -->
<script src="/scripts/liquidGL.js" defer></script>

  8. Optimize performance with specific snapshots

    main

    On complex pages, instead of snapshotting the entire document (which can exceed GPU texture limits or cause performance issues), you can limit the snapshot area to a specific container. Use the snapshot option in your configuration with a CSS selector.

    Example: snapshot: '.my-background'

  9. How dynamic elements and lenses work together

    main

    LiquidGL works by taking a snapshot of a snapshotTarget and uploading it as a WebGL texture. However, static snapshots cannot capture moving parts like <video> elements or CSS animations.

    To solve this, liquidGL uses a Dynamic Element system:

    1. Registration: You call addDynamicElement(el) for any element that moves or changes.
    2. Monitoring: LiquidGL attaches listeners for transitionrun, animationstart, and other lifecycle events to detect when an element is 'active'.
    3. Compositing: During the render() loop, liquidGL captures the current frame of the dynamic element (using a temporary canvas or direct video blitting) and composites it onto the main WebGL texture.
    4. Layering: The library ensures that the zIndex of the glass canvas is managed so that lenses appear correctly relative to the elements they are masking.

  10. How liquidGL works (Internal Architecture)

    main

    liquidGL is an ultra-light glassmorphism library that achieves its effects by recreating the DOM's visual state on a WebGL or Canvas context.

    It uses a custom internal engine called NaughtyDOM to:

    1. Traverse the DOM: It builds a tree of node objects that mirror the actual DOM elements, capturing their computed styles (colors, gradients, transforms, radii, etc.).
    2. Handle Layout & Transforms: It parses CSS matrices and transforms to calculate the exact position, size, and orientation of elements in a coordinate system suitable for drawing.
    3. Render Visuals: A Painter object uses a CanvasRenderingContext2D (or WebGL via the library's higher-level API) to draw shadows, backgrounds, and gradients that match the CSS specifications.
    4. Asset Management: It automatically discovers and loads assets like background-image URLs and converts inline SVG elements into usable images for the rendering pipeline.

  11. How the NaughtyDOM engine parses CSS properties

    main

    The NaughtyDOM component is responsible for translating CSS values into drawing instructions. Key capabilities include:

    • Gradients: Supports linear-gradient, radial-gradient, and conic-gradient (where supported), including repeating- variants. It parses color stops, angles (deg, grad, rad, turn), and positions.
    • Transforms: Parses matrix() and matrix3d() strings to handle element positioning and scaling.
    • Box Model: Calculates dimensions and radii based on box-sizing (e.g., border-box vs content-box), padding, and border-width.
    • Shapes & Radii: Handles complex border-radius values and ensures they are correctly inset when dealing with padding or borders.
    • Assets: Automatically detects and caches <img> sources and converts <svg> elements into data URIs for rendering.

  12. How liquidGLRenderer works

    main

    The liquidGLRenderer is the core class used to create glassmorphism effects. It works by:

    1. Creating a full-screen WebGL2 (or WebGL) canvas that sits behind your content.
    2. Taking a high-resolution snapshot of a target DOM element (the snapshotTarget).
    3. Using that snapshot as a texture in a WebGL shader.
    4. Rendering 'lenses' (glass elements) on top of the canvas that apply refraction, frost, and aberration effects based on the underlying snapshot texture.

    When you initialize it, it automatically handles resizing, scrolling, and capturing the background content to ensure the glass effect matches the current state of the UI.

    const renderer = new liquidGLRenderer('.your-snapshot-target-selector', 1.0);