---
title: Chip
description: Chips represent compact entities such as tags and filters in a pill-shaped container.
category: Data display
---

import { meta as ChipMeta, Default, Primary } from '@/content/stories/chip';
import Canvas from '@/components/component-docs/canvas';
import Demo from '@/components/component-docs/demo';

export const config = {
	dependencies: {
		components: [Canvas, Demo],
		scripts: [
			'../../components/component-docs/demo.script.tsx',
			'../../components/component-docs/canvas.script.tsx',
			'../../components/component-docs/controls.script.tsx',
		],
	},
};


# Chip

<p class="docs-lede">Chips represent compact entities such as tags and filters in a pill-shaped container that reads at a glance. For status and counts, use <code>RuiBadge</code>.</p>

## Try it

<Demo of={Default} meta={ChipMeta} />

## Usage

Choose a `variant` to match emphasis. Chips are presentational; pair them with `RuiChipList` when displaying a collection.

```tsx
import { RuiChip } from '@ecopages/radiant-ui/chip';

<RuiChip variant="primary">Design system</RuiChip>
```

## Variant emphasis

`default` suits neutral metadata. `muted` recedes in dense lists. `primary` highlights an active filter or category.

<Canvas of={Primary} meta={ChipMeta} />

## Theming

Chip variants map to **semantic surface roles**, never Tailwind palette steps:

| `variant` | Semantic roles |
| --- | --- |
| `default` | `border`, `surface-container-low`, `on-surface` |
| `muted` | `surface-container`, `on-surface` |
| `primary` | `primary-container`, `on-primary-container` |

Rounded shape uses the `rounded-pill` radius token. Override roles at the theme layer (`tokens/presets/colors/*.css`), not in component CSS.

## Accessibility

- Keep chip text short and self-explanatory; avoid abbreviations that need a legend.
- When chips are interactive, use a button or link with an accessible name instead of a static chip.
- Do not rely on chip color alone to convey meaning; include descriptive text.
- For status labels (`Beta`, `Error`, counts), use `RuiBadge` instead.

## API

`RuiChip` is a presentational JSX view over a `<span>`, no custom element.

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `default` · `muted` · `primary` | `default` | Emphasis tone. |

### CSS classes

Public BEM classes on the rendered element (documented via `@cssclass` on `RuiChip`):

| Class | Description |
| --- | --- |
| `.rui-chip` | Chip root. |
| `.rui-chip--default` | Bordered chip on `surface-container-low`. |
| `.rui-chip--muted` | Chip on `surface-container` without a border. |
| `.rui-chip--primary` | Emphasized chip on `primary-container`. |

### Theme roles (per `variant`)

| Variant | CSS variables consumed |
| --- | --- |
| `default` | `--border`, `--surface-container-low`, `--on-surface` |
| `muted` | `--surface-container`, `--on-surface` |
| `primary` | `--primary-container`, `--on-primary-container` |