Skip to main content
All guides
Guide contents

Guide contents

Time to study: 12 min
#automation#openglass#liquid#glass#react
Beginner12 min

OpenGlass UI: Complete Guide to the Liquid Glass React Library

Architecture and integration guide for OpenGlass UI: 40 native components, CSS, SVG SDF, and WebGL2 renderers, token systems, Next.js SSR, and WCAG 2.2.

Published:

OpenGlass UI is a modern React and web component library designed to deliver physical Liquid Glass aesthetics across digital interfaces. Moving far beyond trivial CSS implementations relying solely on backdrop-filter: blur(), OpenGlass UI pairs physically based refraction models, Signed Distance Fields (SDF), hardware-accelerated WebGL2 lenses, and native WCAG 2.2 accessibility compliance.

This guide provides an exhaustive engineering breakdown of the library: from three-tier rendering pipelines and Next.js App Router integration to token-driven theming and GPU performance optimization.

1. Liquid Glass Concept and Core Capabilities of OpenGlass UI

1.1. The Philosophy of Liquid Glass: Bridging Native DOM and Optics

Traditional glassmorphic implementations are frequently criticized for poor legibility and excessive CPU overhead. OpenGlass UI resolves these limitations through architectural decoupling:

  • Semantic Foundation: All 40 included components render onto native HTML elements (<button>, <input>, <dialog>), preserving browser keyboard navigation and assistive technology trees.
  • Optical Materials: The visual surface dynamically adapts to its background layer using tinting, beveling, specular highlights, and edge refraction.
  • Graceful Fallbacks: When running on low-powered mobile devices or under operating system accessibility settings like reduced transparency, the system automatically degrades to high-contrast opaque CSS surfaces.

1.2. Comparative Matrix of the Three Renderers: CSS, SVG Refraction, and WebGL2

OpenGlass UI incorporates three dedicated rendering pipelines tailored for different UI surfaces:

mermaid
flowchart TD A["GlassSurface Render Request"] --> B{"Source Type & Boundary Geometry"} B -->|"Arbitrary DOM / Controls / Text"| C["1. CSS Renderer (Default: performant blur, border, shadow)"] B -->|"Closed Geometric Bounds (Rounded Rect, Capsule)"| D["2. SVG / SDF Renderer (True light refraction via Displacement Map)"] B -->|"Dynamic Media (Video, Canvas, Images)"| E["3. WebGL2 Renderer (Hardware chromatic dispersion & IOR lenses)"]
Renderer PipelineOptical CapabilitiesGPU OverheadBrowser SupportRecommended Use Case
CSS (Auto)Tint, blur, border highlights, shadowsMinimal99.8% (All modern browsers)Buttons, form inputs, cards, navigation, lists
SDF / SVGContour light bending (Index of Refraction)ModerateAll browsers supporting SVG filtersModals, floating dock bars, segmented tabs
WebGL2Realistic chromatic dispersion, lensesHighRequires WebGL2 supportMedia players, interactive glass over 3D/video

2. Package Architecture and Dependency Installation

2.1. Modular Design: The open-glass-ui Facade and Internal Workspaces

The public npm package open-glass-ui consolidates four internal modular workspaces:

mermaid
flowchart LR A["open-glass-ui (Public npm Facade)"] --> B["@open-glass-ui/core (Geometry, SDF math, tokens without React)"] A --> C["@open-glass-ui/renderers (CSS materials, WebGL2 shaders, SVG helpers)"] A --> D["@open-glass-ui/react (State providers, hooks, SSR hydration lifecycle)"] A --> E["@open-glass-ui/recipes (40 ready UI recipes on native DOM)"]
Warning

Direct imports from internal workspaces (such as @open-glass-ui/core or @open-glass-ui/recipes) are private implementation boundaries. Always import via the public facade:

  • open-glass-ui — primary React components, providers, and hooks.
  • open-glass-ui/webgl — hardware WebGL2 surface subsystem.
  • open-glass-ui/core — pure math utilities for theme calculations, contrast ratios, and colors in server components.

2.2. Package Installation and Global Style Ingestion

Install OpenGlass UI using your preferred package manager:

bash
npm install open-glass-ui # or pnpm add open-glass-ui

Import global stylesheet tokens at your application entry point (e.g. src/app/layout.tsx or src/main.tsx):

typescript
// Required import for base CSS materials: import "open-glass-ui/styles.css"; import { Button, Glass, GlassSystemProvider } from "open-glass-ui"; export function RootApplication() { return ( <GlassSystemProvider renderer="auto" quality="auto" motion="system" theme={{ appearance: "system", defaultAppearance: "dark", theme: { preset: "neutral", contrast: "high", radius: "balanced" }, }} > <main className="min-h-screen bg-slate-950 p-8"> <Glass material="regular" interactive> <Button variant="primary">Get Started</Button> </Glass> </main> </GlassSystemProvider> ); }

