liquid-glass-backdrop-react

✨ SVG-based liquid glass for React using backdrop-filter: url(#...).

The component generates displacement and specular maps from a physical model (thickness, IOR, bezel), then applies them through an SVG filter chain.

• ✅ Full effect: Chromium / Edge
• ↩️ Fallback effect: Safari / Firefox (frosted approximation)

Jump to

• Install
• Exports
• Quick usage
• API
• Browser behavior
• Performance notes
• Accessibility
• Security

📦 Install

npm install liquid-glass-backdrop-react

• Peer dependencies: react and react-dom >= 18
• Import styles once:

import 'liquid-glass-backdrop-react/style.css'

🧩 Exports

| Export | Description | | --- | --- | | LiquidGlass | forwardRef host component. variant="surface" renders a div; variant="button" renders a styled button. | | LiquidGlassButton | Convenience wrapper around LiquidGlass with variant="button". | | Types | LiquidGlassProps, LiquidGlassButtonProps, LiquidGlassOptics, SurfaceKey, blend-mode unions. |

🚀 Quick usage

import { LiquidGlassButton } from 'liquid-glass-backdrop-react'
import 'liquid-glass-backdrop-react/style.css'

export function Cta() {
  return (
    <LiquidGlassButton type="button" glassThickness={400} uiScale={1.2}>
      Continue
    </LiquidGlassButton>
  )
}

Surface wrapper example

import { LiquidGlass } from 'liquid-glass-backdrop-react'
import 'liquid-glass-backdrop-react/style.css'

export function Card() {
  return (
    <LiquidGlass
      variant="surface"
      className="my-card"
      glassThickness={200}
      refractionScale={0.75}
    >
      <h2>Title</h2>
      <p>Content behind the glass sees refraction + specular.</p>
    </LiquidGlass>
  )
}

.my-card {
  width: min(100%, 420px);
  min-height: 200px;
  padding: 1.5rem;
  border-radius: 24px;
}

🍱 Common recipes

1) Subtle card glass

<LiquidGlass
  variant="surface"
  className="card"
  glassThickness={120}
  refractionScale={0.55}
  blurStdDev={0.35}
  colorSaturate={1.1}
  specularOpacity={0.28}
  specularRimBlur={0.7}
/>

2) Bold CTA pill

<LiquidGlassButton
  uiScale={1.15}
  glassThickness={260}
  refractionScale={0.95}
  specularOpacity={0.58}
  specularTonePower={1.35}
>
  Get Started
</LiquidGlassButton>

3) Cool blue tint

<LiquidGlass
  variant="surface"
  tintColor="#88aaff"
  tintOpacity={0.18}
  tintBlendMode="soft-light"
/>

🎛️ Visual model (how it works)

1. blurStdDev controls feGaussianBlur on the backdrop input.
2. A generated R/G map drives feDisplacementMap (refraction).
3. colorSaturate applies via feColorMatrix.
4. A specular map is blended using specularBlendMode.
5. Optional tint uses feFlood + feComposite or feBlend.

Maps regenerate on host resize and when optical props change.

Tip: avoid transform: scale() on the host for sizing. The map generator uses layout size (offsetWidth / offsetHeight), so layout-driven sizing is more stable.

API

Surface profile options

| surface value | Shape profile | | --- | --- | | convex_squircle | Smooth convex squircle rim (default) | | convex_circle | Circular convex profile | | concave | Concave bowl-like profile | | lip | Blended convex/concave lip profile |

Optical props

| Prop | Default | Meaning | | --- | --- | --- | | surface | 'convex_squircle' | Cross-section profile used for displacement generation. | | glassThickness | 150 | Refraction model thickness (abstract model units). | | refractiveIndex | 1.5 | IOR in the model; higher values increase bend strength. | | bezelRatio | 0.42 | Relative bezel width before min/max clamping. | | bezelMinPx | 6 | Minimum bezel width in px. | | bezelMaxPx | 32 | Maximum bezel width in px. | | refractionScale | 0.82 | Multiplier on final displacement strength. | | blurStdDev | 0.5 | feGaussianBlur stdDeviation on backdrop input. | | colorSaturate | 1.3 | Saturation factor (1 means unchanged). | | specularOpacity | 0.48 | Alpha slope for specular layer. | | specularAngleDeg | -60 | Light direction angle in degrees (0 = +X). | | specularRimBlur | 0.55 | Blur for specular map softening. | | specularTonePower | 1.12 | Tone exponent (higher = sharper highlights). | | specularBlendMode | 'screen' | Blend mode for specular over refracted layer. | | tintColor | '#88aaff' | Tint flood color. | | tintOpacity | 0 | Tint amount (0 disables tint). | | tintBlendMode | 'over' | Tint compositing mode (over uses feComposite). | | uiScale | 1 | CSS --lg-scale for button chrome sizing. |

Layout and host props

| Prop | Default | Notes | | --- | --- | --- | | variant | 'surface' | surface => div, button => styled native button. | | className | undefined | Merged with internal classes. | | type | 'button' | Only relevant for variant="button". | | children | undefined | Rendered above glass backdrop in .liquid-glass__content. | | ref | — | HTMLDivElement for surface, HTMLButtonElement for button. | | native attrs | — | onClick, aria-*, data-*, etc. are forwarded. |

🌐 Browser behavior

| Browser family | Result | | --- | --- | | Chrome / Edge | Full SVG URL backdrop-filter effect | | Safari / Firefox | Frosted fallback class (liquid-glass--fallback) |

⚡ Performance notes

• Map generation is CPU-heavy (O(width x height)), but runs on resize/prop updates, not per animation frame.
• Very large surfaces increase canvas work significantly.
• Prefer layout sizing (and optional uiScale) over host transform scaling.

♿ Accessibility

• Use visible text or set aria-label for icon-only / empty buttons.
• Decorative backdrop and SVG filter defs are aria-hidden.
• CSS includes reduced-motion consideration (prefers-reduced-motion) for aggressive hinting.

🔒 Security

Displacement and specular assets are generated from numeric ImageData and encoded as data URLs. No HTML injection is involved in the rendering path.

License

MIT