Chip

A small toggleable tag, backed by daisyUI's badge and its style modifiers. It always renders a real <button> (or, when removable, a <span> wrapping one), and it communicates SELECTION, never state or naming.

The canon behind it. method/design-language/03-status-language.md §A1 (03-status-language.md:13, three small-tag species, never interchangeable) and method/design-language/07-toolbars-and-filters.md §A4 (07-toolbars-and-filters.md:24, a trigger that can only summarize as a count owes the reader removable chips).

Click feedback. Every chip type and variant presses on pointer-down (active:scale-[0.96]) and pops for 280ms when it toggles (animate-chipPop, keyed to the click, cleared on animation end); FieldChip's clickable shape shares the press. Owner ruling doc 59 V3: the feedback is a kit default, never something a page adds. Both are stilled under prefers-reduced-motion.

When to reach for it#

Anything the user can select, deselect, or remove: a filter value shown as a removable pill beside its control, a plan or role tag in a card toolbar, a click-to-navigate pill. Canon doc 3 §A1 draws the line precisely: "three small-tag species, never interchangeable. StatusPill/StatusDot communicate STATE. Chip communicates SELECTION... FieldChip communicates NAMING."

Do not reach for it to show a record's status (queued, running, failed). That is StatusPill or StatusDot. Do not reach for it to name a schema field or a file. That is FieldChip. Using Chip for either is called out in the canon as a defect, not a style preference. Do not reach for it to build a two-option segmented toggle either: the shipped precedent for that shape (walmart-mvp/frontend/src/features/catalog/ItemsView.tsx:62-90, ToggleChip, the "By part type / All items" switch) is a hand-rolled joined button pair, not Chip with selected. As of this pass Chip's own selected prop has no confirmed shipped call site in either app; when a two-way toggle is the actual need, the codebase's own answer has been a bespoke button pair, not this component.

Contract#

Identity:

• children: the label.
• presets: ChipPreset | ChipPreset[] (added 2026-08-14). Named partial-prop bundles resolved before prop defaults; explicit props always win, mirroring Button's PresetProps/mergePresets mechanism. One preset today: "applied", the ruled applied-filter shape (size="lg" plus text-sm, chip.tsx PresetProps), which FacetBar's applied chips now ride. A preset's className merges BEFORE the caller's, so caller classes win conflicts. Presets are shorthands, never gates (AGENTS.md ground rule 8): everything a preset applies stays reachable through plain props.
• color: ChipColor, a locally-declared 8-way union (primary | secondary | accent | neutral | info | success | warning | error). This is field-for-field identical to the shared SemanticColor union that now lives at packages/ui/src/internal/variants.ts, but Chip still declares its own copy rather than importing the shared one. The type comment (chip.types.ts:6-9) still frames this as pending a merge into a not-yet-existing shared module; that module exists now, the merge itself just has not happened. Treat ChipColor and SemanticColor as interchangeable in practice, they are not interchangeable in the type system yet.
• variant: solid | outline | ghost | soft. solid is the unmodified default look (no extra class); the other three map to daisyUI's badge-outline/badge-ghost/badge-soft. The default is solid, except that a selectable chip at rest (onChange or selected set, selected false, no onRemove) defaults to soft, so an unselected option reads as quiet in both themes instead of near-black on the light one (owner ruling 2026-09-03). Pass variant explicitly to override either default.
• size: xs | sm | md | lg.

Selection:

• selected / selectedColor: selectedColor overrides color entirely while selected is true.
• onChange(isSelected, event): value-first, the state the click would produce, then the native event.
• clickable: derives to true automatically whenever onChange or selected is set; you rarely need to pass it explicitly.

Icon:

• Icon: IconImportProps's Icon, or literal true for the built-in check-when-selected / plus-when-not affordance (resolvedIcon, chip.tsx:69). No shipped call site sets Icon={true} as of this pass; every real icon usage passes a concrete icon key instead.
• iconSize / iconClassName are consumed. iconProps (the third member of IconImportProps) is declared on the type but never destructured in the component (chip.tsx:42-61), so anything passed through iconProps is silently dropped. This is the same pre-existing RenderIcon passthrough gap StatusPill has.

