Artem Safronov

Posted on Dec 14 • Originally published at dev.to

shadcn-glass-ui: Drop-in Glassmorphism for Your shadcn/ui Projects 🎨

#react #typescript #shadcn #opensource

👋 The Problem

You've built a beautiful app with shadcn/ui. Now you want to add glassmorphism effects — that gorgeous frosted glass look from iOS and macOS. Your options?

📚 CSS libraries — No React components, manual integration
🔄 Full UI frameworks — Requires complete project migration
✍️ Custom components — Build and maintain everything yourself

What if there was a better way?

✨ Introducing shadcn-glass-ui

shadcn-glass-ui is a glassmorphism component library that installs on top of existing shadcn/ui projects with zero migration required. Think of it as shadcn/ui's glass-themed sibling.

# Add to your existing shadcn/ui project
npx shadcn@latest add @shadcn-glass-ui/button-glass

# Use alongside your existing components
import { Button } from '@/components/ui/button';
import { ButtonGlass } from '@/components/glass/ui/button-glass';

🎯 Key Features

🔗 100% shadcn/ui Compatible — Same APIs, same CLI, same patterns. Drop-in installation.
🚀 Progressive Enhancement — MVP on base components → glassmorphism → custom branding
🎨 57 Production-Ready Components — Core UI, Atomic, Composite, Sections, Specialized
🔧 Listed on registry.directory — Official shadcn CLI support
🎭 3-Layer Token System — Zero hardcoded colors, create themes in ~15 lines
🌈 3 Built-in Themes — Glass (dark), Light, Aurora (gradient)
🤖 AI-First Design — Context7 MCP, Claude Code, GitHub Copilot, GPT
♿ WCAG 2.1 AA — Full accessibility, 44px touch targets
⚡ Modern Stack — React 19.2, TypeScript 5.9, Tailwind v4.1, Vite 7
📦 Tree-Shakeable — Import only what you need
🧪 1,500+ Tests — 99.5% pass rate (visual regression, compliance, unit)

🚀 Drop-in Compatibility: The Game Changer

No migration required. shadcn-glass-ui enables a progressive enhancement workflow:

🏗️ Phase 1: Build MVP with base components
   ↓ shadcn/ui — fast start, validate ideas

🎨 Phase 2: Add glassmorphism effects
   ↓ shadcn-glass-ui — visual upgrade without rewrites

🔧 Phase 3: Custom branding
   ↓ 3-layer token system — brand theme in ~15 lines

Perfect for:

Startups — Quick MVP → polish design later
Agencies — Template project → customize per client
Enterprise — Prototype with shadcn/ui → production-ready with branding
Freelancers — One codebase → different visual styles per client

Works Alongside Your Existing Code

shadcn-glass-ui components live side-by-side with shadcn/ui:

// ✅ Your existing shadcn/ui components keep working
import { Button } from '@/components/ui/button';
import { Input } from '@/components/ui/input';

// ✅ Glass variants install separately
import { ButtonGlass } from '@/components/glass/ui/button-glass';
import { InputGlass } from '@/components/glass/ui/input-glass';

function LoginForm() {
  return (
    <form className="space-y-4">
      {/* Standard shadcn/ui */}
      <Input placeholder="Email" />
      <Button variant="outline">Standard button</Button>

      {/* Glass variants with effects */}
      <InputGlass placeholder="Password" type="password" />
      <ButtonGlass variant="primary">Login with glass ✨</ButtonGlass>
    </form>
  );
}

API Compatibility

v2.0.0 achieves 100% API parity with shadcn/ui:

Component	shadcn/ui	shadcn-glass-ui v2.0	Compatible
Button	`variant="default"`	`variant="default"`	✅ 100%
Toggle	`pressed`, `onPressedChange`	`pressed`, `onPressedChange`	✅ 100%
Slider	`value: number[]`, `onValueChange`	`value: number[]`, `onValueChange`	✅ 100%
ComboBox	`value`, `onValueChange`	`value`, `onValueChange`	✅ 100%

Same everything:

