Using data-* Attributes in CSS and JavaScript for Component State

CSS data attributes state switching is the pattern where the browser's own attribute selector engine decides what a component looks like, and the attribute itself is the only thing that changes. Instead of toggling classes with JavaScript, you set a value on a data-* attribute. CSS rules that match that value compute the visual result. The technique replaces the class-toggling pattern where JavaScript adds or removes .is-active, .is-loading, or .has-error to flip a component between states. The win is not specificity. A data-* attribute selector has (0,1,0) specificity, identical to a class, so the cascade priority is the same. The win is semantics and single-source-of-truth: the attribute name carries meaning about the state, and the value is the state machine's current step. You read the DOM and know exactly what the component is doing without inspecting computed styles or remembering which class means what.

An attribute selector like [data-theme="dark"] matches an element that carries that exact attribute and value. It is a plain selector with (0,1,0) specificity, no different from .is-active in the cascade. What differs is that the attribute is also readable by JavaScript via the dataset property, making it the single source of truth for both the style engine and the script. The data-* naming convention is part of the HTML specification. Any attribute name prefixed with data- is valid and never collides with standard attributes. When you change the value with element.dataset.theme = 'dark', the attribute updates, the browser recalculates styles, and the matching rule applies. That is the entire mechanism: a state change expressed as an attribute mutation, and CSS responds declaratively.

JavaScript access comes through two paths. The dataset property converts the hyphenated name to camelCase: data-theme becomes dataset.theme, data-load-state becomes dataset.loadState. The getAttribute and setAttribute methods use the exact string, so getAttribute('data-theme') works when you need the raw name, for example when building a selector string. For reading values like JSON stored in a data attribute, JSON.parse(dataset.config) is the pattern, but only after you have set the attribute with a valid JSON string. The choice between dataset and getAttribute matters when the attribute does not exist: dataset returns undefined, while getAttribute returns null. The distinction is a common source of subtle bugs in state checks.

Component state without CSS classes means the state lives in the attribute, not in a class list. This is a shift in how you think about the DOM. A class is a label that may or may not have meaning. A data attribute with a value is a structured field. For a theme variant switch, you set data-theme on the root element of the component, and CSS rules for each variant match that value. For a UI state machine, you set data-state to one of the machine's states. The CSS for each state is a separate rule. The state machine concept applies directly: the attribute holds the current state, and transitions happen by changing the value. CSS custom properties hold the derived values that the state rules set. The state change becomes a switch that reassigns the property values, and the component's internals read those properties via var().

Build the Theme Switch

Here is the first complete sample: a theme variant switch. The HTML has a container with data-theme="light" initially. The JavaScript changes that value to dark or light when a button is clicked. The CSS uses the attribute selector to set background and text colors, plus custom properties that the rest of the component inherits.

<div id="card" data-theme="light">
  <h3>Sample Card</h3>
  <p>This card changes theme via data-theme.</p>
  <button id="toggle">Toggle Theme</button>
</div>

const card = document.getElementById('card');
document.getElementById('toggle').addEventListener('click', () => {
  card.dataset.theme = card.dataset.theme === 'light' ? 'dark' : 'light';
});

#card[data-theme="light"] {
  --bg: #ffffff;
  --fg: #1a1a1a;
}
#card[data-theme="dark"] {
  --bg: #1a1a1a;
  --fg: #ffffff;
}
#card {
  background: var(--bg);
  color: var(--fg);
  border: 1px solid var(--fg);
  padding: 1rem;
  transition: background 0.3s, color 0.3s;
}

The data-* attribute selector here is specific to the element with the id, but the specificity is the same as a class: (0,1,0). The cascade treats it exactly like .card--dark. The benefit is that the attribute value is set by JavaScript and read by CSS without any extra lookup, and the same attribute is available to any script that needs to know the current theme.

If you need to match any element that has a data attribute regardless of its value, the selector [data-theme] works. Use it for setting base styles that apply only when the attribute exists, like a default padding or a border that appears only once a state is set. The attribute selector also supports operators: [data-theme^="dark"] matches values starting with dark, [data-theme*="ark"] matches substrings, and [data-theme~="dark"] matches exact tokens in a space-separated list. These operators give you a small pattern-matching language that classes do not have. The core use remains a simple equality check, because that is what a state machine needs: one value per state.

Wire Up the State Machine

The second sample is a UI state machine with four states: loading, empty, error, success. The component holds a data attribute data-state, and JavaScript sets it when an asynchronous operation completes. The CSS has a rule per state. Each state changes what is visible and what the message text is. The state machine concept is explicit: the attribute is the single source of truth, and any code that changes it must set a valid state.

<div id="async-list" data-state="loading">
  <p class="state-msg">Loading…</p>
  <ul class="items"></ul>
  <p class="state-error">Something went wrong.</p>
  <p class="state-empty">No items found.</p>
  <p class="state-success">Loaded successfully.</p>
</div>

const container = document.getElementById('async-list');
// Simulated fetch
setTimeout(() => {
  const ok = Math.random() > 0.3;
  container.dataset.state = ok ? 'success' : 'error';
}, 1000);

