# Model Picker

The model chip in a prompt box: always clickable, it opens a popover to switch models.

- Category: AI & Agents
- Page: https://wunderui.com/components/model-picker
- Tier: Core and Pro

## Install

Model Picker ships with WunderUI Core and Pro in the @wunderui/react package.

## Import

```tsx
import { ModelPicker, ModelPickerSize, ModelPickerTrigger } from "@wunderui/react"
```

## Minimal usage

Then use it:

```tsx
import { useState } from "react"
import { ModelPicker } from "@wunderui/react"

const models = [
  { id: "claude-opus-5-5", name: "Claude Opus 5.5", description: "Hard, multi-step work · 1M context · High cost" },
  { id: "claude-sonnet-5-5", name: "Claude Sonnet 5.5", description: "Everyday work · 1M context · Medium cost", tag: "Recommended" },
  { id: "claude-haiku-5-5", name: "Claude Haiku 5.5", description: "Fast answers · 200K context · Low cost" },
]

export function Chip() {
  const [model, setModel] = useState("claude-sonnet-5-5")

  return <ModelPicker models={models} value={model} onValueChange={setModel} />
}
```

Expected result: You see a pill with Claude Sonnet 5.5 and a chevron. Click it and a popover opens above with three rows and a check on Sonnet; ArrowDown, then Enter, and the chip reads Claude Haiku 5.5.

## When to use

### Use Model Picker for

- The model chip in the toolbar of a prompt box, where a person switches between a few models
- A place with little room, where the current model and a way to change it must fit on one line
- A model choice that applies to the next message and should be one click away

### Use something else