✅ Props: variant, size, className
✅ Callbacks: onValueChange, onPressedChange
✅ asChild pattern for polymorphic rendering
✅ CLI installation via npx shadcn add

Bonus features:

🎨 Built-in glassmorphism effects
⚙️ Additional props: loading, icon, intensity
🧩 Compound Components API for complex widgets

📦 Installation: Two Ways

Option 1: shadcn CLI (Recommended)

Now listed on registry.directory!

Step 1: Add registry to components.json:

{
  "registries": {
    "@shadcn-glass-ui": {
      "url": "https://raw.githubusercontent.com/Yhooi2/shadcn-glass-ui-library/main/public/r"
    }
  }
}

Step 2: Install components:

# One command per component
npx shadcn@latest add @shadcn-glass-ui/button-glass
npx shadcn@latest add @shadcn-glass-ui/input-glass
npx shadcn@latest add @shadcn-glass-ui/modal-glass

# Or multiple at once
npx shadcn@latest add @shadcn-glass-ui/button-glass @shadcn-glass-ui/input-glass

Why CLI?

✅ Minimal bundle — only what you use
✅ Code lives in your project — full control
✅ Easy to customize
✅ No npm dependency

Option 2: Full Package (npm)

npm install shadcn-glass-ui

Quick start:

import { ButtonGlass, InputGlass, ThemeProvider } from 'shadcn-glass-ui';
import 'shadcn-glass-ui/dist/styles.css';

function App() {
  return (
    <ThemeProvider defaultTheme="glass">
      <div className="p-8 space-y-4">
        <ButtonGlass variant="primary" size="lg">
          Click me! ✨
        </ButtonGlass>
        <InputGlass placeholder="Enter text..." />
      </div>
    </ThemeProvider>
  );
}

Why npm?

✅ One-command installation
✅ Automatic updates
✅ Tree-shaking included

🎭 Revolutionary: 3-Layer Token System

What makes v2.0 special? Zero hardcoded color values. Every color is a CSS variable.

┌─────────────────────────────────────────────────────────────┐
│  Component Tokens (280+)                                     │
│  --btn-primary-bg, --modal-surface, --input-border          │
│         ↓ automatically inherit from                        │
│  Semantic Tokens (~15 per theme)                            │
│  --semantic-primary, --semantic-surface, --semantic-border  │
│         ↓ reference                                         │
│  Primitive Tokens (225 OKLCH colors)                        │
│  --oklch-purple-500, --oklch-slate-900                      │
└─────────────────────────────────────────────────────────────┘

How It Works

Layer 1 — 225 OKLCH colors, defined once for all themes:

:root {
  --oklch-purple-500: oklch(0.55 0.25 270);
  --oklch-slate-900: oklch(0.15 0.02 250);
  --oklch-emerald-500: oklch(0.55 0.20 160);
  --oklch-cyan-400: oklch(0.70 0.15 195);
  /* ... 221 more colors */
}

Layer 2 — Each theme defines ~15 semantic tokens:

[data-theme='glass'] {
  --semantic-primary: var(--oklch-purple-500);
  --semantic-surface: var(--oklch-slate-900);
  --semantic-text: var(--oklch-white-95);
  --semantic-border: var(--oklch-slate-700);
  --semantic-glow: var(--oklch-purple-500);
  /* ... 10 more tokens */
}

Layer 3 — Components automatically inherit:

:root {
  --btn-primary-bg: var(--semantic-primary);
  --btn-primary-glow: var(--semantic-glow);
  --modal-surface: var(--semantic-surface);
  --input-border: var(--semantic-border);
  /* ... 280+ component tokens */
}

Create a Custom Theme in ~15 Lines

Want a neon theme? Override only the semantic layer:

[data-theme='neon'] {
  --semantic-primary: var(--oklch-cyan-400);
  --semantic-secondary: var(--oklch-purple-400);
  --semantic-surface: var(--oklch-black-10);
  --semantic-surface-elevated: var(--oklch-slate-950);
  --semantic-text: var(--oklch-white-98);
  --semantic-text-muted: var(--oklch-slate-400);
  --semantic-border: var(--oklch-cyan-500);
  --semantic-border-subtle: var(--oklch-slate-800);
  --semantic-glow: var(--oklch-cyan-400);
  --semantic-success: var(--oklch-emerald-500);
  --semantic-warning: var(--oklch-amber-500);
  --semantic-destructive: var(--oklch-red-500);
  --semantic-info: var(--oklch-blue-500);
}

