Customization
Style override layers, slot-based styling, and data-slot DOM contracts.
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.
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:
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 exampledata-slot="button"). - Other slots:
data-slot="<component>-<slot>"(for exampledata-slot="select-control"anddata-slot="select-item-label").
Use this contract for global CSS selectors and test queries:
TypeScript Slot Types#
Each component namespace exports typed Classes, Styles, and Slot shapes: