# Filter menu (goodtabs UI)

A pill that opens checkbox items with counts and shows how many are checked.

## Install

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

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

## Usage

```tsx
import { FilterMenu } from "@/components/ui/filter-menu"

const [pricing, setPricing] = useState<string[]>([])

<FilterMenu
  label="Pricing"
  options={[{ value: "free", label: "Free", count: 128 }, { value: "paid", label: "Paid", count: 31 }]}
  value={pricing}
  onValueChange={setPricing}
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| options | `{ value: string; label: string; count?: number }[]` |  | The options, in menu order. A count shows in mono on the right. |
| value | `string[]` |  | The checked option values. The component is controlled. |
| onValueChange | `(value: string[]) => void` |  | Called with the new list of checked values, or an empty list on Clear. |
| label | `string` | `"Filter"` | Trigger text. |
| clearLabel | `string` | `"Clear"` | Text of the item at the bottom that unchecks everything. |
| align | `"start" | "end"` | `"start"` | Which side of the trigger the menu aligns to. |
| size | `Button size` | `"sm"` | Trigger height: sm is 28px, default is 32px. Any other Button prop applies too. |

## When to use

- To narrow a list or grid by one facet with a handful of values
- In a toolbar next to search and sort, one menu per facet
- When counts help people see what each choice would leave

## When not to use

- For a single on or off facet, use a filter chip or a switch
- For dozens of values that need search, use a combobox
- For choosing exactly one value, use a select or a sort menu

## Notes for agents

- Controlled only: keep the checked values in state and pass value and onValueChange, so the parent must be a client component
- The menu stays open while people check items; Clear closes it and calls onValueChange with an empty list
- The trigger shows the count after a middle dot and sets data-active when anything is checked
- It extends shadcn's Button, so variant and size apply; the default is an outline sm pill

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