Result:

✅ All 57 components update automatically
✅ Theme switching is instant — CSS only, no React re-renders
✅ 280+ component tokens inherit without changes

Real-World Example: MVP to Production

Scenario: SaaS startup building an analytics dashboard.

Week 1-2: MVP with shadcn/ui

// Quick prototype with base components
import { Button, Input, Card } from '@/components/ui';

function Dashboard() {
  return (
    <div>
      <Card>
        <h2>Metrics</h2>
        <Input placeholder="Search..." />
        <Button>Export</Button>
      </Card>
    </div>
  );
}

Week 3: Add glassmorphism

# One command — visual upgrade
npx shadcn@latest add @shadcn-glass-ui/card-glass
npx shadcn@latest add @shadcn-glass-ui/button-glass
npx shadcn@latest add @shadcn-glass-ui/input-glass

// Change only imports — APIs identical
import { ButtonGlass, InputGlass, CardGlass } from '@/components/glass/ui';

function Dashboard() {
  return (
    <div>
      <CardGlass> {/* Now with blur and glow effects */}
        <h2>Metrics</h2>
        <InputGlass placeholder="Search..." />
        <ButtonGlass>Export</ButtonGlass>
      </CardGlass>
    </div>
  );
}

Week 4: Brand with corporate colors

/* 15 lines — entire company branded */
[data-theme='company'] {
  --semantic-primary: var(--oklch-blue-600);      /* Corp blue */
  --semantic-secondary: var(--oklch-orange-500);  /* Corp orange */
  --semantic-surface: var(--oklch-slate-900);     /* Dark background */
  --semantic-glow: var(--oklch-blue-400);         /* Blue glow */
  /* ... 10 more tokens */
}

Result:

⚡ 0 rewritten code — only import changes
🎨 Full rebrand in 15 CSS lines
🚀 Idea to production in one month

Before and After

Metric	v1.x (old)	v2.0 (token system)
Hardcoded OKLCH values	~280 per theme	0
CSS variables per theme	~85	296+ (auto-inherited)
Lines to create theme	~280	~15
Theme switching	React re-render	Instant CSS swap

🤖 AI-First: Built for AI Assistants

Modern developers use AI coding assistants (Claude, Copilot, ChatGPT). The problem? Most libraries are poorly indexed: implicit APIs, outdated docs in training data.

shadcn-glass-ui is optimized for AI:

AI Tool	Integration	What it provides
Context7 MCP	Auto-indexed	41 rules, auto-fetched current docs, version-aware
Claude Code	CLAUDE.md	365-line project context, patterns, examples
GitHub Copilot	TypeScript strict + JSDoc	Accurate completions with inline examples
ChatGPT/GPT-4	EXPORTS_MAP.json	Machine-readable component registry

Example: Context7 MCP in Action

Context7 is a Model Context Protocol for indexing documentation. AI assistants query current documentation in real-time instead of relying on stale training data.

Typical workflow:

Developer: "Add a stepper to my checkout flow with 3 steps"

→ Claude Code queries Context7 MCP for documentation
→ Context7 returns current StepperGlass docs
→ Claude sees: "compound API, linear mode for wizards, 3 variants"
→ Claude generates correct code:

<StepperGlass.Root mode="linear" currentStep={step}>
  <StepperGlass.Step value={0}>
    <StepperGlass.Trigger>
      <StepperGlass.Icon />
      Shipping
    </StepperGlass.Trigger>
    <StepperGlass.Content>
      <AddressForm />
    </StepperGlass.Content>
  </StepperGlass.Step>

  <StepperGlass.Step value={1}>
    <StepperGlass.Trigger>
      <StepperGlass.Icon />
      Payment
    </StepperGlass.Trigger>
    <StepperGlass.Content>
      <PaymentForm />
    </StepperGlass.Content>
  </StepperGlass.Step>

  <StepperGlass.Step value={2}>
    <StepperGlass.Trigger>
      <StepperGlass.Icon />
      Confirmation
    </StepperGlass.Trigger>
    <StepperGlass.Content>
      <OrderSummary />
    </StepperGlass.Content>
  </StepperGlass.Step>
