# rt-liquid-glass
[](https://www.npmjs.com/package/@rethink-js/rt-liquid-glass)
[](https://www.jsdelivr.com/package/npm/@rethink-js/rt-liquid-glass)
[](https://bundlephobia.com/package/@rethink-js/rt-liquid-glass)
[](https://opensource.org/licenses/MIT)
`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](#1-installation)
- [1.1 CDN (jsDelivr)](#11-cdn-jsdelivr)
- [1.2 npm](#12-npm)
- [2. Quick Start](#2-quick-start)
- [3. Activation Rules](#3-activation-rules)
- [4. Configuration (HTML Attributes)](#4-configuration-html-attributes)
- [5. Multiple Elements](#5-multiple-elements)
- [6. Global API](#6-global-api)
- [7. Console Logging](#7-console-logging)
- [8. Troubleshooting](#8-troubleshooting)
- [9. License](#9-license)
---
## 1. Installation
### 1.1 CDN (jsDelivr)
```html
```
### 1.2 npm
```bash
npm install @rethink-js/rt-liquid-glass
```
Then 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:
```html
Liquid Glass Panel
```
> 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-glass` are detected
- A root activation attribute exists on `` or ``
- No explicit opt-out is defined (auto-enable fallback)
If none are found, the library will not run.
---
## 4. Configuration (HTML Attributes)
### Core Activation
```html
```
### Disable on Specific Elements
```html
```
---
### 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:
```html
```
---
### Reveal Animation
Reveal animation is opacity-based and optional.
```html
```
Custom duration:
```html
```
---
### 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
```html
```
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:
```js
window.rtLiquidGlass;
```
### Methods
| Method | Description |
| ----------- | ------------------------------ |
| `refresh()` | Re-scan and reapply effects |
| `destroy()` | Remove styles, observers, SVGs |
---
### Feature Flags
```js
rtLiquidGlass.isLiquidEnabled();
rtLiquidGlass.supportsBackdrop();
```
---
## 7. Console Logging
When enabled via:
```html
```
The library logs:
- Browser capability detection
- Liquid vs fallback mode
- Global resolved options
- Runtime activation state
---
## 8. Troubleshooting
### Effect not visible
- Ensure `backdrop-filter` is 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](https://github.com/Rethink-JS/rt-liquid-glass)
---
by **Rethink JS**
[https://github.com/Rethink-JS](https://github.com/Rethink-JS)