#async-list[data-state="loading"] .state-msg { display: block; }
#async-list[data-state="success"] .state-success { display: block; }
#async-list[data-state="empty"] .state-empty { display: block; }
#async-list[data-state="error"] .state-error { display: block; }
#async-list .state-msg,
#async-list .state-success,
#async-list .state-empty,
#async-list .state-error { display: none; }
#async-list[data-state="success"] .items { display: block; }
#async-list .items { display: none; }

Recalculation Cost and Fallback

The style recalculation cost is minimal. Changing one attribute triggers a re-match of the selectors that involve that attribute. The browser does not need to re-evaluate unrelated rules. The fallback for browsers that do not support attribute selectors is non-existent, because attribute selectors are baseline. The failure case is when JavaScript sets an invalid value, like data-state="pending". None of the state rules match, and the component shows nothing. Guard against that by validating in the setter, or by using a default rule that catches unknown values with [data-state] and a fallback style.

Build a Tooltip with Zero JavaScript

The third sample is a CSS-only tooltip that uses the attr() function in the content property to display text stored in a data attribute. This is the only place where attr() is widely supported: on the content property of pseudo-elements. The HTML has a button with data-tooltip="Save changes". The CSS reads that value to generate the tooltip text. No JavaScript is needed for the display; the attribute is the content source.

<button class="tooltip-trigger" data-tooltip="Save changes">Save</button>

.tooltip-trigger {
  position: relative;
}
.tooltip-trigger::after {
  content: attr(data-tooltip);
  position: absolute;
  bottom: 100%;
  left: 50%;
  transform: translateX(-50%);
  background: #333;
  color: #fff;
  padding: 0.25rem 0.5rem;
  border-radius: 3px;
  white-space: nowrap;
  opacity: 0;
  transition: opacity 0.2s;
  pointer-events: none;
}
.tooltip-trigger:hover::after,
.tooltip-trigger:focus::after {
  opacity: 1;
}

Limits of attr()

The attr() function here returns a string, and the content property accepts it directly. The computed value is the text from the attribute, so the tooltip always matches the data, even if the attribute changes at runtime. The common mistake is expecting attr() to return a non-string type, such as a number or color. In shipped implementations it always returns a string. Browser support for attr() outside content is limited; check caniuse before using it on width or background-color. For this tooltip, the fallback is trivial: the text is already in the attribute, and you could duplicate it in a title attribute for native tooltip support.

The attr() function is defined in the CSS Values and Units Level 5 specification. Its use on the content property is baseline, supported in all engines since around 2008. Outside content, support is not baseline. Test with an @supports guard like @supports (width: attr(data-w type())) before relying on it. The accepted fallback for non-content uses is to write the value into a CSS custom property via JavaScript, then read that property with var(). That pattern keeps the data in the attribute as the source of truth and moves the computed value into the style system. The distinction matters: attr() on content is safe everywhere; attr() on other properties is a Chromium-only experiment that may change.

An attribute selector, a class selector, and a pseudo-class like :hover all have specificity (0,1,0). This is the unitless triple that the cascade uses to order declarations. When you write [data-state="loading"] and .is-loading, they fight on equal ground. Source order decides the winner. The advantage of the data attribute is not specificity; it is the semantic load. A class name like .is-loading says nothing about what is loading. data-state="loading" names the state machine and its current step. The cascade still applies the same rules: origin, layer, specificity, and source order. If you need to override a data attribute rule from a component, use a higher-specificity selector like an id, or rely on cascade layers to give your override a later priority. Neither approach is inherently better; the choice is about maintainability.

When to Use a Class Instead

There are cases where a class is the right tool. If the state is purely presentational, like a hover effect that a visitor triggers with a mouse, a class or pseudo-class is fine. If the state has no value beyond being present or absent, a class is simpler. But if the state has multiple values, like loading, empty, error, success, a data attribute with a controlled vocabulary is clearer. The rule of thumb: if a human or a script needs to read the state and know what it means without looking up a mapping, use a data attribute. If the state is a boolean flag with no further information, a class is acceptable.

CSS custom properties are the bridge between the state attribute and the visual detail. In the theme sample, the state rules set --bg and --fg, and the component reads them via var(). This is a common pattern: the state attribute selects a rule, that rule assigns custom property values, and those values inherit down the DOM subtree. The inheritance works because custom properties are inherited by default. The computed value of --bg on the container is passed to every child that uses it. This keeps the state logic in one place and the visual variables in another. The cost is a cascade step: the browser must resolve the custom property value, then compute the property that uses it. For most components, this is negligible. The failure mode is when a custom property is not set, leaving var() with no fallback. The declaration becomes invalid at computed-value time and the property stays at its initial value.

