A React component for creating liquid glass morphism effects with customizable distortion and blur
npm install simple-liquid-glassrgba, hsla, hex with alpha)
bash
npm install simple-liquid-glass
`
or with yarn:
`bash
yarn add simple-liquid-glass
`
Usage
$3
`jsx
import React from 'react';
import { LiquidGlass } from 'simple-liquid-glass';
function App() {
return (
Your Content Here
This content has a liquid glass effect!
);
}
`
$3
`jsx
import React from 'react';
import { LiquidGlass } from 'simple-liquid-glass';
function App() {
return (
mode="custom"
scale={200}
radius={20}
border={0.1}
lightness={60}
displace={0.5}
alpha={0.8}
blur={10}
dispersion={30}
frost={0.2}
background="linear-gradient(45deg, #ff6b6b, #4ecdc4)"
autoTextColor
textOnDark="#ffffff"
textOnLight="#111111"
forceTextColor
borderColor="rgba(255, 255, 255, 0.5)"
className="my-glass-container"
style={{ boxShadow: '0 8px 32px rgba(0, 0, 0, 0.1)' }}
>
Custom Glass Effect
Fully customized liquid glass morphism with gradient background
);
}
`
$3
The component comes with a beautiful preset that works out of the box:
`jsx
`
Note: In preset mode, incoming props still override the preset defaults (e.g., scale, radius, blur, etc.).
On iOS, when iosBlurMode is 'auto', a minimal blur (iosMinBlur, default 7px) is applied even if blur is 0 to ensure a visible fallback effect.
The background prop automatically converts solid colors and gradients to semi-transparent (30% opacity) for better glass effects. Images (URLs) are left unchanged.
Props
| Prop | Type | Default | Description |
|------|------|---------|-------------|
| children | ReactNode | - | Content to display inside the glass effect |
| mode | 'preset' \| 'custom' | 'preset' | Use preset values or custom configuration |
| scale | number | 160 | Scale of the displacement effect (-360 to 360) |
| radius | number | 50 | Border radius of the glass effect |
| border | number | 0.05 | Border thickness (0 to 0.5) |
| lightness | number | 53 | Lightness of the glass (0 to 100) |
| displace | number | 5 | Displacement blur amount (0 to 10) |
| alpha | number | 0.9 | Alpha transparency (0 to 1) |
| blur | number | 0 | Blur amount for the glass effect |
| dispersion | number | 50 | Chromatic dispersion amount |
| saturation | number | 140 | Color saturation multiplier (%) applied via CSS saturate() |
| aberrationIntensity | number | 0 | Multiplier for chromatic aberration (red/blue separation) |
| frost | number | 0.1 | Frost effect intensity (0 to 1) |
| borderColor | string | 'rgba(120, 120, 120, 0.7)' | Border color in CSS format |
| glassColor | string | 'rgba(255, 255, 255, 0.4)' | Semi‑transparent glass color (rgba, hsla, hsl(.../a), #RGBA, #RRGGBBAA). Invalid/opaque values fall back to frost‑based default |
| background | string | - | Background color or gradient (automatically made semi-transparent) |
| autoTextColor | boolean | false | Automatically detect background luminance and set text color |
| textOnDark | string | '#ffffff' | Text color used when background is detected as dark |
| textOnLight | string | '#111111' | Text color used when background is detected as light |
| forceTextColor | boolean | false | Force the computed text color on all descendants (!important) to override nested styles |
| className | string | - | Additional CSS class names |
| style | CSSProperties | - | Additional inline styles |
| quality | 'low' \| 'standard' \| 'high' \| 'extreme' | 'low' | Rendering quality preset. 'extreme' matches previous versions' visuals |
| autodetectquality | boolean | false | Auto-detect device performance and pick a quality preset |
| mobileFallback | 'css-only' \| 'svg' | CSS-only on mobile | Control mobile rendering strategy |
| effectMode | 'auto' \| 'svg' \| 'blur' \| 'off' | 'auto' | Control effect: auto, force SVG, force CSS blur, or disable |
Examples
$3
`jsx
background="linear-gradient(45deg, #ff6b6b, #4ecdc4)"
autoTextColor
>
Gradient Background
This uses a gradient background that's automatically made semi-transparent!
`
$3
`jsx
// Manual quality
// Autodetect device performance and choose quality automatically
// Note:
// - Default quality is 'low'.
// - 'extreme' produces the same visual fidelity as previous versions of this component.
// - For many instances on the same page, prefer quality='low' or autodetectquality.
`
$3
`jsx
// Force CSS-only (strongest performance) even on desktop
// Force SVG filter on mobile (may impact performance)
// Default behavior: CSS-only on mobile, SVG on desktop
`
Performance and Fallbacks
- Default behavior: on mobile devices the component uses a CSS-only effect to avoid jank; on desktop it uses the SVG filter.
- Quality presets: 'low' is the default and optimized for many instances; 'extreme' matches previous visuals.
- Autodetection: set autodetectquality to let the component choose a preset based on device performance.
- Effect Mode: use effectMode to force the strategy.
`jsx
// Force CSS-only blur (no SVG) — recommended on very low-end devices
// Disable all filter effects (keeps border/frost/background)
// Force SVG filter everywhere
`
$3
`jsx
// Force pure CSS blur (no SVG) — ideal per dispositivi molto low-end
// Disattiva totalmente l'effetto (mantiene solo saturazione/frost)
// Forza sempre l'SVG
// Selezione automatica (default)
`
$3
`jsx
width: '350px',
height: '200px'
}}>
radius={15}
frost={0.15}
autoTextColor
background="linear-gradient(135deg, #667eea 0%, #764ba2 100%)"
>
Glass Card
This is a beautiful glass morphism card with liquid distortion effects and gradient background.
$3
`jsx
position: 'absolute',
top: '50%',
left: '50%',
transform: 'translate(-50%, -50%)',
width: '300px',
height: '150px'
}}>
Overlay Content
Glass effect over image
Browser Support
- Chrome (latest)
- Firefox (latest)
- Safari (latest)
- Edge (latest)
The component leverages modern CSS (backdrop-filter) and SVG filters. Older browsers may not support all effects.
Performance Tips
1. The component uses ResizeObserver to adapt to size changes efficiently
2. SVG filters are hardware-accelerated in modern browsers
3. For best performance, avoid animating the glass parameters rapidly
4. Use the preset mode for optimal default settings
Accessibility
- autoTextColor uses computed styles from the nearest opaque ancestor to decide between textOnDark and textOnLight. This helps maintain readable contrast automatically. You can set forceTextColor to enforce the computed color on deeply nested content.
Storybook
Run a live playground:
`bash
npm run storybook
`
Switch the Backgrounds toolbar between light/dark to see text color adapt in real time.
License
MIT © [lucaperullo]
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature`)