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>

<style>

  /* Conflicting specificity */

  .btn-primary { ... }

  .btn-lg { ... }

  .btn-primary.btn-lg { ... }

</style>

<button class="btn"

  data-variant="destructive"

  data-size="lg">

  Delete

</button>

<style>

  /* Flat specificity - no combos needed */

  .btn[data-variant="destructive"] { ... }

  .btn[data-size="lg"] { ... }

</style>

§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;

  cursor: not-allowed;

}

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.

Comments, ideas or improvements? Edit this page's source on GitHub