Data

Table

Its own scroll container, sticky header, optional sticky first column, two densities, zebra and hover, and an opt-in stacked layout. The scroll container is a separate block because a scrollable region has to be focusable and named: a keyboard-only reader cannot reach content that only a pointer can scroll.

Scrolling, with the header and the first column pinned

Seven columns and eight rows inside a box capped at 14rem. On a phone this scrolls in both directions and the page itself does not move. Drag it sideways, or put focus in it with the keyboard and use the arrow keys: the column headings and the region names stay on screen while the figures move under them.

scope="col" and scope="row" are not optional: without them a screen reader cannot announce which column a cell belongs to, and no amount of CSS can supply that. A sticky header needs a bounded block size on the wrapper, which --bs-table-scroll-max-block sets here and bs-table-scroll--capped sets at 70dvh. There is no CSS that makes a horizontally scrolling table stick its header to the viewport: once one axis is auto the other can never stay visible outside the box, which is why the header sticks inside this wrapper and not to the window.

Both densities

The same figures at both settings, side by side, so the difference is something you can see rather than a row in a table of modifiers.

Sorting

CSS can paint a sorted table and cannot sort one, so this is the one example on the page where a column header does something. Press a header, or reach it with the keyboard and press Enter: the rows reorder and aria-sort on that header changes, which is what a screen reader reads when it lands on the column.

The header holds a real button, so activation, focus and the keyboard belong to the platform rather than to a script. Only a header carrying aria-sort is sortable, which is how a table sorts on two of its six columns. "2 hours ago" is prose and not a date, so the Updated cells carry data-bs-sort-value with the value the string stands for. Direction is never signalled by colour alone: it lives in the attribute a screen reader announces.

Stacked, instead of scrolled

The other answer for a narrow screen: below 48em each row becomes a block and each cell states its own column name. Narrow this window, or read this page on a phone, and the table below is already stacked.

It is opt-in because display: block on table elements removes the implicit table semantics in every engine, so the roles have to be written back into the markup and every cell has to carry its own data-label. Announcement of generated content varies between screen readers, so where guaranteed parity matters, keep the scrolling table above: its semantics are intact at every width.

Card

A card is a container, not a control. The interactive variant must not put a click handler on the card element, because a div with a click handler is invisible to the keyboard and to assistive technology. Put a real link inside and let it cover the card: tab to the first card below and the ring is drawn around the whole panel.

bs-card__link stretches its hit area over the whole card, so the pointer target is the card while the accessible name, the role and the focus behaviour all come from the anchor. The focus ring is drawn around the card rather than the text, since the text is only part of the target. The image is decoration beside a title that already says what the card is, so its alt is empty, and its dimensions are in the markup: without them the grid reflows the moment it loads.

Stat

A single figure with its label, and an optional change indicator. The label and the value are one unit, which a description list says and a pair of divs does not.

Direction must not be carried by colour alone. The arrow carries it visually, and because the arrow is aria-hidden the direction has to reach a screen reader in the text, which is why the examples above read "up 12.4%" rather than a bare percentage in green. If the figure updates while the page is open, put aria-live="polite" on bs-stat__value.

List

Lists used as data: divided rows, inline runs, and a plain list with no markers. Removing the marker removes the list semantics in Safari and VoiceOver, so every variant that hides markers has to declare the role it just lost.

The role is required on --plain, --divided and --inline. A bare bs-list keeps its markers and needs no role. --interactive styles the row around a real control; it does not create one, which is why the middle example holds anchors and its row highlight answers to :focus-within as well as to hover. Tab into it to see the row light up.

Description list

Key and value pairs: the shape most product detail panels actually want, and the one most of them build out of divs. Direct dt and dd children, no wrappers, because the two-column variant places children by source order.

One term may be followed by several descriptions, which is how HTML expresses a key with several values. Do not repeat the term to fake it: a screen reader announces the repeat as a second term.

Badge

A status pill: small, filled, not interactive. A badge carries state, so the state has to be in the text and not only in the fill. Colour alone fails SC 1.4.1 and is invisible to anyone with a colour vision deficiency.

A count badge attached to something else needs its own label, or a screen reader reads a bare number with no idea what it counts. If the value changes while the page is open, add aria-live="polite" so the change is announced rather than silently repainted. --pin is absolutely positioned, so its host needs position: relative and enough room not to be overlapped by its own count.

Tag

A badge states a status the system owns. A tag states a value the reader applied and can usually take back. Take one back: press a remove control below. The chip goes, focus lands on the next one instead of on the top of the document, and the line underneath says what left.

The remove button needs a name that says what it removes: "Remove" on its own gives a screen reader user a list of identical buttons. A chip that disappears is silent, so the removal is written into a role="status" line, and focus is moved deliberately, because removing the element that holds focus otherwise drops a keyboard reader at the top of the document. When a tag is a filter that toggles it is a button carrying aria-pressed with no remove control, which is the second row above. Press one: the attribute is the state, and because tag.css ships no rule for it, the markup names the modifier that paints it in data-bs-pressed-class and the two move together. A state only assistive technology can read is half a control.

Avatar

A fixed-ratio identity image with an initials fallback, and an overlapping group with an optional overflow count. Initials are a visual shorthand, never a name, so they are hidden and the container is named.

src/data/avatar.css, adds 996 B gzip Copy markup

AL GH KJ MJ OP

Show codeHide code

An avatar next to the person's name is decorative and takes an empty alt, or every row in a list is announced twice. An avatar standing alone is the only thing naming the person, so it carries the name. Always set width and height on the image so the row does not reflow when it loads.

Stacked

A group overlaps its children and is its own scroll container, so a run longer than the column scrolls inside its own box instead of making the page scroll sideways. The second group below is deliberately too long for a phone: drag it, or tab to it and use the arrow keys.

CSS cannot count children, so the truncating is yours: cut the run in markup and let the count carry the remainder. What the file guarantees instead is that the failure stays local. Anything that scrolls has to be reachable without a pointer, so a group that can overflow takes tabindex="0", and the name goes on aria-label rather than on a role that would replace role="list".

Keycap

For documenting a key a reader presses, not for code. A chord is several keys, so it is several elements: one keycap holding "Ctrl+K" tells assistive technology it is a single key with a plus sign in its name.

Key names are capitalised in the markup rather than by text-transform, so a screen reader reads the same string a sighted reader sees.

Divider

Plain, labelled or vertical. The labelled section rules on this page are the same component. A labelled divider cannot be an hr, because that is a void element and cannot hold the label, so it is a div with the role restored.

The default colour is the decorative hairline. A divider that has to be perceivable as structure rather than read as a hint of one uses --strong, which clears the 3:1 non-text floor. The second rule above is that one.

Empty state

What a table, list or panel shows when it has nothing to show. The icon is decoration and is hidden; the title carries the meaning.

The state a filter actually produces

The case worth building for is not the panel that was born empty, it is the one that emptied while the reader was looking at it. Type in the box below. As soon as nothing matches, the table and its scroll wrapper leave together and the empty state takes their place inside a live region, so the change is announced rather than only seen. Clear the box and the rows come back.

Two things here are the consumer's rather than the framework's. The swap has to be announced, so the pair sits inside aria-live="polite". And the table's wrapper has to leave with the rows: left behind, it is a named, focusable, empty scrolling region whose caption points at nothing. Hiding uses the hidden attribute rather than a class, because src/core/reset.css makes it display: none !important and so takes the row out of the box tree and out of the accessibility tree in one move.