glass-refraction

KO | EN

gitlite — search

#javascript #python #ai #golang #deep-learning #linux #docker #java #nodejs #awesome #kubernetes #awesome-list #pytorch #mcp

glass-refraction

(★ 36)

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

glass-refraction Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# glass-refraction

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

[![npm](https://img.shields.io/npm/v/glass-refraction)](https://www.npmjs.com/package/glass-refraction)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://raw.githubusercontent.com/Z1Code/glass-refraction/master/LICENSE)

Inspired by Apple's Liquid Glass (WWDC 2025) and [kube.io SVG refraction research](https://kube.io).

---

## Install

```bash
npm install glass-refraction
```

## CSS-only usage (any framework)

Import the stylesheet and use the class names directly:

```css
@import 'glass-refraction/css';
```

Or in JavaScript/TypeScript:

```js
import 'glass-refraction/css';
```

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

## React usage

```tsx
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:

```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:

```css
: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`](./examples/vanilla/index.html)
- **Next.js** — [`examples/nextjs/page.tsx`](./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](https://kube.io) SVG refraction research
- `feTurbulence` + `feDisplacementMap` technique

## License

[MIT](./LICENSE)

glass-refraction

glass-refraction Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

glass-refraction

glass-refraction Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README