Chip

When to use

• A short label that describes or filters content. Categories, attributes, topics, suggestions: words a reader scans in a row.
• Filters and choices. Put chips in a ChipGroup with selection="multiple" for any-of-many and selection="single" for one-of-many. Each chip is a toggle.
• Removable values the person has added. Give a chip onRemove to make an input chip, such as the tags on a post or the recipients of a message.
• Small contextual actions. An action chip with onClick, like "Sort" or "Near me", sits in a row beside the content it affects.
• A static tag. With no handler a chip is plain text in a pill, not a control. Leave it that way when it only labels.
• Labels of one or two words. Keep them in sentence case and short enough not to wrap; maxWidth truncates the rest.

When not to use

• For the main action of a view. An action chip is small and contextual. Use a Button.
• For a tool state in a toolbar. Bold or mute, often icon-only, is a ToggleButton.
• For a count or a status attached to something else. An unread count on a bell or "New" on a card never does anything. Use a Badge or a Status.
• For a setting such as view mode or period. A one-of-many that is not content reads better as a SegmentedControl or ToggleGroup.
• For navigation. A chip is not a tab or a menu. Use Link, or render the chip as one (As a link) when it truly goes somewhere.
• For typed multi-value entry. A field that turns typed text into chips is a Tokenizer.
• For long labels or sentences. If the text needs more than a couple of words, use a Checkbox or a list.

Installation

pnpm add @tessinaui/ui

Usage

import { Chip, ChipGroup } from "@tessinaui/ui";

<Chip>Design</Chip>                                          // tag — a <span>
<Chip selected={on} onSelectedChange={setOn}>Vegan</Chip>    // toggle — aria-pressed
<Chip onClick={openSort}>Sort</Chip>                         // action — a button
<Chip onRemove={() => remove(tag)}>Trading cards</Chip>      // input — with a remove button

<ChipGroup aria-label="Cuisine" selection="multiple" value={cuisines} onValueChange={setCuisines}>
  <Chip value="thai">Thai</Chip>
  <Chip value="indian">Indian</Chip>
</ChipGroup>

Examples

Default

With no handler a chip is a static tag: a <span> with no control semantics, no Tab stop and no hover state.

Kinds

What a chip is follows from what it is given — nothing, selected / defaultSelected, onClick or onRemove. There is no kind prop; the derived kind is exposed as data-kind and in the Kind by handler below.

Filter chips

Any number can be on. selection="multiple" lets the group own the selection; each chip opts in with value and becomes a toggle with aria-pressed.

Choice chips

One or none. selection="single" behaves like radio buttons that can also be cleared — pressing the selected chip deselects it.

Input chips

onRemove adds a real remove button, named "Remove" and described by the chip's label. Backspace or Delete removes the chip from either part; focus then moves to the next interactive chip, else the previous one, else to onRemoveFocusTarget — the field here.

Variants

Four fills at rest — outline, soft, solid and ghost. The neutral outline border is deliberately light, firming up on hover. A selected chip takes the solid primary fill whichever variant it started from, so the variants only differ while off.

Intents

At rest an intent tints the quiet variants with the family's light fill and ink (solid takes the full fill straight away). Selected, every intent becomes its solid fill with its own locked ink; none selects into primary.

Sizes

24 · 28 · 32 · 40 · 44 px — the chip's own scale, below the button family's. Interactive chips under 44 px grow an invisible tap extension on touch devices; a tag is not a control and is exempt.

Rounded

The family map: none 0 · sm 4 · md 6 · lg 8 · xl 12 px · full pill. A leading avatar follows the chip's corners.

With icon

leadingIcon and trailingIcon are decorative — wrapped in an aria-hidden span and sized from the chip's scale. While a toggle is selected the check mark takes the leading slot; showCheck={false} keeps the icon there instead.

With avatar

leadingAvatar draws a decorative avatar; the chip's label names the person. name drives the initials when there is no image, and presence / statusIntent put a dot on it. An avatar outranks the check mark, so a selected person chip keeps its face.

With status

leadingStatus takes { presence } (online / away / busy / offline, shape-coded) or { intent }. The dot is decorative; if the state matters, say it in the label.