3. Theme System Configuration: Palettes, Contrast, and CSS Tokens

3.1. Theme Orchestration: Presets, Appearance Modes, and Corner Radii

The OpenGlass UI theming engine is structured across three axes:

  1. Appearance Mode: Accepts light, dark, or system. When set to system, the server renders a deterministic defaultAppearance, synchronizing with prefers-color-scheme post-hydration.
  2. Palette Presets: Choose from built-in validated palettes (neutral, cobalt, teal, violet, coral, amber) or override with custom hex values via accent, secondary, and tertiary.
  3. Corner Radius: Select between sharp, balanced (standard 12–16px), or soft (organic 24–28px).

3.2. Semantic Token Matrix (--ogui-*) and WCAG Contrast Verification

All component surfaces map to stable CSS variables:

css
/* Base surfaces and borders */ --ogui-color-background: #090d16; --ogui-color-surface: rgba(15, 23, 42, 0.65); --ogui-color-border: rgba(255, 255, 255, 0.12); --ogui-color-text: #f8fafc; --ogui-color-muted: #94a3b8; /* Accent states and focus indicators */ --ogui-color-accent: #38bdf8; --ogui-color-accent-ink: #031525; --ogui-color-focus: #0284c7; /* Radii and optical material parameters */ --ogui-radius-control: 8px; --ogui-radius-surface: 16px; --ogui-material-blur: 16px; --ogui-material-bevel: 1px;

💡 Contrast Verification Rule: Use the exported contrastRatio(colorA, colorB) utility from open-glass-ui/core. Contrast must measure at least 4.5:1 for body copy and 3:1 for large headings to fulfill WCAG 2.2 AA.

4. Component Catalog: Comprehensive Review of 40 Native Recipes

4.1. Component Taxonomy: Controls, Overlays, Navigation, and Forms

The package ships with 40 production-ready recipes built on native DOM elements:

Functional CategoryIncluded UI Components
Action ControlsButton, IconButton, ToggleButton, SegmentedControl, Switch, Slider, Stepper
Navigation & LayoutToolbar, Dock, Tabs, Breadcrumbs, Pagination, Menu, MenuItem
Overlays & DialogsDialog, Drawer, Popover, Tooltip, Toast, Alert, Banner
Form InputsTextField, Textarea, NumberField, SearchField, Select, Checkbox, RadioGroup, FileDropzone
Data PresentationCard, Stat, Badge, Avatar, AvatarGroup, Accordion, Progress, Meter, Spinner, Skeleton, MediaControls

4.2. Accessibility Standards (a11y): ARIA Bindings, Focus Rings, and State Logic

Adhere to core accessibility invariants when integrating OpenGlass UI recipes:

  • Mandatory Icon Labels: IconButton and SegmentedControl strictly require explicit aria-label strings for screen readers.
  • Deterministic Focus Restoration: Dialog and Drawer primitives automatically retain and restore keyboard focus to the triggering element upon dismissal.
  • Multi-Modal State Signaling: Never communicate selected, disabled, or error states solely via transparency or color. Always provide textual or icon-based status indicators.

5. Working with Renderers: From Universal CSS to Hardware WebGL2

5.1. Declarative SVG/SDF Refraction for Closed Geometric Geometries

For floating control panels or standalone cards, enable physical light refraction using Signed Distance Fields:

typescript
import React from "react"; import { Glass, SdfFilterDefinition, useSdfFilter } from "open-glass-ui"; const panelGeometry = { kind: "rounded-rect", width: 360, height: 200, cornerRadius: 24, } as const; export function RefractedControlPanel({ children }: { children: React.ReactNode }) { const filter = useSdfFilter({ id: "main-panel-filter", width: 360, height: 200, geometry: panelGeometry, quality: "medium", }); return ( <div className="relative inline-block"> <SdfFilterDefinition filter={filter} /> <Glass renderer="sdf-svg" filterId={filter.filterId} geometry={panelGeometry} material="regular" > <div className="p-6 text-slate-100"> {children} </div> </Glass> </div> ); }

5.2. Hardware Optical Lenses in WebGL2 Over Live Video and Canvas

When rendering over live video, canvas streams, or 3D viewports, open-glass-ui/webgl layers hardware lenses with Index of Refraction (IOR) physics:

