Data Attribute API

Props → Data Attributes

If you came from a component framework, this mapping should feel familiar.

<Button
  variant="destructive"
  size="lg"
>
  Delete
</Button>

<button class="btn"
  data-variant="destructive"
  data-size="lg"
>
  Delete
</button>

How it works

Every component has exactly two layers in its markup: a class and its data attributes.

The CSS combines these with attribute selectors: .btn[data-variant="outline"]. No modifier classes, no BEM suffixes, no utility chains.

Why data attributes instead of modifier classes?

Traditional systems like Bootstrap and BEM use modifier classes: .btn-primary, .btn--lg, .btn-outline-danger. Here's why we don't.

<button class="btn btn-destructive btn-lg">
  Delete
</button>

/* Conflicting specificity */
.btn-primary { ... }
.btn-lg { ... }
.btn-primary.btn-lg { ... }

<button class="btn"
  data-variant="destructive"
  data-size="lg">
  Delete
</button>

/* Flat specificity */
.btn[data-variant="destructive"] { ... }
.btn[data-size="lg"] { ... }
/* no combo needed */

Styling attributes

These are set in your HTML and read by CSS. They control the visual appearance of components.

data-variant

The most common attribute. Controls the visual style of a component.

data-size

Controls height, padding, and sometimes font-size.

Other styling attributes

Some components have additional axes beyond variant and size.

Behavioral attributes

These wire up JavaScript interactions. They follow the pattern data-{component}-trigger and data-{component}-close — connecting a button to the element it controls.

<!-- The trigger: its value is the ID of the target -->
<button class="btn" data-dialog-trigger="confirm">
  Open Dialog
</button>

<!-- The target: matched by ID -->
<dialog id="confirm" class="dialog">
  <div class="dialog-content">
    <p>Are you sure?</p>
    <!-- The close: placed inside, closes the nearest parent -->
    <button class="btn" data-dialog-close>Cancel</button>
  </div>
</dialog>

State attributes

These are set and removed by JavaScript at runtime to represent UI state. CSS reads them to apply state-specific styles. You don't write these in markup — the JS manages them.

ARIA attributes as styling hooks

Where the browser natively provides state APIs — like aria-selected, aria-expanded, or disabled — we style against those directly. No data attributes are needed because the browser already exposes the state.

/* Tab is selected — use ARIA, not a data attribute */
.tab-trigger[aria-selected="true"] {
  color: var(--foreground);
  border-color: var(--primary);
}

/* Toggle is pressed — native ARIA attribute */
.toggle[aria-pressed="true"] {
  background: var(--accent);
}

/* Button is disabled — native HTML attribute */
.btn:disabled {
  opacity: 0.5;
  pointer-events: none;
}

Rule of thumb: if the browser has a native attribute for a state (disabled, aria-selected, aria-expanded, open), we style against that. Data attributes are only used when no native equivalent exists.

The pattern at a glance

Every component follows this structure. Once you learn one, you know them all.

<element
  class="{component}"             ← what it is
  data-variant="{variant}"        ← visual style
  data-size="{size}"              ← dimensions
  data-{axis}="{value}"           ← other config
  data-{component}-trigger="{id}" ← JS wiring
  aria-*/disabled/open            ← native state
>
  content
</element>

<button class="btn"
  data-variant="outline"
  data-size="sm">
  Edit
</button>

<span class="badge"
  data-variant="secondary">
  New
</span>

<dialog class="sheet"
  data-side="left"
  id="nav">
  ...
</dialog>

Each component's component-skill.md lists the complete set of supported data attributes, variants, sizes, and ARIA requirements.