Chapter 5: Styling

Core Idea

Every part exposes the same four style hooks — className (string or state-function), data-* attributes, CSS custom properties, and a style prop (also state-function-capable) — so Tailwind, CSS Modules, and CSS-in-JS all plug in the same way, without any Base-UI-specific styling API to learn.

Key Concepts

• className prop: accepts a string, or a function (state) => string that receives the component's current state object (e.g. (state) => state.checked ? 'checked' : 'unchecked').
• Data attributes: every stateful part exposes data-* attributes for its states (e.g. Switch's [data-checked]/[data-unchecked]) — style off these directly in CSS, never by mirroring state into your own class toggling.
• CSS variables: parts expose dynamic numeric values as custom properties for sizing/transform math (e.g. Popover's Popup exposes --available-height, --anchor-width) — check each component's own chapter/API reference for its full variable list.
• style prop: accepts a CSS object, or a function (state) => cssObject, mirroring the className function form.
• Three supported engines, same pattern: Tailwind classes reference data-* states directly (data-pressed:bg-neutral-100); CSS Modules classes target [data-state] selectors in a .module.css file; CSS-in-JS wraps each part with styled(Menu.Trigger) etc. and targets the same attributes.

Code Examples

/* Tailwind — data-attribute-driven state styling */
<Menu.Trigger className="... data-pressed:bg-neutral-100 focus-visible:outline-2 ..." />

/* CSS Modules — same data attribute, targeted in a stylesheet */
.SwitchThumb[data-checked] { background-color: green; }
.Popup { max-height: var(--available-height); }

/* CSS-in-JS — wrap each part once, compose normally */
const StyledMenuPopup = styled(Menu.Popup)`/* styles */`;

• What it demonstrates: the same [data-pressed]/[data-checked]-style attribute selector works identically regardless of which of the three styling engines renders it.

Key Takeaways

1. Always style off data-* attributes, never by tracking component state in your own React state and toggling classes manually — the attributes are the intended, documented styling contract.
2. Use the function form of className/style when a class needs to react to state that isn't already exposed as a data-* attribute (rare, but available as an escape hatch).
3. Check the specific component's chapter before styling it — CSS variable names (--anchor-width, --available-height, --transform-origin, etc.) are component-specific and documented per component, not globally.

Connects To

• ch006 (Animation): [data-starting-style]/[data-ending-style]/[data-open]/[data-closed] are the animation-specific subset of this same data-attribute system.
• ch007 (Composition): asChild/render let you swap the rendered element while keeping these same style hooks.
• Every component chapter's own "Reference Tables" section lists its specific data-* attributes and CSS variables.