Removable mode:

• onRemove(event): when set, the chip's DOM shape changes to a <span> shell with a nested close <button>, because the chip body itself is no longer the clickable target and a <button> cannot nest another <button>. onRemove and onChange/selected are mutually exclusive in effect, not just in intent: when onRemove is set, the component returns the removable-span branch unconditionally (chip.tsx:85-102) and the plain clickable-button branch, the only one that reads onChange, selected, or clickable, never executes. Passing both is not a type error, but onChange will silently never fire.
• removeLabel: what a screen reader calls the close control, defaults to Remove <label> when children is a plain string, or Remove filter otherwise.

Other:

• skeleton, loading (drives the icon's own loading state), noBorder (drops the border, no confirmed shipped call site), tooltip / tooltipProps (wraps unconditionally, no-ops when empty, same contract as Tooltip itself and as Button's tooltip).

Truncation#

The label lives in its own span inside the chip. When the chip's box is narrower than its text, the label ends in an ellipsis inside the chip (the chip never overflows or hard-clips), and a tooltip with the full text appears on hover. A chip whose label fits shows no tooltip. A caller's own tooltip always wins over the automatic one. Only a string or number label can feed the automatic tooltip; for a node label pass tooltip.

Laws it enforces#

• Fit, then truncate, never clip: truncation happens inside the chip with the full value on hover.
• Show only what has something to say: the tooltip appears only when text is actually hidden.

Sanctioned combinations#

Banned combinations#

• onChange (or selected) together with onRemove. See the contract note above: onRemove wins unconditionally and onChange/selected are dead code on that render. If a chip needs to be both selectable and removable, that is two chips or a different component, not one Chip with both props.
• Chip standing in for StatusPill/StatusDot or FieldChip. Canon doc 3 §A1 states this as a defect, not a preference: selection, state, and naming are three different signals and the reader needs to tell them apart at a glance.
• Chip with selected as a two-option segmented toggle. The shipped precedent for that exact shape is a hand-rolled button pair (ToggleChip, ItemsView.tsx:62-90), not this component. If you're tempted to reach for selected to build a Yes/No or grouped/flat switch, check whether a join-pair button (canon doc 7 §B, "Admin quick toggle") fits better first.
• Passing iconProps. It is silently dropped; if per-render icon customization beyond iconSize/iconClassName is needed, it is not currently plumbed through.

Before you adopt this#

Five questions to answer before reaching for Chip.

1. Does the shell, a parent layout, or a global provider already render this? Not applicable, Chip is inline content; no shell already renders it.
2. Does this app already ship a local implementation of the same thing? A hand-rolled two-option toggle (ToggleChip) is the shipped precedent, not selected.
3. Does this app's kit pin reach the version this component or prop landed in? presets landed 2026-08-14; confirm the app's kit pin reaches it.
4. Does the component derive its own accessible name and keyboard path, or must the call site supply them? Not applicable, Chip derives its own name from children or removeLabel.
5. Which canon §A rules bind this surface, and which does the composition break? §A1 bars Chip standing in for StatusPill/StatusDot or FieldChip.

Travels with#

• Tooltip, unconditionally, same no-op-when-empty contract as Button.
• FacetBar (table.md, "FacetBar: the standing-facets toolbar"), which is the kit's answer to a filter row and already renders applied values as removable chips. Reach for it before assembling one: a standing menu per filter, its counts, and the chips are all inside it. Chip on its own is for a selection the caller places itself.
• Dropdown or Select, when the surface genuinely is not a table toolbar and FacetBar does not fit: Chip renders the selected values and the picker owns choosing them.
• RenderIcon, internally, for both the leading icon and the close-control's Close icon in removable mode.

Snippet#

import { Chip } from "@versable-git/ui";
<Chip key={`${f.key}:${v}`} size="sm" variant="soft" onRemove={() => f.onToggle(v)}>
  {f.options.find((o) => o.value === v)?.label ?? v}
</Chip>

walmart-mvp/frontend/src/components/FacetToolbar.tsx:153-155