glass-refraction

Liquid Glass design system — CSS + React components with SVG refraction filters, specular highlights, and chromatic edge dispersion.

Inspired by Apple's Liquid Glass (WWDC 2025) and kube.io SVG refraction research.

Install

npm install glass-refraction

CSS-only usage (any framework)

Import the stylesheet and use the class names directly:

@import 'glass-refraction/css';

Or in JavaScript/TypeScript:

import 'glass-refraction/css';

<nav class="glass">Navbar</nav>
<div class="glass-card">Content card</div>
<span class="glass-pill">Badge</span>

React usage

import { GlassFilters, Glass, GlassCard, GlassPill } from 'glass-refraction';

export default function App() {
  return (
    <>
      <GlassFilters />
      <Glass as="nav" className="px-4 py-3">Navbar</Glass>
      <GlassCard className="p-6">
        <h2>Card title</h2>
        <p>Card content</p>
      </GlassCard>
      <GlassPill className="px-3 py-1">Tag</GlassPill>
    </>
  );
}

React components automatically import the CSS.

Tiers

| Class | Use case | Effect | |---|---|---| | .glass | Navbar, footer, hero overlays | Dense frosted glass with animated shimmer sweep, specular breathing highlight, and full chromatic edge dispersion | | .glass-card | Content cards, panels | Medium-density glass with hover lift, top-edge specular line, and chromatic edges on hover | | .glass-pill | Tags, badges, inline elements | Lightweight frosted pill with subtle hover brighten |

React Components

<GlassFilters />

Renders hidden SVG <defs> providing two refraction filters. Place once near the root of your app.

| Prop | Type | Default | Description | |---|---|---|---| | scale | number | 8 | Displacement scale for subtle refraction | | strongScale | number | 16 | Displacement scale for strong refraction | | baseFrequency | string | "0.015 0.012" | Turbulence frequency | | numOctaves | number | 2 | Noise octaves | | seed | number | 42 | Turbulence seed |

Apply the filters in CSS:

.refracted { filter: url(#glass-refract); }
.refracted-strong { filter: url(#glass-refract-strong); }

<Glass>

Polymorphic wrapper rendering a .glass element.

| Prop | Type | Default | Description | |---|---|---|---| | as | ElementType | "div" | HTML element to render | | variant | "glass" \| "glass-card" \| "glass-pill" | "glass" | Override the tier | | className | string | — | Additional classes |

<GlassCard>

| Prop | Type | Default | Description | |---|---|---|---| | as | ElementType | "div" | HTML element to render | | hoverable | boolean | true | Enable hover lift effect | | className | string | — | Additional classes |

<GlassPill>

| Prop | Type | Default | Description | |---|---|---|---| | as | ElementType | "span" | HTML element to render | | className | string | — | Additional classes |

Theming

Override CSS custom properties to theme the glass system:

:root {
  /* Blur */
  --gr-blur: 26px;
  --gr-blur-card: 20px;
  --gr-blur-pill: 8px;

  /* Saturation */
  --gr-saturation: 1.7;
  --gr-saturation-card: 1.5;
  --gr-saturation-pill: 1.3;

  /* Border radius */
  --gr-radius: 20px;
  --gr-radius-card: 16px;
  --gr-radius-pill: 9999px;

  /* Base background */
  --gr-bg-start: rgba(18, 22, 35, 0.48);
  --gr-bg-end: rgba(12, 16, 28, 0.42);

  /* Chromatic dispersion */
  --gr-chromatic-blue: rgba(0, 180, 255, 0.045);
  --gr-chromatic-violet: rgba(120, 80, 255, 0.04);
  --gr-chromatic-pink: rgba(255, 100, 200, 0.035);
  --gr-chromatic-green: rgba(100, 255, 180, 0.025);

  /* Animation timing */
  --gr-shimmer-duration: 7s;
  --gr-specular-duration: 5s;
}

Examples

• Vanilla HTML — examples/vanilla/index.html
• Next.js — examples/nextjs/page.tsx

Browser Support

Requires backdrop-filter support:

• Chrome 76+
• Safari 9+ (with -webkit- prefix, included)
• Firefox 103+
• Edge 79+

SVG refraction filters (<GlassFilters />) work in all modern browsers.

Credits

• Apple Liquid Glass design language (WWDC 2025)
• kube.io SVG refraction research
• feTurbulence + feDisplacementMap technique

License

MIT