Skip to main content

Chip

Interactive inline element - selectable, dismissible, or linkable. A chip is a compact, labeled token that represents a filter choice, an applied selection, or a navigation shortcut. Each variant uses the most appropriate semantic element (checkbox, span + button, anchor) so chips work without JavaScript: checkboxes toggle, links navigate, and close buttons submit a form.

Usage​

When to use

  • To represent an applied filter a user can remove
  • To present a compact, selectable option in a filter UI
  • To surface a small navigational shortcut inline with content

When not to use

  • For display-only labels - use badge
  • For full-width calls to action - use button
  • For a fixed set of exclusive options with clear labels - use a radio group or segmented button group

Do

  • Use the correct semantic variant (selectable / dismissible / linkable) for the chip's purpose
  • Keep chip labels short (one or two words ideal)
  • Provide an explicit accessible name on the dismiss control for dismissible chips (e.g. "Dismiss CSS")

Don't

  • Don't mix different chip variants in a single group without clear affordances
  • Don't rely on color alone to show the selected state
  • Don't use a chip for destructive global actions

API​

Slots​

SlotRequiredDescription
contentYesVisible chip text.
icon-Optional leading icon markup (typically inline SVG).

Props​

PropTypeDefaultDescription
typeEnum: selectable, dismissible, linkableselectableSemantic variant.
urlstring-Target URL for linkable chips.
namestring-Name attribute for the selectable chip input.
valuestring-Value attribute for the selectable chip input.
is_checkedboolean-Checked state for the selectable chip.
is_disabledboolean-Disabled state for the selectable chip input.
is_multipleboolean-When true, the selectable chip uses a checkbox input (multi-select). When false, a radio input.
dismiss_labelstring-Accessible label for the dismiss button. Defaults to "Dismiss {content}".
classesarray-Additional CSS class words merged into the root element.
attributesobject-Additional HTML attributes spread on the root element.

Classes​

ClassCapabilityDefaultDescription
.subtleEmphasis-Lower emphasis; a muted, quieter weight.
.neutralEmphasisYesDefault emphasis; the standard weight at balanced contrast.
.accentEmphasis-Higher emphasis; a stronger, louder weight.
.infoIntent-Informational message.
.warningIntent-Warning or caution.
.dangerIntent-Error, destructive, or critical.
.successIntent-Confirmation or completion.
.solidFill-Filled surface; background and border rendered.
.outlineFill-Bordered surface; transparent background.
.ghostFill-No surface; text or icon only.
.smSize-Small.
.mdSizeYesMedium.
.lgSize-Large.
.roundedShape-Rounded corners.
.squareShape-Sharp corners.
.pillShape-Fully rounded ends.
.animatedMotionYesHonors the animations option.
.stillMotion-Forces motion off regardless of the option.

Attributes​

AttributeSet byRequiredDescription
data-chipConsumer-Marks a dismissible chip root; the dismiss behavior binds to marked chips that directly contain a dismiss button.
data-closeConsumer-On a descendant button inside the chip, marks it as the dismiss trigger consumed by the close utility.

Events​

EventDirectionDescription
chip-dismissEmitsFired on the chip element when its dismiss button is activated. detail.trigger is null when the close-dismiss it answers carried no detail of its own. Cancelable - calling preventDefault() blocks removal so a host application can run async work first.
close-dismissListensListened on the chip root. The close utility on a descendant dismiss button dispatches it; chip cancels the default close behavior to run its own dismiss event.

Examples​

Selectable​

Toggleable chip backed by <input type="checkbox">.

Linkable​

Chip rendered as <a> for navigation.

With icon​

Chip with a leading icon.

Dismissible​

A row of chips each carrying a close button, whose accessible name names the chip it removes.

Single filter group​

Selectable chips backed by radio inputs, so choosing one clears the previous choice.

Multiple filter group​

Selectable chips backed by checkbox inputs, so any number can be active at once.

Accessibility​

  • WCAG 2.2 AA
  • Selectable chips expose native toggle semantics
  • Dismissible chip dismiss buttons carry an accessible name including the chip text (e.g. "Dismiss CSS")
  • Linkable chips are proper links and work without JS
  • Selected state is communicated via the native checked attribute for checkbox/radio chips. Custom non-native controls that need to expose pressed/checked semantics use aria-pressed or aria-checked instead
  • Visible focus ring on every interactive variant
  • Keyboard reachable and activatable by Enter/Space
  • badge - display-only, non-interactive label
  • button - standalone action button
  • group - visually joined button grouping