# ð§ LiquidGlass
**Real liquid glass for React. One component. Every prop.**
Pure actual refraction, not a blurred rectangle.
[](https://www.npmjs.com/package/liquid-glass-component)
[](LICENSE)
[](#)
[](#)
**[âķ Live playground](https://exist08.github.io/liquid-glass-component/)** · [Install](#install) · [API](#props) · [Recipes](#recipes)
---
## Why LiquidGlass?
- ð **Real refraction**, not a frosted rectangle.
- ðïļ **One component, every prop** â shape, tint, blur, noise type, scale, hover scale, wobble, drag, âĶ
- ðŠķ **~3 KB gzipped** with zero runtime dependencies beyond React.
- 𧎠**Polymorphic** â render as `button`, `a`, `div`, or any element via `as`.
- ðŊ **Typed** â full TypeScript definitions, props are inferred.
- âŋ **Accessible** â preserves native focus, keyboard, and ARIA behaviour of the underlying element.
---
## Install
```bash
npm install liquid-glass-component
# or
pnpm add liquid-glass-component
# or
yarn add liquid-glass-component
```
> Requires **React 18+**. No build step. No CSS file to import.
---
## Quick start
```tsx
import { LiquidGlass } from 'liquid-glass-component'
export default function App() {
return (
console.log('clicked')}>
Click me
)
}
```
That's it â defaults give you a frosted pill button with subtle warp on hover.
### Customized
```tsx
Nebula
```
> ðĄ Open the [live playground](./demo.html) to dial in every prop visually and copy the generated TSX.
---
## Recipes
Drop-in presets that match the swatches in the playground.
```tsx
// ⊠White â neutral glass
White
// âŦ Black â dark glass
Black
// ð Ember â warm amber
Ember
// ðĢ Nebula â deep purple
Nebula
// ðĒ Venom â toxic green, ridged noise
Venom
// ðŪ Crystal â high-displacement, thin rim
Crystal
// ðĨ Wobble â circle that breathes
ðĨ
// ð As a nav link
About
```
---
## Props
### Shape
| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `variant` | `"pill" \| "rounded" \| "circle" \| "squircle" \| "sharp"` | `"pill"` | Border-radius preset |
| `radius` | `string \| number` | â | Override `border-radius` directly |
### Glass surface
| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `tint` | `string` | `"rgba(255,255,255,0.10)"` | Fill color over the displaced backdrop |
| `blur` | `number` | `0` | `backdrop-filter` blur in px. `0` = pure displacement |
| `saturate` | `number` | `1.2` | `backdrop-filter` saturate multiplier |
### Displacement (the liquid part)
| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `scale` | `number` | `20` | Warp intensity at rest |
| `hoverScale` | `number` | `scale * 1.9` | Warp on hover |
| `noiseType` | `"fbm" \| "perlin" \| "ridged" \| "curl" \| "value"` | `"fbm"` | Noise algorithm |
| `frequency` | `number` | `4` | Noise frequency â lower = bigger waves |
| `octaves` | `number` | `4` | fBm octave count (detail layers) |
| `persistence` | `number` | `0.5` | Amplitude decay per octave |
| `lacunarity` | `number` | `2` | Frequency growth per octave |
| `seed` | `number` | `42` | Noise seed â change for different patterns |
| `textureSize` | `number` | `128` | Texture resolution in px |
### Surface details
| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `rim` | `string` | `"rgba(255,255,255,0.20)"` | Border color |
| `rimWidth` | `number` | `1` | Border width in px |
| `specular` | `boolean` | `true` | Top-edge highlight |
| `specularColor` | `string` | `"rgba(255,255,255,0.22)"` | Highlight color |
| `shadow` | `string` | â | `box-shadow` value |
### Animation
| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `animate` | `boolean` | `true` | Lerp `scale` on hover |
| `wobble` | `boolean` | `false` | CSS scale wobble loop |
| `wobbleDuration` | `number` | `4` | Wobble period in seconds |
### Sizing & element
| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `padding` | `string` | `"14px 32px"` | CSS padding |
| `width` | `string \| number` | â | Fixed width |
| `height` | `string \| number` | â | Fixed height |
| `fullWidth` | `boolean` | `false` | Stretch to container width |
| `as` | `ElementType` | `"button"` | Render as any element |
> All standard HTML attributes (`onClick`, `disabled`, `href`, `className`, `style`, `aria-*`, âĶ) are forwarded to the underlying element.
---
## Noise types
Each noise generates a different displacement texture. The R channel drives X-displacement, G drives Y.
| Type | Personality | Best for |
|------|-------------|----------|
| `fbm` | Layered fractal â natural liquid feel | Default, almost everything |
| `perlin` | Smooth gradient noise | Gentle, ambient waves |
| `ridged` | Sharp ridges | Volcanic, aggressive, "venom" looks |
| `curl` | Swirling vortex | Soap bubbles, holographic |
| `value` | Blocky | Coarse frosted glass |
---
## Performance
- The SVG filter is generated **once per instance** and reused â no per-frame canvas work.
- Hover/wobble animations are CSS-driven or use a single `requestAnimationFrame` lerp loop.
- Texture size defaults to **128 px** â large enough for high-DPI screens, small enough for GPU upload to be free.
- The whole package is **tree-shakable ESM**.
---
## Browser support
`backdrop-filter: url(#svg-filter)` requires a modern engine:
| Browser | Min version |
|---------|-------------|
| Chrome / Edge | 85+ |
| Safari (macOS / iOS) | Not Yet |
| Firefox | 103+ |
On older browsers, the glass gracefully degrades to a tinted rectangle (no warp).
---
## License
[MIT](LICENSE) â free for personal and commercial use.
---
Built with âĪïļ for the future of liquid glassmorphism.
Open the live playground â