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/
- 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
<script src="https://cdn.jsdelivr.net/npm/@rethink-js/rt-liquid-glass@latest/dist/index.min.js"></script>npm install @rethink-js/rt-liquid-glassThen bundle or load dist/index.min.js as appropriate for your build setup.
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.
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.
<div rt-liquid-glass></div><div rt-liquid-glass="false"></div>| 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 |
| 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 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>| 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 |
<body
rt-liquid-glass
rt-liquid-glass-options-json='{"blur":12,"scale":50}'
></body>Used for advanced or programmatic configuration.
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.
Once initialized:
window.rtLiquidGlass;| Method | Description |
|---|---|
refresh() |
Re-scan and reapply effects |
destroy() |
Remove styles, observers, SVGs |
rtLiquidGlass.isLiquidEnabled();
rtLiquidGlass.supportsBackdrop();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
- Ensure
backdrop-filteris supported - Check Firefox fallback behavior
- Verify the element has a visible background
- Ensure there's content behind the glass
This means SVG displacement is disabled due to:
- Browser limitations
- Firefox protection
- Manual fallback
This is expected and intentional.
- Ensure the script loaded
- Check console for logs
- Confirm attribute spelling
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