@rethink-js/rt-liquid-glass
v1.0.1
Published
Rethink JS utility to apply an attribute-driven liquid glass effect (with SVG displacement + backdrop-filter, and safe fallbacks).
Maintainers
druhin13Readme
rt-liquid-glass
rt-liquid-glass is a lightweight JavaScript utility that applies an attribute-driven liquid glass effect using SVG displacement maps and CSS backdrop filters, with safe fallbacks for unsupported browsers, featuring:
- Zero-config defaults (works out of the box)
- Attribute-driven configuration
- Automatic browser feature detection
- Defensive fallbacks (never crashes your page)
- Support for multiple elements
- A clean global API under
window.rtLiquidGlass - Safe degradation on unsupported browsers
- Clear console logs for debugging and verification
Primary inspiration:
https://www.ekino.fr/publications/liquid-glass-in-css-and-svg/
Table of Contents
- 1. Installation
- 2. Quick Start
- 3. Activation Rules
- 4. Configuration (HTML Attributes)
- 5. Multiple Elements
- 6. Global API
- 7. Console Logging
- 8. Troubleshooting
- 9. License
1. Installation
1.1 CDN (jsDelivr)
<script src="https://cdn.jsdelivr.net/npm/@rethink-js/rt-liquid-glass@latest/dist/index.min.js"></script>1.2 npm
npm install @rethink-js/rt-liquid-glassThen bundle or load dist/index.min.js as appropriate for your build setup.
2. Quick Start
Add the script to your page. With no configuration provided, rt-liquid-glass will:
- Auto-initialize itself when applicable
- Detect browser capabilities
- Apply safe defaults
- Fallback gracefully when unsupported
- Expose the global API
Example:
<div rt-liquid-glass>Liquid Glass Panel</div>
<script src="https://cdn.jsdelivr.net/npm/@rethink-js/rt-liquid-glass@latest/dist/index.min.js"></script>Note: If you do not provide any
rt-liquid-glass-*attributes, the library runs using its internal defaults.
3. Activation Rules
The library activates when any of the following are true:
- One or more elements with
rt-liquid-glassare detected - A root activation attribute exists on
<html>or<body> - No explicit opt-out is defined (auto-enable fallback)
If none are found, the library will not run.
4. Configuration (HTML Attributes)
Core Activation
<div rt-liquid-glass></div>Disable on Specific Elements
<div rt-liquid-glass="false"></div>Core Attributes
| Attribute | Description |
| --------------------------------- | ---------------------------------- |
| rt-liquid-glass | Enables the effect |
| rt-liquid-glass="false" | Disables effect |
| rt-liquid-glass-debug | Enable console logging |
| rt-liquid-glass-disable-firefox | Disable SVG liquid mode on Firefox |
Visual Controls
| Attribute | Description |
| ------------------------------- | ---------------------------------- |
| rt-liquid-glass-blur | Gaussian blur amount (px) |
| rt-liquid-glass-scale | Displacement intensity |
| rt-liquid-glass-map | Resolution cap for SVG map |
| rt-liquid-glass-fallback-blur | Fallback blur when SVG is disabled |
Example:
<div
rt-liquid-glass
rt-liquid-glass-blur="12"
rt-liquid-glass-scale="40"
rt-liquid-glass-map="256"
></div>Reveal Animation
Reveal animation is opacity-based and optional.
<div rt-liquid-glass rt-liquid-glass-reveal></div>Custom duration:
<div rt-liquid-glass rt-liquid-glass-reveal="1.5s"></div>Global Styling Overrides
| Attribute | Description |
| ------------------------------------- | ------------------------------- |
| rt-liquid-glass-base-bg | Background color |
| rt-liquid-glass-transition-ms | Transition duration |
| rt-liquid-glass-observe-threshold | IntersectionObserver threshold |
| rt-liquid-glass-observe-root-margin | IntersectionObserver rootMargin |
Advanced JSON Options
<body
rt-liquid-glass
rt-liquid-glass-options-json='{"blur":12,"scale":50}'
></body>Used for advanced or programmatic configuration.
5. Multiple Elements
rt-liquid-glass automatically supports multiple elements on the same page.
Each element:
- Is measured independently
- Gets its own SVG displacement filter
- Has isolated configuration
- Degrades independently if unsupported
No additional setup is required.
6. Global API
Once initialized:
window.rtLiquidGlass;Methods
| Method | Description |
| ----------- | ------------------------------ |
| refresh() | Re-scan and reapply effects |
| destroy() | Remove styles, observers, SVGs |
Feature Flags
rtLiquidGlass.isLiquidEnabled();
rtLiquidGlass.supportsBackdrop();7. Console Logging
When enabled via:
<body rt-liquid-glass-debug></body>The library logs:
- Browser capability detection
- Liquid vs fallback mode
- Global resolved options
- Runtime activation state
8. Troubleshooting
Effect not visible
- Ensure
backdrop-filteris supported - Check Firefox fallback behavior
- Verify the element has a visible background
- Ensure there's content behind the glass
Looks like a normal blur
This means SVG displacement is disabled due to:
- Browser limitations
- Firefox protection
- Manual fallback
This is expected and intentional.
Nothing happens
- Ensure the script loaded
- Check console for logs
- Confirm attribute spelling
9. License
MIT License
Package: @rethink-js/rt-liquid-glass
GitHub: https://github.com/Rethink-JS/rt-liquid-glass
by Rethink JS https://github.com/Rethink-JS