</StepperGlass.Root>

Without Context7, AI would:

Rely on outdated docs from training data
Guess API names (maybe step instead of value?)
Miss the linear mode for wizards
Forget StepperGlass.Icon and other subcomponents

Decision Trees for AI

The repository includes decision trees — which component to use for specific tasks:

Need to display a metric?
├─ Single value → MetricCardGlass
├─ Compare multiple → MetricsGridGlass
├─ With trend (sparkline) → SparklineGlass
└─ Circular chart → CircularMetricGlass

Need a modal?
├─ Simple confirmation → AlertGlass
├─ Form with fields → ModalGlass.Root (compound)
└─ Toast notification → NotificationGlass

Rich JSDoc for All Components

Every component includes detailed JSDoc with examples:

/**
 * Glass-styled button with glassmorphism effect
 * 
 * @example
 * // Primary button with loading state
 * <ButtonGlass variant="primary" size="lg" loading>
 *   Loading...
 * </ButtonGlass>
 * 
 * @example
 * // As link with React Router (polymorphic)
 * <ButtonGlass asChild>
 *   <Link to="/profile">Profile</Link>
 * </ButtonGlass>
 * 
 * @example
 * // With icon
 * <ButtonGlass icon={<CheckIcon />} variant="ghost">
 *   Saved
 * </ButtonGlass>
 * 
 * @accessibility 
 * - Keyboard navigation (Enter, Space)
 * - Focus visible ring (2px inner + 4px outer)
 * - Touch target minimum 44x44px (Apple HIG)
 * - Loading state disables interaction
 */
export const ButtonGlass: React.FC<ButtonGlassProps> = ({ 
  variant = "default",
  size = "md",
  loading = false,
  icon,
  asChild = false,
  ...props 
}) => { /* ... */ };

AI sees examples directly in types and generates correct code on the first try.

🎨 Components: 57 Production-Ready

shadcn-glass-ui provides 57 components across 6 categories:

Category	Count	Description	Examples
Core UI	18	Essential building blocks	ButtonGlass, InputGlass, ModalGlass, TabsGlass, CheckboxGlass, SliderGlass
Atomic	7	Single-purpose components	SearchBoxGlass, ThemeToggleGlass, IconButtonGlass, StatItemGlass
Composite	13	Pre-built complex widgets	MetricCardGlass, AICardGlass, RepositoryCardGlass, UserInfoGlass
Sections	7	Full page sections	HeaderNavGlass, ProfileHeaderGlass, CareerStatsGlass, ProjectsListGlass
Specialized	10	Advanced components	SparklineGlass, StepperGlass (3 variants), RainbowProgressGlass
Primitives	3	Low-level primitives	TouchTarget, FormFieldWrapper, InteractiveCard

Three Built-in Themes

Glass (dark) — Classic glassmorphism with purple accents and glow effects
Light — Clean minimal design with subtle glass effects
Aurora — Vibrant gradients with aurora borealis-inspired colors

import { ThemeProvider, useTheme } from 'shadcn-glass-ui';

function ThemeSwitcher() {
  const { theme, cycleTheme } = useTheme();

  return (
    <button onClick={cycleTheme}>
      Current theme: {theme}
    </button>
  );
}

Compound Components API

Complex components use the Compound Components pattern for maximum flexibility:

<ModalGlass.Root open={isOpen} onOpenChange={setIsOpen}>
  <ModalGlass.Overlay />
  <ModalGlass.Content>
    <ModalGlass.Header>
      <ModalGlass.Title>Confirm Action</ModalGlass.Title>
      <ModalGlass.Description>
        This action cannot be undone
      </ModalGlass.Description>
      <ModalGlass.Close />
    </ModalGlass.Header>

    <ModalGlass.Body>
      <p>Are you sure you want to delete this item?</p>
    </ModalGlass.Body>

    <ModalGlass.Footer>
      <ButtonGlass variant="ghost" onClick={() => setIsOpen(false)}>
        Cancel
      </ButtonGlass>
      <ButtonGlass variant="destructive" onClick={handleDelete}>
        Delete
      </ButtonGlass>
    </ModalGlass.Footer>
  </ModalGlass.Content>
