Chip

Installation#

# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add chip

Usage#

import { Chip, ChipIcon, ChipRemove } from "@/components/ui/chip"

export function Example() {
  return (
    <Chip selected={on} onClick={() => setOn(!on)}>
      1-ADAM-12
    </Chip>
  )
}

A Chip is a <button type="button"> unless you give it another element through asChild. Reach for it when the pill does something: toggles, assigns, filters, links or drags. A pill that only shows a status or a count is a Badge.

Anatomy#

import { Chip, ChipIcon, ChipRemove } from "@/components/ui/chip"

<Chip>
  <ChipIcon />
  Label
</Chip>

<Chip asChild>
  <span>
    Label
    <ChipRemove />
  </span>
</Chip>

Assign to#

Extra-small outline chips in a call banner: one click hands the call to a unit, a second click takes it back. The department colour rides on the edge and the mark; the chosen unit takes the brand edge and wash.

Frequencies#

A leading ChipIcon and a numeric label: chips are tabular-nums, so a row of frequencies lines up digit for digit. Wrap a set in role="group" with a name, so the pressed chip is announced in context.

Filter tags#

A tag whose only action is its × is a <span> (through asChild) holding a ChipRemove: a button cannot sit inside a button. The × has its own name, so say what it removes. A display-only chip does not answer hover or press; only the × does.

Variants and tones#

soft (default) fills the pill: the muted ground for neutral, the tone's own wash otherwise. outline keeps only the edge. Tones are neutral, brand, info, success, warning and destructive; the label takes the tone's legible -strong ink.

Sizes#

xs is 20px tall, sm (default) 24px. Both reach a 40px target (44px on touch) through an invisible extension, so a row of small chips stays easy to hit without growing.

Colour#

color takes any CSS colour: a department's hex from your config, a theme variable. It tints the edge and the ground and adds a leading mark in that colour; the label stays in the foreground ink, since an arbitrary hex as text carries no contrast guarantee. The tint is an opacity layer, not color-mix(), so it holds in old embedded browsers too.

Selected#

selected paints the brand edge and a brand wash over any variant, tone or colour (the colour mark stays). On the default button it also sets aria-pressed, so the chip is announced as a toggle; leave it undefined on a chip that is not one.

Icons#

ChipIcon goes before the label (leading) or after it (trailing) and tucks in toward the edge. Pass idle and hover instead of children to swap one glyph for another while the chip is hovered or focused: a check that becomes an × says “click to remove” before the click. Both glyphs stay mounted and cross-fade.

Remove#

ChipRemove is its own <button>, last in the chip, hugging the trailing edge at either size. Its target is 40px tall but never wider than itself, so it never takes a tap meant for the next chip. Name it with label.

As a link or a drag handle#

asChild hands the chip's paint to your element: a link to a unit's record, or the element a sortable (dnd-kit's useSortable) puts its listeners on. Hover and press answer on a link and on anything with role="button"; pass static to a drag handle so the press scale does not fight the drag. Try the arrow keys on a focused chip below.

Disabled#

disabled dims the chip in any state and takes it out of the pointer's way: the native disabled on the default button, aria-disabled with asChild.

API reference#

FAQ#