With count

count renders "(n)" after the label in tabular figures and is part of the accessible name — "Shoes (12)".

Truncation

maxWidth caps the label, not the chip: the text truncates with an ellipsis and the full string goes into title. Slots keep their size.

Full width and alignment

fullWidth stretches the chip to its container; align decides where the content sits once the chip is wider than it. In an input chip the control takes the slack and the remove button stays pinned at the end.

As a link

render puts the chip on another element. An anchor host keeps link semantics — announced as a link, activated by Enter, listed among the page's links.

Scrolling row

overflow="scroll" keeps one row that scrolls sideways with the scrollbar hidden and both edges faded, so a cut-off chip reads as "more this way". Arrow keys still walk the whole row.

On a coloured surface

Wrap a region in <Surface> and every chip inside inherits tone="on-color", deriving its colours from the ink the surface paints. No per-chip prop.

Disabled

disabled dims every kind to 50 %, and the element that dims carries the state. Buttons take the native attribute — an input chip disables its remove button, and its label too when that label is a button; a tag and an input chip's shell take aria-disabled, so a remove-only label reads as inactive to assistive tech as well as to the eye, with the shell dropping pointer events for the whole chip. A disabled <ChipGroup> disables every chip inside it.

Skeleton

ChipSkeleton reads its height, width and radius from the chip's own scale. showLeading reserves the circle an avatar or status dot will occupy. Each one is a live region announcing "Loading".

RTL

Under dir="rtl" the leading slot sits on the right, the remove button moves to the left end, and ArrowLeft walks the group forward.

API Reference

Chip

Extends the HTML attributes of the element it renders. In an input chip the extra attributes (id, aria-*, data-*) go to the label element — a <button> when the chip is activatable, otherwise a <span> — while className, style and dir go to the shell around it and the remove button.

Leading slot priority, when more than one is given: avatar → check → status → icon.

ChipAvatarDef

ChipStatusDef

ChipGroup

A labelled role="group" with one Tab stop. Either aria-label or aria-labelledby is required; TypeScript enforces it.

ChipSkeleton

Kind by handler

onRemove wins over everything else: an input chip that also has selected keeps aria-pressed on its control. A toggle with onClick fires both.

Data attributes

Exports

CHIP_SIZE and CHIP_ROUNDED are the scale maps the chip and its skeleton read. chipFill({ variant, intent, selected, tone, interactive }) returns the colour classes for one chip, every token named — for a chip-shaped thing that is not a chip. useChipGroup() returns the nearest group's context (selection, isSelected, toggle, disabled), or null outside one.

Accessibility

The accessible name is the label, always. Icons, avatars and status dots inside a chip are decorative and hidden from assistive technology; if something matters, it is in the text.

Patterns

• A toggle chip follows the WAI-ARIA Button pattern, toggle variant: a <button> with aria-pressed that is true while selected. The check mark is decoration.
• An input chip is a label and a remove control in one shell. The remove control is a real <button> named by removeLabel ("Remove") and described by the chip's label through aria-describedby, so a row of them never reads as five identical "Remove" buttons. The label is a control only if you also give the chip something to do — pass onClick (or render, or make it a toggle) and it becomes a button; with onRemove alone it is a <span>, because a button whose activation does nothing is a button in name only. Both parts are arrow-key stops either way, and Backspace or Delete removes the chip from both.
• A group is role="group" with a required name and a roving tabindex — the APG practice for a composite: the row is one Tab stop and arrow keys move inside it. Static tags carry no marker and are not stops.
• A tag is not a control. A <button> that does nothing is announced as a button, takes a Tab stop, and leaves the user pressing it and wondering. Text that only labels stays text — which also exempts it from the 44 px floor.

Keyboard

What is announced

VoiceOver + Safari, 2026-09-14. Arriving works: "Dietary group", "Vegan selected toggle button", "Vegetarian toggle button". On an input chip it reads "Remove Trading cards button", and removing that chip moves focus to the next one ("Vintage group"). Pressing a toggle chip is silent. The chip does toggle, and re-reading it says "Vegetarian selected toggle button". A plain HTML <button aria-pressed> is silent in the same way, so this is how VoiceOver + Safari treats every toggle button, not a chip defect. The rest of this list is expected from the markup, not a recorded run.