</ModalGlass.Root>

Benefits:

🧩 Flexible composition — Skip Footer or add Description as needed
📦 Tree-shaking — Unused parts don't ship to production
📖 Clear structure — DOM hierarchy visible without docs

Polymorphic Components (asChild)

All interactive components support the asChild pattern from Radix UI:

import { ButtonGlass } from 'shadcn-glass-ui';
import { Link } from 'react-router-dom';

// Render button as React Router Link
<ButtonGlass asChild variant="primary">
  <Link to="/dashboard">Go to Dashboard</Link>
</ButtonGlass>

// Render button as anchor
<ButtonGlass asChild variant="ghost">
  <a href="https://github.com" target="_blank" rel="noopener">
    GitHub
  </a>
</ButtonGlass>

// Render button as custom component
<ButtonGlass asChild>
  <motion.button
    whileHover={{ scale: 1.05 }}
    whileTap={{ scale: 0.95 }}
  >
    Animated Button
  </motion.button>
</ButtonGlass>

♿ Accessibility First

All components comply with WCAG 2.1 Level AA:

✅ Contrast — Minimum 4.5:1 for text
✅ Keyboard — Full navigation via Tab, Enter, Arrow keys
✅ Touch targets — Minimum 44×44px (Apple HIG)
✅ Screen readers — Proper ARIA attributes and semantic HTML
✅ Focus indicators — 2px inner + 4px outer ring
✅ Reduced motion — Auto-disables animations with prefers-reduced-motion

Test Coverage: 1,500+ Automated Tests

Category	Count	Tools	Pass Rate
Design System Compliance	650+	Vitest + custom matchers	99.5%
Visual Regression	580	Playwright + screenshots	99.5%
Unit Tests	270+	Vitest	99.5%

Design System Compliance verifies:

All components use tokens (no hardcoded values)
Touch targets minimum 44×44px
Color contrast 4.5:1+
Correct compound component structure

Visual Regression catches:

Unintended visual changes
Theme switching bugs
Responsive design issues

🛠️ CLI Utilities

shadcn-glass-ui includes a CLI for quick reference:

# Component info (fuzzy search)
npx shadcn-glass-ui info button
npx shadcn-glass-ui info modal

# List all components
npx shadcn-glass-ui list

# Filter by category
npx shadcn-glass-ui list --category=core
npx shadcn-glass-ui list --category=composite

🗺️ Roadmap

Coming in future releases:

🎨 10+ new components (DatePicker, Calendar, Command Palette)
🌈 Additional themes (Cyberpunk, Nord, Dracula)
📱 Mobile optimization enhancements
🔌 Figma plugins (export themes)
🤖 Extended Context7 integration (code actions)

📚 Resources

🌐 Live Demo: Storybook
💻 GitHub: Repository
📦 npm: Package
📚 Documentation:
🤖 Context7: Auto-indexing

🤝 Contributing

shadcn-glass-ui is open source (MIT) and we welcome contributions!

🐛 Found a bug? Report it
💡 Have an idea? Start a discussion
🔧 Want to contribute? Contributing Guide

⭐ Support the Project

If you find shadcn-glass-ui useful:

Star the GitHub repository
Share this article
Try it in your next project

🎯 What Makes This Different?

shadcn-glass-ui solves four key problems:

"How do I add glassmorphism without rewriting my project?"

→ Drop-in compatibility with shadcn/ui, CLI installation
"How do I quickly go from MVP to production-ready design?"

→ Progressive enhancement: base components → glassmorphism → branding
"How do I create themes without copy-pasting hundreds of values?"

→ 3-layer token system, new theme in ~15 lines
"How do I make my library AI-assistant friendly?"

→ Context7 MCP, rich JSDoc, decision trees