Skip to main content

Customization

Style override layers, slot-based styling, and data-slot DOM contracts.

View as Markdown

Moraine components expose typed slots and four class override layers. CSS theme tokens are a separate mechanism: change a semantic color or radius in CSS to update every component that uses the token. With UnoCSS, presetMoraine() emits neutral defaults and accepts named color overrides; with Tailwind, define the tokens in CSS. Use defineTheme() to change component recipes or default variants.

The 4-Layer Override Hierarchy#

Choose the layer that matches the scope of your change:

Layer Surface Scope How to configure
1 Base Recipe Library defaults Built-in styles shipped with Moraine.
2 Theme Layer Application or subtree defaults Wrap in <MoraineProvider theme={defineTheme(...)}>
3 Instance Slots Named slots on one instance classes={{ slot: '...' }} / styles={{ slot: { ... } }}
4 Direct Element The root element, or one part of a composite class="..." / style={{ ... }} on that component

How Classes Merge Across Layers#

Classes merge in ascending priority (Layer 1 → Layer 2 → Layer 3 → Layer 4) with Moraine’s cn merger. When utilities conflict (for example bg-primary and bg-danger, or p-2 and p-4), the higher layer wins. Two refinements apply: the classes of an ancestor component sit between the Theme layer and the instance, and classes a component enforces for functional reasons (positioning, virtual scroll sizes) always win and cannot be overridden. styles and style merge per property in the same order, and undefined or null values are skipped.

import { Button } from 'moraine'

export function CustomAction() {
  return (
    <Button
      tone="danger"
      // Layer 4: `class` adds a shadow to the root element
      class="shadow-lg"
      // Layer 3: slot `classes` style the inner elements
      classes={{
        label: 'font-mono uppercase tracking-widest',
        leading: 'text-danger-foreground',
      }}
    >
      Delete Project
    </Button>
  )
}

See Composition for public parts versus style slots, and Theming for app-wide defaults (Layer 2).

Style Slots & the data-slot Contract#

CamelCase in TSX Props#

In TSX, slot names on classes and styles are always camelCase:

import { Select } from 'moraine'

export function StyledSelect() {
  return (
    <Select
      classes={{
        control: 'rounded-xl border-primary/50 shadow-sm',
        content: 'p-1 rounded-xl shadow-xl',
        item: 'py-2 px-3 rounded-lg',
        itemLabel: 'font-medium',
      }}
    />
  )
}

Kebab-case data-slot in DOM#

In the rendered DOM, Moraine tags each slot element with a kebab-case data-slot attribute:

  • Root slot: data-slot="<component>" (for example data-slot="button").
  • Other slots: data-slot="<component>-<slot>" (for example data-slot="select-control" and data-slot="select-item-label").

Use this contract for global CSS selectors and test queries:

/* Custom backdrop blur for all Moraine select dropdowns */
[data-slot='select-content'] {
  backdrop-filter: blur(12px);
}

TypeScript Slot Types#

Each component namespace exports typed Classes, Styles, and Slot shapes:

import type { ButtonT, CardT } from 'moraine'

// Type-safe slot class overrides
const buttonClasses: ButtonT.Classes = {
  root: 'rounded-full px-5',
  label: 'tracking-wide font-medium',
}

// Union of all available slot names for Card
type CardSlots = keyof CardT.Slot // 'root' | 'header' | 'title' | 'description' | 'action' | 'body' | 'footer'