---
title: Customization
description: Style override layers, slot-based styling, and data-slot DOM contracts.
package: moraine
version: 0.11.0
repository: https://github.com/subframe7536/moraine
---

# 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.

```tsx
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](https://moraine.subf.dev/docs/composition.md) for public parts versus style slots, and [Theming](https://moraine.subf.dev/docs/theming.md) 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:

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

```css
/* 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:

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