• Tag: "Design" — read as text, not as a control.
• Toggle: "Vegan selected toggle button" / "Vegetarian toggle button" (recorded). With a count: "Shoes (12), toggle button".
• Action: "Sort, button". As a link: "Avatar, link".
• Input chip: "Trading cards" — text, not a button, unless the chip is also clickable — then on the remove button "Remove, button, Trading cards". A custom removeLabel="Remove filter" reads "Remove filter, button, Trading cards".
• Interactive person chip: "Jane Doe, button" — the avatar is aria-hidden; its name only drives the initials. As a tag it is simply "Jane Doe".
• Group: "Dietary, group" on entry.
• Skeleton: a role="status" live region announcing "Loading".

Touch and pointer

• Below 44 px, every interactive chip carries an invisible vertical tap extension on touch devices (touch:) that brings the hit box to 44 px while the visual stays compact — the way IconButton does it. The remove button gets its own 44 px target, grown inward over the label so it never hangs past the chip's edge. Tags get none.
• The focus ring is 2 px with a page-coloured offset. Inside an input chip both buttons draw inset rings, so the shell can never clip them. Those rings take the chip's own ink, which holds on every fill: a solid or selected chip, and a chip on a coloured <Surface>.
• A neutral outline chip draws its border from --outline-border at 60 % in light and 75 % in dark, returning to full strength on hover. That resting value is below the 3:1 WCAG 1.4.11 asks of a control's boundary, and it is a deliberate design decision: a chip is low-emphasis and carries a visible label — 19.8:1 inside the pill — where a full-strength outline around every filter in a row reads as a grid of boxes. The focus ring (5.2:1) is unchanged, and a selected chip paints a solid fill. If your product needs the boundary itself to clear 3:1, variant="solid" with an intent is the only option that gets there — error (4.77:1 light / 5.20 dark), success (3.22 / 8.93) and info (5.20 / 7.51). Neutral solid reaches 1.48 / 1.91 and light warning only 2.17, and soft does not carry the boundary at all (1.04–1.34:1 across every intent and both themes). For anything else, supply your own border. The button family keeps --outline-border at full strength.
• Intent outlines sit on the intent's light fill, which carries the boundary instead.
• disabled uses the native attribute on buttons, aria-disabled + tabindex="-1" on an anchor host, and aria-disabled on a tag and on an input chip's shell. The 50 % dim takes a label under 4.5:1, which WCAG 1.4.3 allows only for an inactive component, so the state has to be one assistive tech — and axe — can read; data-disabled is not. The group's arrow keys skip disabled items.

Guidelines

Copy rules

• Labels are one or two words in sentence case — "Gluten-free", "Near me" — never a sentence, and never with trailing punctuation.
• Keep the label identical on and off. The state is carried by aria-pressed and the fill; "Vegan" that becomes "Vegan ✓" changes width mid-click.
• Put counts in count, not in the text, so they render in tabular figures and stay separable from the name.
• Do not hand-write aria-label on a chip. The remove button is named "Remove" and described by the chip's label automatically; change the verb with removeLabel only when "Remove" is wrong ("Remove filter").
• A person chip's label is the person's name. The avatar's name is for initials, not for naming the chip.

Non-goals

• A chip does not open anything by itself. An action chip that opens a menu is the trigger of a DropdownMenu — the chip supplies the button, the menu supplies the popup.
• Input chips hold values; the field they come from is yours. Pass its ref as onRemoveFocusTarget so the last removal lands focus back in it.
• There is no elevated variant, by decision. The lift is a fill, not a shadow: variant="soft" is the elevated chip — its plate clears the page at 1.26:1 light / 1.31:1 dark, which in dark beats every shadow in the Tailwind scale, because the dark card colour is the page colour and a shadow on it measures 1.01:1.
• A person chip's own fill does not follow who the person is. Pass leadingAvatar.identity and the avatar takes a stable hue of its own.
• The chip is not a multi-value input. A field that commits typed entries as chips is a Tokenizer, which renders these chips for you.