@yyhomran/liquid-glass

A small, expressive React component library for interfaces that feel fluid, refractive, and quietly alive. Liquid Glass combines layered translucent surfaces, directional highlights, SVG displacement, backdrop blur, GPU-friendly interaction, and accessible fallbacks into a consistent design system.

Install

npm install @yyhomran/liquid-glass

Import the stylesheet once at your application root:

import '@yyhomran/liquid-glass/styles.css';
import { GlassCard, GlassButton } from '@yyhomran/liquid-glass';

Quick start

import { LiquidGlass, GlassCard, GlassButton } from '@yyhomran/liquid-glass';

export function Example() {
  return (
    <LiquidGlass interactive tilt glow>
      <GlassCard>
        <h1>Liquid Glass</h1>
        <p>Layered material for modern React interfaces.</p>
        <GlassButton variant="primary">Get started</GlassButton>
      </GlassCard>
    </LiquidGlass>
  );
}

Components

| Component | Purpose | | --- | --- | | LiquidGlass | The low-level material primitive with refraction and pointer light. | | GlassCard | Padded content surface with optional elevation. | | GlassButton | Accessible button with primary, secondary, and ghost variants. | | GlassInput | Labelled input with hints and error messaging. | | GlassNavbar | Responsive navigation surface with brand and link slots. | | GlassModal | Focusable dialog surface with Escape and backdrop dismissal. | | GlassPanel | Structured surface with eyebrow, title, action, and content slots. | | GlassBadge | Compact status or metadata chip. | | GlassToggle | Keyboard-friendly switch with controlled state. | | GlassTooltip | Hover and focus tooltip for concise contextual help. |

Core props

LiquidGlass, GlassCard, GlassPanel, and related surfaces accept the following visual props:

| Prop | Type | Default | Description | | --- | --- | --- | | blur | number | 20 | Backdrop blur radius in pixels. | | opacity | number | 0.095 | Base translucent surface opacity. | | borderRadius | number \| string | 24 | Radius in pixels or any CSS length. | | distortion | number | 8 | Subtle SVG displacement scale. | | glow | boolean | false | Adds a soft outer color glow. | | interactive | boolean | false | Enables pointer-following reflection and lift. | | reflection | boolean | true | Enables the refraction/highlight layer. | | intensity | number | 0.9 | Internal gradient intensity. | | color | string | — | Color used to derive the surface and glow. | | gradient | string | — | Complete CSS gradient override. | | tilt | boolean | false | Enables a restrained pointer tilt when interactive. | | mouseLight | boolean | true | Enables the pointer-position light. | | disabled | boolean | false | Dims the surface and disables interaction. | | theme | dark \| light \| auto | dark | Semantic theme hint for custom token layers. | | className / style | standard React types | — | Escape hatches for local customization. |

Customization and themes

The visual system is tokenized with CSS custom properties. Override them globally or scope them to a section:

:root {
  --lg-blur: 24px;
  --lg-radius: 20px;
  --lg-border: rgba(255, 255, 255, .22);
  --lg-highlight: rgba(188, 221, 255, .38);
  --lg-glow: rgba(100, 153, 255, .28);
}

.light-glass {
  --lg-background: rgba(255, 255, 255, .55);
  --lg-text: #11182c;
  --lg-muted: #5a6680;
  --lg-border: rgba(40, 60, 100, .15);
}

Use gradient when a component needs an art-directed surface, or use color to derive a coherent tint and glow without writing custom CSS.

Accessibility

The interactive controls use native buttons and inputs, visible focus rings, labelled relationships, aria-invalid, aria-describedby, role="switch", and role="dialog" where appropriate. GlassModal closes with Escape and prevents background scrolling while open. The stylesheet includes a prefers-reduced-motion: reduce treatment that removes non-essential movement and animation.

Browser support and fallback behavior

Modern Chromium, Safari, and Firefox browsers receive the full treatment when backdrop-filter and SVG filters are available. The library uses @supports to fall back to an opaque, readable surface when backdrop blur is unavailable; the effect is never required for contrast or interaction. SVG displacement is intentionally decorative and can be disabled with reflection={false}.

Performance

The library keeps React state out of the high-frequency pointer path. Pointer coordinates update CSS variables directly, while CSS handles gradients, transitions, and transforms. There are no runtime dependencies beyond React, and no animation loop is used for normal interactions. For dense views, prefer interactive={false} on static surfaces and reserve tilt for hero moments.

Advanced usage

Compose the primitive with your own semantic element or layout:

<LiquidGlass
  as="section"
  blur={28}
  distortion={12}
  gradient="linear-gradient(130deg, rgba(142,168,255,.20), rgba(255,255,255,.04))"
  style={{ '--lg-radius': '32px' } as React.CSSProperties}
>
  {/* your content */}
</LiquidGlass>

The demo in this repository is intentionally built from the public package exports. Run it locally with npm run dev, and build the package/demo with npm run build.

License

MIT. See LICENSE.