# Filter chip (goodtabs UI)

Toggle pills with a label and a count, in a row that scrolls instead of wrapping.

## Install

```bash
npx shadcn@latest add https://ui.goodtabs.co/r/filter-chip.json
```

Or, with the @goodtabs namespace configured in components.json: `npx shadcn@latest add @goodtabs/filter-chip`

## Usage

```tsx
import { FilterChip, FilterChipGroup } from "@/components/ui/filter-chip"

<FilterChipGroup aria-label="Category" value={category} onValueChange={setCategory}>
  <FilterChip value="all" count={212}>All</FilterChip>
  <FilterChip value="components" count={48}>Components</FilterChip>
</FilterChipGroup>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value | `string` |  | On FilterChip: identifies it inside a FilterChipGroup. |
| count | `number | string` |  | On FilterChip: mono count after the label, 70% opacity when selected. |
| selected, defaultSelected, onSelectedChange | `boolean, boolean, (selected: boolean) => void` |  | On a FilterChip used alone: controlled or uncontrolled state. |
| type | `"single" | "multiple"` | `"single"` | On FilterChipGroup: one chip at a time, or any number. |
| value, defaultValue, onValueChange | `string or string[] by type` |  | On FilterChipGroup: controlled or uncontrolled selection. |

## When to use

- Above a grid or list to narrow it by category, pricing or tag
- When the counts help people choose and the set fits in one row
- For one or many selections that apply at once, with no submit step

## When not to use

- For switching views of the same thing, use segmented-tabs
- For more than about ten options, use a select or a combobox
- For navigation between pages, use links

## Notes for agents

- Give FilterChipGroup an aria-label; it renders role group and the chips carry aria-pressed
- Single select keeps one chip selected: clicking the selected chip does nothing, so include an All chip for the empty filter
- The row scrolls sideways with no wrap; put it in a container with a width or it grows with its parent
- A demo or parent that passes onValueChange must be a client component

Docs: https://ui.goodtabs.co/components/filter-chip