Chip
A dismissible pill for active filters, selected tokens, or removable lightweight labels.
Component
Use fd-chip when users need to remove an item from a visible set without opening a menu or editing a form field. The chip stays text-first, and the remove affordance is always a real button.
When to use
- Active filters — when users can remove one applied filter at a time.
- Selected tokens — when a compact removable summary helps users review current choices.
- Lightweight removable labels — when removing an item is a safe, single-step action.
When not to use
- Clickable or selectable pills —
fd-chipdoes not support toggle, selection, or navigation behavior in v1. - Critical alerts or workflow status — use a fuller message pattern when the user needs more context or recovery guidance.
- Complex editing — if users need to rename, inspect details, or confirm before removing, use a richer pattern.
Examples
Properties
| Name | Type | Default | Description |
|---|---|---|---|
type | "neutral" | "cool" | "warm" | "positive" | "alert" | neutral | Visual tone for the chip surface. |
removeLabel | string | undefined | undefined | Optional accessible-name override for the internal remove button. |
Slots
| Name | Description |
|---|---|
| (default) | Visible chip label text. |
Events
| Name | Detail | Description |
|---|---|---|
fd-chip-remove | {} | Fired when the internal remove button is activated. |
CSS custom properties
| Name | Default | Description |
|---|---|---|
--fd-chip-height | 28px | Minimum chip height. |
--fd-chip-padding-inline-start | var(--fdic-spacing-sm, 12px) | Leading inline padding before the label. |
--fd-chip-remove-size | 28px | Square size for the internal remove button. |
--fd-chip-remove-gap | var(--fdic-spacing-3xs, 2px) | Space between the label and the remove affordance. |
--fd-chip-radius | 9999px | Pill corner radius. |
--fd-chip-font-size | var(--fdic-font-size-body-small, 1rem) | Label font size. |
--fd-chip-text-color | var(--fdic-color-text-primary, #212123) | Shared text color across tones. |
--fd-chip-bg-neutral | light-dark(var(--fdic-color-neutral-200), var(--fdic-color-neutral-800)) | Neutral chip background. Uses stronger neutral surfaces in light and dark themes so neutral chips remain visually comparable with semantic chip types. |
--fd-chip-bg-cool | var(--fdic-color-info-050, #f1f8fe) | Cool chip background. |
--fd-chip-bg-warm | var(--fdic-color-secondary-050, #f8efda) | Warm chip background. |
--fd-chip-bg-positive | var(--fdic-color-success-050, #e8f5e9) | Positive chip background. |
--fd-chip-bg-alert | var(--fdic-color-error-050, #fdedea) | Alert chip background. |
--fd-chip-remove-overlay-hover | var(--fdic-color-overlay-hover, rgba(0, 0, 0, 0.04)) | Hover overlay for the internal remove button. |
--fd-chip-remove-overlay-active | var(--fdic-color-overlay-pressed, rgba(0, 0, 0, 0.08)) | Pressed overlay for the internal remove button. |
--fd-chip-remove-focus-ring | var(--fdic-color-border-input-focus, #38b6ff) | Focus-ring color for the internal remove button. |
Shadow parts
| Name | Description |
|---|---|
container | Outer pill container. |
label | Visible label wrapper. |
remove-button | Internal native remove button. |
remove-icon | Decorative close icon wrapper inside the button. |
Best practices
Do
Use a chip for one-step removal
Keep the action simple and predictable so the user understands what will disappear when the button is activated.
Don't
Make the whole chip a mystery button
Only the remove affordance is interactive in v1. If the whole pill needs to act, use a different pattern.
Do
Keep the label explicit
Short text like “Pending review” or “Under $250K” makes the remove action understandable without relying on color.
Don't
Use chips as the only explanation for high-stakes state
Regulatory, error, or eligibility conditions need fuller text or message patterns.
Content guidelines
- Keep labels short and plain. Users should understand the label immediately before they decide whether to remove it.
- Treat the remove action literally. The chip button should remove one item, not clear all results or dismiss unrelated content.
- Use status text that stands on its own. Color supports scanning, but the visible label must still carry the meaning.
Accessibility
fd-chipexposes one real tab stop: the internal remove button.- The remove button gets a generated accessible name in the form “Remove {label}” unless you provide
remove-label. - The decorative close icon stays
aria-hidden="true". - The component does not remove itself from the DOM. The host application owns collection state, so focus management after removal remains a product decision.
- Forced-colors support preserves the pill boundary, readable text, and a visible focus treatment on the internal button.
Known limitations
fd-chipis not a selectable chip, filter button, or navigation control in v1.- The component supports text labels only in its documented contract. Rich leading icons, avatars, and counters are out of scope.
- The button-focus treatment is intentionally localized to the remove affordance, not the whole pill.
Choosing between Chip, Badge, and Alert
These three components are frequently confused. Use the right one:
- Chip (this component) = user-removable token. The user can dismiss it from a visible set. Use for active filters and selected items.
- Badge = static metadata label. The user reads it but cannot act on it. Use for tags, categories, and status indicators.
- Alert = system message requiring attention. Use for time-sensitive or high-priority information that changes the user's next step.
If the user only reads it, use a badge. If it communicates something urgent, use an alert. If the user removes it from a set, use a chip.
Related components
- Badge — static text-first pill when no remove action is needed
- Chip Group — wrapping layout for related chips
- Badge Group — wrapping layout for related badges
- Alert — page-level or section-level messaging for time-sensitive information