typescript
"use client"; import React, { useRef } from "react"; import { GlassProvider } from "open-glass-ui"; import { WebGLGlassSurface } from "open-glass-ui/webgl"; const opticalMaterial = { thickness: 0.62, ior: 1.48, // Glass refraction index dispersion: 0.015, // Edge chromatic dispersion edgeStrength: 0.5, bevel: 0.7, frost: 0.2, }; export function InteractiveVideoLens() { const videoRef = useRef<HTMLVideoElement>(null); return ( <GlassProvider> <div className="relative overflow-hidden rounded-2xl"> <video ref={videoRef} src="/ambient-flow.mp4" autoPlay loop muted playsInline className="w-full h-auto block" /> <WebGLGlassSurface sourceRef={videoRef} continuous maxDevicePixelRatio={2} lenses={[ { x: 180, y: 120, width: 240, height: 120, radius: 0.4, material: opticalMaterial, }, ]} /> </div> </GlassProvider> ); }

6. Next.js App Router Integration and Server-Side Rendering (SSR)

6.1. Clean Hydration: Isolating Client Boundaries and Server-Safe Core Utilities

OpenGlass UI is built for Next.js App Router conventions. Server rendering never references window, document, or WebGL contexts.

Encapsulate client-side state in a dedicated provider component:

typescript
// src/components/providers/GlassRootProvider.tsx "use client"; import React from "react"; import "open-glass-ui/styles.css"; import { GlassSystemProvider } from "open-glass-ui"; export function GlassRootProvider({ children }: { children: React.ReactNode }) { return ( <GlassSystemProvider renderer="auto" quality="auto" theme={{ appearance: "system", defaultAppearance: "dark", }} > {children} </GlassSystemProvider> ); }

Import pure utility functions for color calculations into Server Components directly from open-glass-ui/core:

typescript
// src/app/page.tsx (Server Component) import { createGlassTheme } from "open-glass-ui/core"; import { GlassRootProvider } from "@/components/providers/GlassRootProvider"; export default function Page() { const staticTheme = createGlassTheme({ preset: "neutral", contrast: "high" }); return ( <GlassRootProvider> <h1 className="text-2xl font-bold">SSR Initialized Successfully</h1> </GlassRootProvider> ); }

6.2. Preventing Layout Flicks and Dynamic prefers-color-scheme Synchronization

To eliminate hydration mismatches:

  • Avoid branching initial JSX output on viewport dimensions (window.innerWidth).
  • Declare defaultAppearance="dark" to ensure deterministic server and client initial markup.

7. Performance Engineering and Graphics Pipeline Optimization

7.1. Minimizing GPU Overhead: DPR Clamping and Selective Glass Adoption

Extensive backdrop filtering can tax consumer GPUs. Follow these production rules:

  • Clamp Device Pixel Ratio: Always constrain maxDevicePixelRatio={2} on WebGL surfaces. Rendering on Retina displays at DPR 3+ quadruples pixel shading cost with zero perceptible quality gain.
  • Selective Layering: Restrict glass materials to top-level navigation (Headers, Docks, Modals). Routine list items should employ opaque or semi-transparent flat CSS backgrounds.
  • Pointer-Rate Updates: For interactive mouse-tracking effects, mutate CSS variables or transform matrices via element refs rather than triggering React re-renders on every animation frame.

7.2. Signed Distance Field (SDF) Caching and Resize Throttling

Generating SDF displacement maps is compute-intensive. The useSdfFilter hook automatically caches maps keyed to geometric parameters. During viewport resizing, the library automatically drops render quality, restoring full fidelity only after resize events settle.

8. Troubleshooting Matrix and Frequently Asked Questions (FAQ)

8.1. Diagnosing Rendering Artifacts, Contrast Failures, and Memory Leaks

Symptom / ErrorRoot CauseEngineering Solution
Glass effect absent (flat white/gray)Missing global stylesheet importAdd import "open-glass-ui/styles.css"; to root layout
Text illegible over bright photographyHigh transparency in material="clear"Switch to material="regular" or material="frosted" for increased backing opacity
Frame drops during page scrollToo many active sdf-svg filter nodesRevert bulk elements to renderer="auto" (CSS)
WebGL context lost runtime warningExceeded maximum concurrent canvas contextsLimit active lenses to 6 per single WebGLGlassSurface

8.2. Frequently Asked Questions by Frontend Engineers Adopting OpenGlass UI

❓ Is OpenGlass UI compatible with Tailwind CSS?
Yes. OpenGlass UI does not conflict with Tailwind classes. You can safely compose utility classes (className="flex items-center gap-4 p-6") alongside material and interactive props.

❓ Is OpenGlass UI ready for enterprise production?
The package is currently in pre-release. Its architecture and public API are stabilized, but reviewing release changelogs before upgrading minor versions is strongly recommended.

❓ How does the library handle Windows High Contrast Mode?
OpenGlass UI detects forced-colors: active media queries automatically, stripping all translucency effects and applying solid high-contrast borders and standard system colors.

This guide is completely free. If it saved you an evening, you can support the project's growth.
Support the author