Skip to content

Chip

C-03 · Components · Actions

All elements · Chip on the Components page

Last checked 2026-10-22 · Awaiting approval · Accessibility tests

Copies the bun run a11y:approve command for Chip.

Chip

C-03WCAG 2.2 AA · Passed #396
Axis Values
data-variant soft (default) · filled · outlined
data-color info (default) · primary · success · warning · error · purple · electric-blue · pink · yellow · brown
data-size · data-shape sm 24px (default) · md 32px / square
data-clickable · aria-pressed · aria-disabled hover / selected / disabled
.qf-chip__delete · .qf-avatar deletable / leading avatar slot
Colors × variants
InfoPrimarySuccessWarningErrorPurpleElectricPinkYellowBrown
InfoPrimarySuccessWarningErrorPurple
InfoPrimarySuccessWarningError
With icon, avatar, delete, selection, sizes
Finance jdJane Doe Finance Disabled Medium 32px Square Truncated label that is much too long

Guidance

When to use

  • Use a chip to show a short status, type or tag on a record, such as Approved or Finance.
  • Use a deletable chip (.qf-chip__delete) for values the user has added and can remove, such as tags or filter terms.
  • Use a clickable chip (data-clickable with aria-pressed) for quick filters that turn on and off.
  • Use a chip with a leading avatar to show a person as a value.

When to consider something else

  • If the item runs an action, use a button; chips are values, not commands. See Button.
  • If the user picks several values from a known list, use a multi select, which holds its chips inside the control. See Select.
  • If the message is a page or section level notice, use a banner. See Banner.
  • If you only need to show a person, use an avatar with the name beside it. See Avatar.

Usability

Do
  • Keep labels to one or two words; truncate long labels and expose the full text.
  • Use the same color for the same status everywhere in the app.
  • Add an icon or clear wording when the color carries meaning, such as a check for success.
  • Use data-size="md" (32px) when chips are interactive in touch layouts.
Don’t
  • Don't use color as the only difference between statuses.
  • Don't put a delete button and a clickable chip action on the same chip.
  • Don't use the yellow, filled success or filled warning chips for text-critical status without checking contrast in each theme.

Accessibility

Keyboard

Chip keyboard
Keys Action
Tab Moves focus to a clickable chip or to a chip's delete button. Static chips are not focusable.
Enter or Space On a clickable chip, flips aria-pressed. On a delete button, removes the chip.

Roles and names

  • A static chip is a <span> with text; it needs no role.
  • A clickable chip is a <button class="qf-chip" data-clickable> with aria-pressed.
  • The delete button needs a name that includes the value, such as aria-label="Remove Finance"; "Remove" alone is not enough when several chips are shown.
  • A disabled chip uses aria-disabled="true".

Focus

  • After a chip is removed, the binding must move focus to the next chip, or the previous one, or the related input; the static layer just removes the node.
  • Clickable chips and delete buttons show the token focus ring.

Other requirements

  • Target size 2.5.8: the delete button is 16px; it passes only with enough space around it, so do not place delete chips edge to edge.
  • Color must not be the only cue (1.4.1). The a11y report lists several filled, outlined and yellow chips as known contrast debt in the dark and classic themes (1.4.3).
  • A truncated label uses title, which keyboard and touch users cannot read; also put the full text in the accessible name or show it on focus (1.3.1).
  • Announce removals in a live region when the chip set changes outside the user's focus (4.1.3).

Test your implementation too. This guidance covers the element as specified here. How a screen composes it (labels, order, announcements) still needs its own keyboard and screen reader check.

Accessibility tests

WCAG 2.2 AA · Passed

Passed the gate (run 358b316 on 2026-10-22): no finding in any theme. Awaiting a person’s approval of the checklist below.

Chip test checklist
Area Automated A person checks
General Passed Color is never the only cue, text alternatives say the same thing as the graphic, and the element reads the same in the light and the dark theme.
Zoom Passed At 200% zoom, at 320 CSS pixels wide and with the WCAG text-spacing overrides, nothing is lost, clipped or overlapping.
Keyboard Passed Every row of the Keyboard table works, focus is always visible and never trapped, and the tab order follows the reading order. (2 rows)
Screen reader Passed With NVDA or JAWS on Windows and VoiceOver on macOS, names, roles and states are announced as Roles and names says, and changes are announced once. (4 items)

Approving. When the checklist passes on the checked run, record it with bun run a11y:approve -- chip --by "Your name" and commit a11y/approvals.json with the rebuilt pages. All test status

Package

Consumers link one stylesheet, css/classic/index.css, which includes every element. The files below are where this element is defined.

Chip package
Source css/classic/components/actions.css
Specimens also use Avatar · Box · Card · Icon · Table · Text · Toolbar
Sprites sprites/icons.svg
React Not yet available: the React binding has not started.

Latest updates

No recorded changes yet.

All release notes