# FilterChip

> Slug: `filter-chip` · Category: Selection

## When to use

- A trigger that opens a menu/popover for filtering or sorting a list, table, or grid.
- When the chip itself displays the currently selected value (e.g., "Sort by: Price").

## When NOT to use

- Multi-select pills inline (no menu) — use `Chips variant="toggle"`.
- Single-select pills inline — use `Chips variant="radio"`.
- Removable applied filters — use `Chips variant="button"`.
- A general-purpose dropdown — use `MenuDropdown`.

## Variants & decision tree

| Need | `chipType` |
|---|---|
| "Filter by: …" prefix | `'filter'` |
| "Sort by: …" prefix | `'sort'` |

The chip displays the prefix and appends the `selectedItem.text` when set. A trailing caret indicates a menu trigger; the caret rotates when `showMenu` is true.

## States

Closed (default), open (`showMenu`), with selection (`selectedItem`), hover, focus, pressed, inverse.

## Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `id` | `string` | — | Required. Used to derive `aria-controls`. |
| `chipType` | `'filter' \| 'sort'` | — | Required. Drives the prefix text. |
| `selectedItem` | `{ id, text }` | — | Currently selected item to display. |
| `showMenu` | `boolean` | `false` | Sets `aria-expanded` on the trigger. |
| `hasPopUp` | `boolean` | `true` | Sets `aria-haspopup`. |
| `leadingIcon` | `ReactNode` | — | Optional icon before the label. |
| `caretIcon` | `ReactNode` | built-in | Override the caret SVG. |
| `inverse` | `boolean` | `false` | Dark-background styling. |
| `onClick` | `MouseEventHandler` | — | Open/close the associated menu. |

## Usage examples

```tsx
const [open, setOpen] = useState(false);
const [sort, setSort] = useState<{ id: string; text: string }>();

<FilterChip
  id="sort-chip"
  chipType="sort"
  selectedItem={sort}
  showMenu={open}
  onClick={() => setOpen((o) => !o)}
/>

// With leading icon
<FilterChip
  id="filter-chip"
  chipType="filter"
  leadingIcon={<SearchIcon />}
  selectedItem={{ id: 'phones', text: 'Smartphones' }}
/>
```

## Composition

Pair with a `MenuDropdown` whose `id` matches the FilterChip's derived `aria-controls` target. Above lists/tables, group multiple FilterChips in a flex row with `Chips variant="button"` showing applied filter summary below.

## Accessibility

`aria-haspopup` and `aria-expanded` are wired automatically. The chip is a real `<button>` so it gets keyboard activation for free. Pair with a Menu/MenuDropdown that the user can dismiss with Escape and that returns focus on close.

## Do / Don't

- DO use `chipType="filter"` for filtering and `'sort'` for sorting — the prefix text matters for screen readers.
- DO keep the menu container and FilterChip's `aria-controls` id in sync.
- DON'T use FilterChip for inline selection — use `Chips` instead.
- DON'T omit `onClick`; the chip must open the associated menu.
