Themes and materials
Scoped appearance configuration and an optional Liquid Glass-inspired Web material.
Wrap a subtree in UIProvider. Theme changes stay scoped, including portaled dialogs; nested providers inherit unspecified options.
import { UIProvider, Glass, Button, Menu } from '@swiftuijs/ui';
const items = [{ label: 'Edit' }, { label: 'Delete', destructive: true }];
<UIProvider
theme="light"
accentColor="#7952B3"
glass={{ enabled: true, intensity: 0.6, variant: 'regular' }}
tokens={{ '--sw-radius-sheet': '28px' }}
>
<Glass><Button buttonStyle="borderedProminent">Continue</Button></Glass>
<Menu glass={false} trigger={<Button>Actions</Button>} items={items} />
</UIProvider>Theme and tokens
theme accepts light, dark, or system. CSS resolves the system preference without changing the server markup. tokens accepts --sw-* CSS variables; you can also override them in your own stylesheet. Keep accent colors readable in both themes.
Glass configuration
Liquid Glass is off by default. glass accepts a boolean or { enabled, intensity, variant, renderer }; intensity is clamped to 0–1 and zero disables the effect. The preference applies to Glass, menus, context menus, popovers, navigation controls, toolbar groups, tab bars, alerts, confirmation dialogs and automatic sheets. Each supports a local glass override. Keep forms and content cards opaque.
Presentations default to regular material for legibility, even with a global clear preference. An automatic sheet becomes more opaque at its large detent; full-screen sheets stay opaque. Explicit Sheet.backgroundStyle values take precedence over glass preferences and continue to support opaque accessibility fallbacks.
Requirements and fallbacks
The regular variant softens background detail and favors legibility. Clear uses less blur and a much lighter tint so the background stays visible. Use clear only over visually rich backgrounds and verify contrast; bright media may need a dimming layer behind the control. Chromium adds SVG edge refraction that follows the surface's size and corner radii, with clear foreground content. Safari and Firefox retain CSS blur, tint and rim highlights. Use glass={{ renderer: 'css' }} to choose CSS everywhere; auto is the default. Apple's system vibrancy and full native optical model are not reproduced.
SSR renders the CSS fallback; the optional renderer loads after hydration. SVG maps require img-src data: under CSP; blocked images or a failed optional chunk keep the CSS fallback. Maps use a bounded cache and rebuild after resizing settles, with no graphics engine or continuously running animation.
Reduced transparency, increased contrast and forced colors fall back to an opaque surface. Browsers without backdrop-filter also retain an opaque background. Test the material with your actual content, and use glass={false} for surfaces where effects are unnecessary.
See Apple's material guidelines for the distinction between the functional glass layer and standard content materials.