- [Model Select](https://wunderui.com/components/model-select) for a card with specs, price and reasoning effort, for a settings page
- [Combobox](https://wunderui.com/components/combobox) for a long list of anything else that needs search and type-ahead
- [Select](https://wunderui.com/components/select) for a plain field in a form
- [Prompt Mode Switch](https://wunderui.com/components/prompt-mode-switch) for choosing what the agent may do, not which model answers

## Keyboard

The chip is a button. The popover opens beside it, and its rows are buttons in a listbox with one tab stop.

| Key | Action |
|---|---|
| `Enter` or `Space` | On the chip: opens or closes the popover. On open, focus moves to the chosen row, or to the search field when `searchable`. A `disabled` chip does nothing. |
| `ArrowDown` | Moves focus to the next row that can be chosen. From the search field it goes to the chosen row. It stops at the last row. |
| `ArrowUp` | Moves focus to the previous row that can be chosen. On the first row of a `searchable` list it goes back to the search field. |
| `Home` or `End` | Moves focus to the first or the last row that can be chosen. |
| `Tab` or `Shift+Tab` | The list is one tab stop (the chosen row, or the one you last moved to). Past it focus leaves the popover; it stays open until you press Esc, pick a model or click outside. |
| `Enter` or `Space` | On a row: picks that model, calls `onValueChange`, closes the popover and returns focus to the chip. |
| `Esc` | Closes the popover and returns focus to the chip. Nothing is picked. |

Up, Down, Home and End move focus between rows that can be chosen, skipping disabled rows. A model is picked with Enter or Space, and there is no type-ahead.

## Behavior

What the picker does with the choice, the list and the popover, and what it leaves to you.

- **The value:** Pass a value and the picker shows that model. Without one it keeps its own choice, starting at the default or the first enabled model, and an unknown value falls back to the first.
- **Picking:** Clicking or pressing Enter on a row reports the pick and closes the popover. If you do not change the value, the chip stays on the old model, and a disabled row is never picked.
- **A model that cannot be used:** A disabled model stays in the list, dimmed, ignoring clicks and Enter and skipped by arrow keys, with its reason shown under it. If it is the current model, the chip still shows it.
- **An empty list:** With an empty list the chip has no name and the popover is empty, so show a placeholder or alert instead (Prompt Input hides the chip). A search with no match shows No model matches.
- **Rows:** A row shows the description, or meta if there is none, the icon (a sparkle by default) and the tag. Text wraps, but the chip never truncates the name, so keep names short.
- **Search:** Search adds a field above the rows that filters by name, meta, description and tag, ignoring case. The query clears when the popover closes; use it from about seven models.
- **Focus:** On open, focus goes to the chosen row so the arrow keys start there, or to the search field when it is on. Closing returns focus to the chip, and the list is one tab stop.
- **Disabled chip:** A disabled chip dims to 40%, leaves the tab order and keeps the popover closed. Prompt Input passes its own disabled state on to the chip.
- **The popover:** The popover is not modal, so the page stays usable behind it. It closes on Escape, on a pick and on a press outside.
- **In Prompt Input:** Prompt Input shows this chip in its toolbar as soon as it gets models, and the popover opens upwards over the box.
- **Motion:** The popover fades in and zooms from 95% with an overshoot ease, and leaves faster. The chevron turns, and the mark changes colour on hover.
- **Reduced motion:** With reduced motion the zoom is removed and the fade stays, the chevron turns at once, and colour changes keep running.

## Anatomy

- `ModelPicker`: The chip: a 32 px pill button with the mark, the current model name and a chevron that turns while the popover is open. It is named Model plus the name, and disabled it dims to 40% and does not open.
- `Mark`: A 14 px icon before the name: the current model's icon, a sparkle by default. Grey, turning indigo on hover and while the popover is open.
- `Popover`: The panel: 320 px wide (never wider than the viewport minus 2 rem), 12 px radius, a dialog named by the label. It opens beside the chip, above and aligned to the start by default.
- `Heading`: The label as a 12 px line above the list, Model by default.
- `Search field`: With search on: a 32 px field named Search models between heading and rows. It filters by name, meta, description and tag, and the popover opens with focus in it.
- `Row`: One model as an option button with 8 px radius. The chosen row has the subtle fill, hover the page fill, and a disabled row has no hover; the whole list is one tab stop.
- `Row mark`: A 28 px tile with the model's icon on the indigo tint.
- `Name and tag`: The name in 14 px medium and, if the model has a tag, a small indigo pill beside it, such as Recommended.
- `Description`: The description, or meta when there is none, in 12 px secondary text. It wraps onto as many lines as it needs.
- `Reason`: The reason a model is disabled: 12 px secondary text under the description at full contrast while the row is dimmed. Assistive technology reads it as the row's description.
- `Check`: A 16 px check at the right edge, visible on the chosen row only.

## Best practices

### When to use

- Use a Model Picker as the small chip of a prompt box, for a few models. For a full card with specs and reasoning effort use Model Select; for a long searchable list use Combobox.

### Do

- Put what the model is for, its context size and cost tier in the one description line: Hard, multi-step work · 1M context · High cost. It wraps if it needs more.
- Mark the default with a tag such as Recommended, and only one.
- Disable a model that cannot be used and give a reason, such as Rate limit reached · try again in about a minute. Keep the model's description as it is.
- Say what the choice changes in a line near the box: The next message uses Claude Haiku 5.5. Earlier messages keep their model.
- Leave the popover opening upwards for a chip at the bottom of the screen, where a prompt box sits, and open it downwards near the top.

### Don't

- Don't render the picker with an empty list, because the chip would have no name. Show a placeholder while models load and an alert with a retry when they fail.
- Don't show more than about seven models without the search field. For hundreds of options use Combobox.
- Don't switch the model behind a person's back. When the chosen model goes down, keep the chip on it, disable the row with a reason and block sending until another is picked.
- Don't disable a model nobody can ever use; leave it out of the list. A disabled row is for a state that can change, and its reason should say what to do.

## API reference

### ModelPicker

| Prop | Type | Default | Description |
|---|---|---|---|
| models* | ModelOption[] |  | The models, in the order of the list: `{ id, name, meta?, description?, tag?, icon?, disabled?, reason? }`. `id` is the value, `name` the label of the row and the chip. `disabled` keeps the row visible but not choosable and `reason` says why. `specs` is part of the type but only Model Select shows it. |
| align | "start" \| "center" \| "end" | "start" | `start` (default), `center` or `end`: how the popover lines up with the chip along its edge. |
| className | string |  | Extra classes for the chip, for example `ml-1`. Prompt Input sets that one. |
| defaultEffort | "medium" \| "low" \| "high" |  |  |
| defaultOpen | boolean | false |  |
| defaultValue | string |  | The id that starts chosen when you do not pass `value`. The first model by default. |
| disabled | boolean | false | Turns the chip off: it shows the current model, is dimmed to 40 % and does not open. Default false. |
| effort | "medium" \| "low" \| "high" |  | `panel="card"` only: the reasoning effort. Works like `value` and `onValueChange`. |
| label | string | "Model" | The heading above the list and the accessible name of the popover and the list. `Model` by default. |
| onEffortChange | (effort: Effort) => void |  |  |
| onOpenChange | (open: boolean) => void |  |  |
| onValueChange | (id: string) => void |  | Called with the id of the row that was picked, just before the popover closes. It is also called for the row that is already chosen. |
| open | boolean |  | Open state, to control the popover or to show it open at first. |
| panel | "list" \| "card" | "list" | `list` (default): a list of the models. `card`: the Model Select card with specs and the reasoning effort of the chosen model. |
| searchable | boolean | false | Adds a search field above the rows that filters by name, meta, description and tag. The popover then opens on the field. Default false. |
| side | "top" \| "bottom" | "top" | `top` (default) or `bottom`: where the popover opens against the chip. |
| size | "sm" \| "md" | "md" | `md` 32 px (default) or `sm` 28 px for a header or a mobile bar. |
| value | string |  | The id of the chosen model, for a controlled picker. If you do not change it in `onValueChange`, the chip stays on the old model. |

### ModelPickerTrigger

| Prop | Type | Default | Description |
|---|---|---|---|
| model | ModelOption |  | The chosen model: its icon (a sparkle without one) and name show on the chip. |
| size | "sm" \| "md" | "md" | `md` 32 px (default) or `sm` 28 px for a header or a mobile bar. |

Also accepts React.ButtonHTMLAttributes attributes.

## Examples

### Rows: a description and a tag, a meta line, your own marks, text that wraps

### Availability: all ready, rate limited, no access (disabled rows with a reason)

### Search: a field above a long list

### Align: the popover lines up with the start, the middle or the end of the chip

### Small chip, card panel, own trigger

## In context

### In a prompt box: the choice applies to the next message

Prompt Input shows the picker in its toolbar once it gets models, and it opens upwards. Pick a model and send: the line names the one used, and earlier messages keep theirs.

### The chosen model goes down: the row says so and sending stops

Press Simulate an outage. The Claude Opus 5.5 row is disabled with its reason, and Enter keeps the text and shows why nothing was sent; pick another model and send again.

### The list of models: loading, failed with a way out, ready

Never render the picker with an empty list, as the chip would have no name. Show a placeholder while loading, an alert with Try again on failure, and the picker once there are models.

## For AI agents

`get_component("model-picker")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
