# Sort menu (goodtabs UI)

A pill that opens a menu with a radio group for the sort field and one for direction.

## Install

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

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

## Usage

```tsx
import { SortMenu } from "@/components/ui/sort-menu"

const [sort, setSort] = useState({ field: "name", direction: "asc" })

<SortMenu
  fields={[{ value: "name", label: "Name" }, { value: "added", label: "Date added" }]}
  value={sort}
  onValueChange={setSort}
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| fields | `{ value: string; label: string }[]` |  | The fields people can sort by, in menu order. |
| value | `{ field: string; direction: "asc" | "desc" }` |  | The current field and direction. The component is controlled. |
| onValueChange | `(value: SortValue) => void` |  | Called with the new field and direction whenever either changes. |
| label | `string` | `"Sort"` | Word before the field name in the trigger. |
| iconOnly | `boolean` | `false` | Hide the text and show only the icon, with the label as the accessible name. |
| 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

- Above a list, table or grid that people can reorder by more than one field
- In a toolbar next to search and filter controls
- When direction matters as much as the field, so both are one choice away

## When not to use

- For a single toggle between two orders, use a button that flips
- For column sorting in a table, put the control in the column header
- When there is only one field to sort by

## Notes for agents

- Controlled only: keep { field, direction } in state and pass both value and onValueChange, so the parent must be a client component
- The trigger reads Sort: plus the label of the current field; the direction is read out to screen readers
- Pass align="end" when the trigger sits at the right edge of a toolbar
- It extends shadcn's Button, so variant and size apply; the default is an outline sm pill

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