Skip to main content

Theming

Define application-wide theme presets, provider scoping, dynamic theme switching, and portal styling.

View as Markdown

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.

src/theme/brand-theme.ts
import { defineTheme } from 'moraine/theme'

export const brandTheme = defineTheme({
  button: {
    defaultVariants: {
      size: 'sm',
    },
    base: {
      root: 'rounded-xl font-medium tracking-tight shadow-xs',
    },
    variants: {
      variant: {
        outline: {
          root: 'border-primary/40 text-primary hover:bg-primary/10',
        },
      },
    },
    compoundVariants: [
      {
        variants: { size: 'sm', variant: 'outline' },
        root: 'border-2',
      },
    ],
  },
  card: {
    base: {
      root: 'rounded-2xl border-border/80 shadow-sm bg-card',
      header: 'border-b border-border/60 pb-3',
    },
  },
})

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:

export const highContrastTheme = defineTheme({
  extends: brandTheme,
  button: {
    base: {
      root: 'border-2 font-bold contrast-125',
    },
  },
})

Scoping with MoraineProvider#

Wrap your application root or any subtree in MoraineProvider to apply a theme:

src/App.tsx
import { MoraineProvider } from 'moraine'
import { brandTheme } from './theme/brand-theme'

export function App(props) {
  return <MoraineProvider theme={brandTheme}>{props.children}</MoraineProvider>
}

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:

import { createSignal } from 'solid-js'
import { MoraineProvider, Button } from 'moraine'
import { defaultTheme, compactTheme } from './themes'

export function ThemeSwitcherApp() {
  const [currentTheme, setCurrentTheme] = createSignal(defaultTheme)

  return (
    <MoraineProvider theme={currentTheme()}>
      <Button onClick={() => setCurrentTheme(compactTheme)}>Switch Theme</Button>
    </MoraineProvider>
  )
}

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:

const theme = defineTheme({
  button: {
    base: {
      root: 'data-disabled:opacity-50 data-disabled:cursor-not-allowed data-loading:cursor-wait',
    },
  },
  select: {
    base: {
      control: 'focus-within:ring-3 focus-within:ring-ring/50',
    },
  },
})

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:

import { Dialog, Button } from 'moraine'

export function ScopedDialog() {
  return (
    <Dialog
      styles={{
        overlay: { '--backdrop': 'rgb(0 0 0 / 0.75)' },
        content: { '--popover': 'oklch(25% 0 0)', '--popover-foreground': 'white' },
      }}
    >
      <Dialog.Trigger as={Button}>Open Modal</Dialog.Trigger>
      <Dialog.Content title="Custom Styled Dialog">
        <Dialog.Body>The scoped variables apply correctly here.</Dialog.Body>
      </Dialog.Content>
    </Dialog>
  )
}