API quick reference

The package supplies CSS only. Applications supply state, events, validation, focus, live announcements, and persistence. Full markup, state, and customization reference.

Shell and navigation

.app-shell has a direct main and optional header/footer. .site-header, .site-header-brand, .site-header-links arrange native links and buttons; use aria-current="page" for the current destination. .skip-link targets main.

Buttons and X actions

data-barba-variant: primary, secondary, tertiary, text, and icon. data-barba-intent="danger" supplies destructive appearance. Icon actions also use data-barba-shape="icon"; data-barba-size="compact" reduces the face, not the target. Native type, name, and disabled state remain required.

Fields

.inline-field has a direct visible label. .input-row wraps a field/group and action. .input-action requires a direct-child text/search input and icon button; nested component inputs and textareas need application layout. Hide clear when empty; restore focus before hiding it.

Chips

.chip-list wraps. Informational .chip stays noninteractive. A selectable button needs aria-pressed and a .chip-face child. .chip-removable contains a label span and separate compact X button; applications restore focus after removal.

Disclosures

details.disclosure has a direct summary with .disclosure-label, .disclosure-title, optional .disclosure-description, then .disclosure-content. Add .disclosure--filled for a filled header, shared inward/downward chevron, and an accent body border. Native open owns expansion; both variants share markup.

Dialogs

A named native dialog contains a direct .dialog-content-container with .dialog-header, .dialog-body, .dialog-footer. Add .dialog-header-actions for a close row. Optional data-barba-dialog-*: spacing=compact, height=content, room=extra, dividers=full. Applications own cancellation and initial/restored focus.

Visibility and customization

.visually-hidden retains supplemental text for assistive technology. Ordinary hidden suppresses rendering and tab stops; remove the attribute to reveal (the string “false” still hides). hidden="until-found" remains browser-managed. Customize public --barba- tokens; private --_barba- and compiler properties are not API. Decorative .text-gradient and .scaleup-on-hover are optional. Recheck contrast, focus, and target sizes after overrides.

Typography and links

Data tables

Semantic tables receive only a readable foundation. The wide example's scrolling belongs to this specimen, not the library.

Semantic color contract

Every named text role below is guaranteed against both the page and surface backgrounds. Borders and focus rings have a separate non-text contrast guarantee.

Form elements

Accessibility: Use visible associated labels, connect hints/errors with aria-describedby and preserve native validation. WAI forms guidance.

Submit is prevented in this non-networked example. Cancel is intentionally inert; Reset restores the initial values.

Chips

Accessibility: Selectable chips use aria-pressed and stable names; removal has a separate named button and deliberate focus restoration. Informational chips are text. APG toggle-button guidance.

Use informational chips for labels, toggle buttons for filters, and a separate X for removing a selection. Informational chips stay 1.5rem high (24px at a 16px root). Interactive chips have compact 28px short faces inside targets at least 44×44 CSS pixels. Labels wrap rather than truncate.

The remove X shares the close/clear background-only treatment: a compact face with a 2px inset inside its own 44px-wide target. Only the X target removes the chip; its label is not clickable. The transparent area above and below a filter face or X is part of that button. Removing a selection does not delete the category or saved item. These examples keep all changes local.

Allow the target space in layout: rows are about 20px taller than 24px chips, and removable chips reserve extra width for the X. Use normal wrapping and gaps; do not enlarge targets with overlapping absolute hit areas or negative margins. Informational chips have no tab stop. Each filter uses a native button with aria-pressed and a child span.chip-face; the button owns state and the span draws the compact face.

Dashed boundaries include clickable padding. Gray boundaries mark disabled buttons. Tab shows focus around the full target; selection uses a thicker face border. Removing moves focus to the next enabled X, the previous X, or Restore selections when none remain.

Disclosures

Accessibility: Keep native details/summary semantics; avoid redundant roles, tabindex and aria-expanded. Required instructions must remain visible. MDN summary guidance.

Use details.disclosure to group optional settings, filters, or supporting information. Both variants use the same native disclosure markup and a full-width summary target. Keep essential instructions visible outside collapsed sections.

Place the label in disclosure-label, its title in disclosure-title, optional supporting text in disclosure-description, and the body in disclosure-content. A heading can carry both label and title classes. Choose its level for the page hierarchy; the class only normalizes its appearance.

These examples use native disclosure behavior: Enter or Space opens a focused summary, and multiple sections can stay open. Checkboxes and Reset work locally without saving. Put links and inputs in the body. Extra header actions must be siblings outside the summary with separate targets, as in the filled filter example below. Nest only when the content needs that hierarchy.

These are recommendations, not restrictions. Both styles support the same content and native behavior. Chevrons point inward when collapsed and down when expanded, aligned with the title’s first line. Compare all disclosure states.

Bordered disclosure

Use .disclosure for an enclosing border, trailing chevron, and divider when open.

The summary target is at least 2.75rem high (44px at a 16px root size). Keyboard focus uses the library’s separate outline; hover and press tint the summary. The same panel treatment applies in both themes.

Use the native open attribute for an initially expanded section. Leave off the native name attribute to allow independent expansion. Do not add a button role, tabindex, or manually maintained aria-expanded to the summary. Applications own persistence and control behavior; no JavaScript is needed for opening and closing. If heading navigation inside a summary matters, check it with your target assistive technology, or place a section heading outside the disclosure. See summary heading guidance.

