---
title: Theming
description: Define application-wide theme presets, provider scoping, dynamic
  theme switching, and portal styling.
package: moraine
version: 0.11.0
repository: https://github.com/subframe7536/moraine
---

# 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](https://moraine.subf.dev/docs/unocss.md#theme-tokens) 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.

```ts title="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:

```ts
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:

```tsx title="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](https://moraine.subf.dev/docs/localization.md).

## Dynamic Theme Switching

Changing the `theme` prop updates component classes **without unmounting DOM nodes**:

```tsx
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`:

```ts
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:

```tsx
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>
  )
}
```

