components / chip

Chip

Compact filter-like token with selectable state and optional dismiss action.

Overview

What it is

This section explains the intent of the component before the implementation details.

  • Chip handles small selectable or dismissible tokens that behave like compact choices rather than passive labels.
  • It fills the gap between static Badge and full Button.

Aliases

tag chip, filter chip

Decision guide

How to choose it

Use these notes to decide quickly whether this is the right DK component for the job.

Decision guide

  • Choose Chip when the interaction should feel deliberate, documented, and reusable across product surfaces.
  • If the scenario is more specialized than the current Chip contract, prefer a simpler component or build a dedicated workflow on top of the lower-level DK primitives.

Do

  • Keep the Chip label, value, or status language direct enough to scan quickly.
  • Use the documented size and state recipes instead of inventing one-off variants in product code.

Do not

  • Do not hide the main purpose of Chip behind decorative copy or overloaded surface treatments.
  • Do not stretch Chip into a workflow it was not designed to handle just because the visuals are close.

Usage

When to use

Prefer these situations when choosing this component.

  • Use Chip for compact filters, quick toggles, or selected metadata that the user can remove.
  • Use a dismiss affordance when the chip represents a removable selection.

Usage

When not to use

These patterns are better served by a different component or a simpler surface.

  • Do not use Chip for plain status labels; use Badge instead.
  • Do not use Chip when the action needs full button emphasis or larger touch affordance.

Anti-patterns

  • Using Chip as a generic layout container instead of a purpose-built interaction or content surface.
  • Forking the documented recipe in product code instead of extending the shared DK contract.

Migration notes

  • Migrate legacy chip usage by mapping existing variants and states onto the documented DK props before porting any custom styling.
  • Treat the docs examples as the reference contract for accessibility and event behavior during adoption.

Anatomy

Structural parts

The anatomy explains which pieces matter to the recipe and accessibility model.

compact interactive token

root

Carries the selected or neutral surface treatment.

visible token label

label

Communicates the chosen filter or entity.

optional remove action

dismiss

Optional trailing remove affordance.

API

Public interface

The docs contract distinguishes props, DOM events, and slots so integration behavior is explicit.

Props

NameTypeDefaultDescription
tone'neutral' | 'brand' | 'success' | 'warning''neutral'Chooses the chip tone.
size'sm' | 'md''md'Chooses the chip size recipe.
labelstring—Visible chip label.
selectedbooleanfalseControlled selected state.
dismissiblebooleanfalseShows the remove affordance.
onChange(detail: { value: string | undefined }) => void—Callback fired when the selected state changes.
onDismiss(detail: { id?: string }) => void—Callback fired when the dismiss affordance is activated.
themeThemeContract—Overrides the compiled DK theme used to resolve tokens and recipes for this component.

Events

NamePayloadDescription
change{ value: string | undefined }Fires when the component commits a new value.

Slots

NameDescription
defaultChip is mostly prop-driven in v1 and uses the label prop as its main visible content.

Recipes

Variants, sizes, and states

These notes summarize the intended recipe surface rather than exposing raw implementation detail first.

Variants

  • neutral: Default compact token.
  • brand: Branded emphasis for important filters or groups.
  • success: Positive or accepted state token.
  • warning: Cautionary or attention-seeking token.

Sizes

  • sm: Tight compact token
  • md: Default chip size

States

  • rest: Neutral chip state
  • selected: Active or chosen state
  • dismissible: Shows a remove affordance

Accessibility

Accessibility contract

This is the behavior the component promises to assistive tech and keyboard users today.

Semantics

  • Chip should expose button-like or removable semantics when it is interactive.

Keyboard

  • Selected and dismiss interactions must stay keyboard reachable.

Screen readers

  • Visible label and optional remove action need clear naming.

Checklist

  • Verify the visible label or title still produces a clear accessible name.
  • Verify focus remains obvious in every supported state and size.
  • Verify disabled, selected, and error states do not rely on color alone.

Implementation

Tokens and slot vars

This section shows the representative compiled slot variables that the runtime consumes for the selected design system.

root

--dk-chip-gap
clamp(0.563rem, 0.5156rem + 0.208vw, 0.703rem)

button

--dk-chip-bg
#d7e9ff
--dk-chip-fg
#000f4d
--dk-chip-border
#2072e4
--dk-chip-radius
999px
--dk-chip-gap
clamp(0.563rem, 0.5156rem + 0.208vw, 0.703rem)
--dk-chip-block-size
40px
--dk-chip-inline-padding
clamp(1.333rem, 1.2222rem + 0.494vw, 1.667rem)
--dk-chip-font-size
clamp(1.333rem, 1.2222rem + 0.494vw, 1.667rem)
--dk-chip-font-weight
650
--dk-chip-dismiss-size
24px

leading

--dk-chip-leading-size
0.85rem

label

--dk-chip-label-size
clamp(1.333rem, 1.2222rem + 0.494vw, 1.667rem)
--dk-chip-label-weight
650

dismiss

--dk-chip-dismiss-size
24px

Implementation notes

  • Chip is compact by design; if the affordance needs more emphasis or explanation, escalate to Button or Alert.

Implementation checklist

  • Use the public component API first and only drop to lower-level primitives when the component contract genuinely does not fit.
  • Keep theme overrides token-driven so proofs and recipes stay meaningful.
  • Verify the shipped examples and proof fixtures still represent the real product scenario you are implementing.

Examples

Copy-paste examples

Each example is intentionally practical, grouped by starter, common pattern, and edge-case coverage.

Examples
3
Depth
baseline

Starter

1 example

starter

Starter: selected token

A compact selected choice.

Copy snippet

<Chip tone="brand" label="Priority" selected={true} />

Common patterns

1 example

common

Common: removable token

Dismissible chips work well for selected filters or entities.

Copy snippet

<Chip tone="neutral" label="Assigned to me" dismissible={true} onDismiss={(detail) => console.log(detail)} />

Edge cases

1 example

edge

Edge: cautionary token

Warning tone can flag a risky or incomplete state in a compact way.

Copy snippet

<Chip tone="warning" label="Needs review" />

Verification

Curated proof fixtures

Proofs stay visible in the docs so the system shows what it can guarantee, not just what it can render.

neutral

pass

size=md|tone=neutral

  • Contrast: 90.8 Lc
  • Target: 40px
  • Layout: 53 / 120, 200

brand-selected

pass

size=md|tone=brand

  • Contrast: 89.9 Lc
  • Target: 40px
  • Layout: 53 / 120, 200

danger

pass

size=sm|tone=danger

  • Contrast: 80.5 Lc
  • Target: 36px
  • Layout: 53 / 120, 200