# FilterPill

> A toggle for one filter value, announced as pressed. Pair it with the use-url-filter hook to keep the choice in the URL.

Section: Forms. Docs: https://entrepta.vercel.app/docs/components/filter-pill

## Install

```bash
npx @entrepta/cli@latest add filter-pill
```

Files: `primitives/filter-pill.tsx`, `hooks/use-url-filter.ts`.
npm packages: `@phosphor-icons/react`.
Comes with: `use-url-filter`.

## Usage

```tsx
import { FilterPill } from "@/components/entrepta/filter-pill"
import { useUrlFilter } from "@/hooks/use-url-filter"

const TYPES = ["film", "book"] as const
const [type, setType] = useUrlFilter("type", TYPES)

{TYPES.map((t) => (
  <FilterPill
    key={t}
    label={t}
    count={counts[t]}
    active={type === t}
    onClick={() => setType(type === t ? null : t)}
  />
))}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `ReactNode` | - | Text on the pill |
| `active` | `boolean` | - | Pressed state, sets aria-pressed |
| `count` | `number` | - | Tally beside the label, at full contrast |
| `icon` | `Icon` | - | A Phosphor icon; it fills when active |
| `useUrlFilter(param, allowed, path?, { replace? })` | `[value, set]` | - | Hook: reads and writes ?param=value, prerender safe. pushState by default; { replace: true } for a form of options, so back does not walk through each click |