Chip

Use Chip for concise, glanceable controls that represent status, selections, categories, or removable tokens. The primitive is composition-first: use companion slots like ChipCheck, ChipAvatar, and ChipDelete instead of implicit icon/delete props.

Installation

The component is exported from @by/experience-system. Add the package with your package manager:

pnpm add @by/experience-system

In this monorepo, depend on the workspace package (for example via workspace:* or your catalog) so imports resolve to packages/experience-system.

Composition

Use the base Chip and optional companion subcomponents:

Chip
├── ChipCheck (optional)
├── ChipAvatar (optional)
└── ChipDelete (optional)

Chip automatically wraps plain text children in an internal label slot, so most usage stays concise while still supporting explicit composition.

Usage

import { Chip, ChipAvatar, ChipCheck, ChipDelete } from '@by/experience-system';

Chip and companions are client components. Use them inside a Client Component or dynamic import when using the Next.js App Router.

<Chip checked color="accent" variant="fill">
  <ChipCheck />
  Warehouse
</Chip>

<Chip variant="soft">
  Returns
  <ChipDelete ariaLabel="Remove Returns" onDelete={() => removeFilter('returns')} />
</Chip>

Examples

Action chips

Use action chips to display contextual actions that help the user complete a specific task. An alternative to action chips is a Button, which represents persistent actions.

Chip with popover

Chips can be accompanied by a popover when additional contextual explanation is required. It also could be combined with a Hover Card component.

Registry examples

These @by-es items are registry-only composites. Live previews use the same sources as the Experience System registry.
View code shows post-shadcn add imports (often @/components/ui/...).
See Registry for components.json and REGISTRY_TOKEN.

Choice chips (single select)

Use the choice-chips registry composite for one selected value at a time.

import

After shadcn add, import ChoiceChips from your registry path (for example @/components/ui/choice-chips).

pnpm dlx shadcn@latest add @by-es/choice-chips

Filter chips (multi select)

Use the filter-chips registry composite for independent multi-select toggles.

import

After shadcn add, import FilterChips from your registry path (for example @/components/ui/filter-chips).

pnpm dlx shadcn@latest add @by-es/filter-chips

Chip list (input chips)

Use chip-list for removable token lists with overflow behavior.

import

After shadcn add, import ChipList from your registry path (for example @/components/ui/chip-list).

pnpm dlx shadcn@latest add @by-es/chip-list

Chip select

Use chip-select to build filters with non-binary options that are available via a drop-down menu.

import

After shadcn add, import ChipSelect from your registry path (for example @/components/ui/chip-select).

pnpm dlx shadcn@latest add @by-es/chip-select

API Reference

Chip

Chip renders a <span> by default and forwards standard span attributes. For interactive chips, use asChild to render a semantic <button>/<a> or provide role, tabIndex, and aria-disabled.

ChipCheck

Optional check slot for selected chips. When no custom children are provided, it renders the default check icon.

ChipAvatar

Optional leading avatar slot. It inherits the chip size context for consistent spacing.

ChipDelete

Optional trailing delete affordance. Use onDelete to handle remove behavior from mouse and keyboard activation.

Accessibility

Chip renders a non-interactive <span> by default; for clickable chips, use asChild to render a semantic <button>/<a> (recommended) or add role, tabIndex, and the appropriate aria-* state yourself. For selectable groups, provide clear pressed/checked state semantics and labels. ChipDelete supports keyboard activation (Enter/Space) and should expose a meaningful aria-label when icon-only context is ambiguous.

Source in the repo: packages/experience-system/src/components/Chip/Chip.tsx. Agent-oriented contracts: packages/experience-system/src/components/Chip/Chip.instructions.md.