Theming
Define application-wide theme presets, provider scoping, dynamic theme switching, and portal styling.
Use defineTheme() and MoraineProvider to set component defaults across your application or within a subtree. defineTheme() changes component recipes and default variants. For colors, fonts, shadows, and sizing tokens, configure the UnoCSS preset or write CSS variables.
Defining a Theme with defineTheme#
Use defineTheme() from moraine/theme to create a reusable theme. Each key is a component name in camelCase (such as button, card, or dropdownMenu). Its value accepts base, variants, compoundVariants, and defaultVariants, all optional. These layers merge on top of the component’s built-in recipe. The returned theme is immutable.
Extending Themes#
Pass an existing theme to extends to build a specialized theme, such as a high-contrast or compact mode. The new theme applies the parent’s overrides first, then its own on top:
Scoping with MoraineProvider#
Wrap your application root or any subtree in MoraineProvider to apply a theme:
Provider Nesting Behavior#
theme prop |
Behavior |
|---|---|
Omitted or undefined |
Inherits the parent Provider’s theme unchanged. At root, uses built-in recipe defaults. |
defineTheme(...) |
Replaces the parent’s theme for this subtree. Overrides apply on top of built-in component recipes; the object is not merged with the ancestor’s theme. |
theme={null} |
Disables theming for this subtree: any inherited theme is dropped, and components use built-in recipe defaults. |
Omit the prop to keep the parent’s theme, pass a theme to replace it, and pass null to opt a subtree out of theming. Instance classes, styles, class, and style props still win over the theme.
locale, dir, and messages also inherit from the parent when omitted, with their own merge rules. See Localization.
Dynamic Theme Switching#
Changing the theme prop updates component classes without unmounting DOM nodes:
Interactive elements keep their focus, text selection, and native element references when themes switch.
State Selectors in Themes#
Variants define stable design dimensions (size, variant, tone). Style transient state (such as disabled or loading) with attribute selectors in base:
Portals & CSS Variables#
Overlay components (Dialog.Content, Popover.Content, Tooltip.Content) render into a Portal attached to the trigger’s document.body by default.
Portaled nodes sit outside their parent container in the DOM tree, so CSS custom properties declared on local container elements do not cascade into portaled overlays.
Dialog, Sheet, and Drawer accept a mount node, so you can portal them into a container that declares the variables. To pass custom variables or classes to any portaled overlay directly, set them on its slots: