GitHub - ObaidQatan/liquid-glass-component-library: A React component collection exploring glassmorphism and Apple-inspired Liquid Glass surfaces.

A React component collection exploring glassmorphism and Apple-inspired Liquid Glass surfaces.

It started as a personal experiment: how close can you get to iOS 26-style refractive glass in a browser with nothing but React, Tailwind CSS, SVG filters and Framer Motion? The result is a small but fully interactive library of desktop and mobile components built around a shared glass system that you can tweak in real time.

Status: experimental. Built for my own projects and learning.
Contributions: not accepted at this time.

✨ What it looks like

• Glass mode — traditional frosted glass with adjustable blur, transparency and saturation.
• Liquid Glass mode — an experimental refractive SVG-filter effect inspired by kube.io’s Liquid Glass research, pushing how close a browser can get to Apple’s Liquid Glass look. The standard glass mode is the more practical choice; Liquid Glass is here to test the limits.
• Dark & light themes with persistent user preferences.
• Spring-driven motion powered by Framer Motion.

The demo app is a single self-contained dist/index.html file that doubles as documentation and a playground.

🚀 Tech stack

• React 19 + TypeScript 5.9
• Vite 7
• Tailwind CSS 4.1
• Framer Motion
• lucide-react

The production build is inlined into one file by vite-plugin-singlefile.

📦 What’s inside

70+ components organized into categories:

The full source-of-truth for the docs is src/docs-data.ts, generated from the component files by node scripts/generate-docs-data.js.

🛠 Getting started

# clone the repo
git clone https://github.com/ObaidQatan/liquid-glass-component-library.git
cd liquid-glass-component-library

# install dependencies
pnpm install

# start the dev server
pnpm run dev

# build the single-file demo + docs
pnpm run build

# type-check
pnpm exec tsc --noEmit

After building, open dist/index.html or run pnpm run preview.

🧩 Basic usage

import { LiquidGlassButton, LiquidGlassCard, LiquidGlassModal } from "liquid-glass";

function App() {
  const [open, setOpen] = useState(false);

  return (
    <LiquidGlassCard className="p-6">
      <h2 className="text-xl font-semibold text-[var(--lg-text)]">Hello Glass</h2>
      <LiquidGlassButton onClick={() => setOpen(true)}>Open modal</LiquidGlassButton>
      <LiquidGlassModal open={open} onClose={() => setOpen(false)} title="Demo">
        This surface adapts to your glass settings automatically.
      </LiquidGlassModal>
    </LiquidGlassCard>
  );
}

🎚 Glass system

The ThemeProvider exposes mode-aware controls.

Glass mode

Liquid Glass mode

Switch between modes to compare standard frosted glass against the refractive SVG-filter look.

📁 Project structure

src/
├── components/liquid-glass/   # all components
├── App.tsx                    # demo playground
├── Docs.tsx                   # documentation SPA
├── docs-data.ts               # generated component metadata
├── docs-demos.tsx             # interactive demos
├── docs-variants.tsx          # variant grids
├── index.css                  # Tailwind entry + glass utilities
└── utils/cn.ts                # clsx + tailwind-merge

scripts/
└── generate-docs-data.js      # regenerates docs-data.ts

🙅‍♂️ Contributions

This repository is a personal sandbox. I’m not looking for issues, pull requests or maintainers right now. If that changes I’ll update this section.

🙏 Credits

The Liquid Glass experiment is inspired by kube.io — Liquid Glass with CSS and SVG.

This repo is a personal starting point. Hopefully it can help lead to a better, more stable, and more optimized glass UI library from trusted sources like Shadcn UI, Ionic, and others in the future.

📄 License

MIT — see LICENSE.

Built with curiosity by Obaid Qatan.