When JavaScript sets a data attribute, the browser marks the element as needing a style recalculation. The engine then re-evaluates selectors that could match that element, specifically those that reference the attribute. This is a scoped operation, not a full page recalc. The cost depends on the selector complexity. A simple [data-state] is cheap. A long compound selector with :has() or attribute operators can be more expensive. Keep state selectors simple: an element selector plus the attribute, occasionally a descendant or child combinator. Avoid putting data attribute selectors inside :has() unless you have measured the cost. A broad :has() can force the engine to scan many elements. When you change the attribute, the transition property can animate the change, but only if the property being changed is animatable. For example, display does not transition. A state change from display: none to display: block is instant. opacity and transform do transition.

The dataset property is a DOMStringMap that reflects all data attributes on an element. Reading element.dataset.state gives you the value of data-state. Writing to it sets the attribute. The camelCase conversion means data-load-state becomes dataset.loadState. When you need to set an attribute that has a hyphen, use the camelCase version; the browser converts it back. For dynamic attribute names, like a state that comes from a variable, you cannot use dataset directly. Use setAttribute('data-' + key, value). The getAttribute method returns the raw string, which is useful for comparisons. A common pattern: read the current state, compare it to a target, and then set the new value. if (el.dataset.state !== 'success') { el.dataset.state = 'success'; }. This avoids unnecessary recalculations when the state has not changed.

The attr() function is a CSS functional notation that retrieves an attribute's value from the element or a pseudo-element's originating element. On the content property, it is supported everywhere and returns a string. On other properties, such as width or color, support is limited to Chromium, and the specification is still evolving. Check caniuse for the current state. The attr() function outside content requires a type hint, like attr(data-width type()). Even then the browser may ignore it. The safe approach: use attr() only for content. For other properties, read the attribute with JavaScript and set a custom property. The failure case is writing width: attr(data-width) and expecting it to work in Firefox. It will not. The declaration is ignored, leaving the property at its initial value. Always test with @supports if you try to use it elsewhere.

The honest comparison is not that data attributes are always better. They serve different roles. A class is a label that can be applied to multiple elements and combined freely: .is-active and .is-disabled can both be present. A data attribute with a single value is exclusive. data-state="loading" cannot also be data-state="success". That exclusivity is exactly what a state machine needs. The attribute name is part of the selector, so you get namespacing for free: [data-theme] does not collide with [data-state]. With classes, you rely on naming conventions like BEM to avoid collisions. The specificity is the same. The cascade does not favour one. The real difference is in the DOM. A data attribute is self-describing. A class requires external documentation. For a component that is used by other developers, the data attribute is a contract; the class is an implementation detail.

The most common failure is setting an attribute value that does not match any selector. The component silently renders with default styles. Inspect the element in the browser's developer tools and confirm the attribute value. Another failure is expecting attr() to return a number for arithmetic. It returns a string, so calc(attr(data-width) * 2) fails unless the browser supports the typed attribute syntax. A third failure is relying on attr() outside content without checking support. The declaration is dropped. The property stays at its initial value. A fourth failure is using dataset to read a value that has not been set, which returns undefined. A strict comparison to a string will fail silently. Debug by logging the attribute value in JavaScript, checking the computed style in devtools, and verifying that the selector syntax is correct, including the brackets and quotes.

The cascade is the mechanism that resolves competing declarations. When you have #card[data-theme="light"] and #card setting the same property, the more specific selector wins. If specificity is equal, the last one in source order wins. The computed value is the result of resolving the cascade, including any custom property substitutions. Inheritance plays a role when the state attribute is on a parent and the property is inherited, like color or a custom property. The state rule on the parent sets the value. Children inherit it unless they override. Computed value stability is a concern when you rely on a custom property that is set by a state rule. If the state changes, the custom property changes. Any dependent property recomputes. This is a chain of dependencies that the browser handles internally. Be aware that changing a state attribute can cause multiple property recalculations.

Q: Does using a data attribute instead of a class affect performance?
A: No meaningful difference. Both trigger a style recalculation scoped to matching selectors. Keep selectors simple, and the cost is negligible.

Q: Can I use data attributes for boolean states like active or disabled?
A: Yes. Use data-active="true" or data-active="false". For a simple flag, a class is also fine, but the attribute is more explicit.

Q: What happens if JavaScript sets an invalid state value?
A: The element matches no specific state rule, so it falls back to any default rule. Add a rule for [data-state] that catches unknown values.

Q: Is attr() safe to use for anything other than content?
A: No. Only Chromium supports it outside content. Check caniuse for current support. Use content with attr(), or set custom properties via JavaScript for other properties.

This approach is not a silver bullet. The attribute selector is still a selector. The cascade applies, specificity matters, and you can create the same tangled mess with data attributes that you could with classes if you do not plan. The single-source-of-truth benefit only holds if you actually treat the attribute as the only source. No script writes a class to override a state. No inline style sets a property that a state rule should control. The browser is the final renderer. It will compute whatever the cascade says. Keep the state machine small. Keep the attributes few. Keep the selectors simple. The pattern is maintainable and honest. If you try to encode every possible visual variation into a data attribute, you will end up with a selector explosion that is harder to read than a class list. The tool is right for the job when the job is a state machine, not when the job is a visual theme with dozens of degrees of freedom.