Unclassed details keeps the browser’s native appearance. App layouts own spacing between panels; the examples use a grid gap. Customize through the existing color, spacing, and radius tokens or scoped application CSS.

<details class="disclosure">
  <summary>
    <span class="disclosure-label disclosure-title">Preferences</span>
  </summary>
  <div class="disclosure-content">
    <p>Settings and controls go here.</p>
  </div>
</details>

Filled disclosure · working filters

Add .disclosure--filled to details.disclosure for a filled header, shared chevron, and accent-colored body border with a gap below the header. Use a persistent summary when selections matter even while the controls are collapsed.

Try selecting aldis and costco, then black and blue, and collapse Filters. “All stores” and “All categories” clear their own group; the X clears both. Each theme has independent, synthetic state. Nothing is saved or sent.

Application responsibilities: Keep the visible summary current in both states: show “All items” when neither group is restricted, otherwise join selected labels with middle dots in stable group order. Native aria-pressed buttons expose each selection; this example adds no duplicate live announcement. If filtering changes a results list, follow the result-status guidance for a persistent live region and concise counts.

Clear action: The X is a named button outside summary in the DOM, positioned inside the filled header before the chevron. Reserve its target space so it cannot cover the title or chevron. Clear and the chevron stay beside the first title line while the selected labels wrap together below it. Clear must not toggle expansion; focus summary before hiding the X. When expanded, keyboard navigation reaches Clear after the body controls; when collapsed, directly after summary. Empty groups select their “All” action. Applications own filtering, persistence, result announcements, and focus transitions.

Example-only code: The specimen-filter-* classes provide inline/wrapping summary text, field-group spacing, and sibling clear-action placement. They are not library APIs. disclosure-filters.js shares local selection/reset behavior with the state gallery; the CSS package contains no JavaScript. Reuse the public disclosure and chip hooks, then implement your application's layout and state.

<details class="disclosure disclosure--filled" open>
  <summary>
    <span class="disclosure-label">
      <span class="disclosure-title">Filters</span>
      <span class="disclosure-description">All items</span>
    </span>
  </summary>
  <div class="disclosure-content">
    <!-- Filter controls belong here. -->
  </div>
</details>

Full state gallery: no selections, short selections, and many selections, each collapsed and expanded, in both themes. The gallery includes reset, narrow panels, and bordered examples. The working controls are generated by example-only JavaScript; the markup and library styling remain reusable separately.

This minimal snippet stacks the description below the title. The working example adds application layout for the inline summary and clear button. The shared accessibility guidance above applies to both variants.

Inline forms and input actions

Accessibility: Keep labels visible and use one naming source for each X. Synchronize clear visibility and move focus to the input before hiding the control. WAI label guidance.

Use an inline-field wrapper for a visible standard-size, medium-weight label above an input-row. The input grows; Add wraps to the right when space runs out. An optional input-action groups a text input with its X. Ordinary stacked forms keep their existing appearance.

The X is our shared close/clear icon action: a native button with data-barba-variant="icon" and data-barba-shape="icon". It has a generous target, transparent resting face, a circular hover background inset by 2px, and a separate keyboard-focus outline. Disabled X actions use muted gray, retain the disabled opacity, and have no hover background. Its accessible name describes the action: “Clear item name” for an input, “Close dialog” for a modal. The icon is decorative; these actions do not delete saved data.

Input and Add

Add validates and reports locally; no information is saved or sent.

Input with an X

Only show the X when there is content. Keep its space reserved, and return focus to the input before hiding it. Applications handle clearing and synchronize visibility after typing, resets and programmatic value changes.

Initially empty

Controls associated with a separate form

Use the form attribute on both the input and its submit button. The label and row layout are identical.

Nothing added yet.

Outside a form

A standalone field can use the same input-action layout without a submit button.

Unavailable actions

For disabled or read-only inputs, a populated field retains a muted gray, disabled X instead of the enabled action color. It cannot change the value and has no hover background.

See the dialog examples for the same X button used to close a modal through its cancellation path.

Buttons

Accessibility: Use native types and disabled states, stable accessible names and visible keyboard focus. Color does not explain destructive behavior. Applications own action feedback and confirmation. APG button guidance.

Native submit, button, and reset types provide primary, secondary, and tertiary emphasis. Existing emphasis styles keep their text color on hover. Text and destructive actions below demonstrate the new optional treatments; their clicks only report local example state.

Motion and interaction

Accessibility: Keep meaning and operation available without animation or hover. Test reduced-motion preferences separately from static screenshots. MDN reduced-motion guidance.

Dialogs

Try the maintained item editor with Name, Notes, chips, disabled states, and long content.

Accessibility: Name each native dialog, choose initial focus deliberately, support Escape/cancellation and restore focus to the invoker or a logical fallback. APG dialog guidance.

Both dialogs start at the same viewport-relative top offset. Short content leaves the footer at the minimum-height bottom. Long content grows to the viewport cap, then only its body scrolls. Footer order is Reset, Cancel, Submit. Submit validates and closes; Cancel or clicking outside closes without validation; Reset restores initial values and stays open. Closing does not reset the form.

Content-fit dialogs with a close action

These examples keep the standard width and opt into compact padding, a content-fit minimum, and more vertical room. Full-width header and footer dividers meet the scrolling body. The close icon uses the background-only icon treatment and follows the same cancellation path as Cancel and Escape.