# Model Select

Pick the model and how hard it should think, with context size and price at a glance.

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

## Install

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

## Import

```tsx
import { ModelSelect, ModelCard } from "@wunderui/react"
```

## Minimal usage

Then use it:

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

const models = [
  { id: "claude-opus-5-5", name: "Claude Opus 5.5", meta: "Deepest reasoning" },
  { id: "claude-sonnet-5-5", name: "Claude Sonnet 5.5", meta: "Balanced" },
  { id: "claude-haiku-5-5", name: "Claude Haiku 5.5", meta: "Fastest" },
]

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

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

Expected result: You see a card with three models, Sonnet chosen, its name Claude Sonnet 5.5, a Reasoning effort control on Medium and the line Balanced (the default). Click Haiku and the details follow.

## When to use

### Use Model Select for

- A settings page or dialog where a person chooses the model and how hard it should think
- A choice that needs facts next to it: context window, price per 1M tokens, speed
- A short list of models, three to eight with search, each with a description

### Use something else

- [Model Picker](https://wunderui.com/components/model-picker) for the model chip of a prompt box
- [Combobox](https://wunderui.com/components/combobox) for a long list of options that is not a short model list, with type-ahead
- [Select](https://wunderui.com/components/select) for a plain select in a form, with a name and a placeholder
- [Usage Meter](https://wunderui.com/components/usage-meter) for what a run has cost so far

## Keyboard

The rows are buttons in a listbox with one tab stop, and the effort is a segmented control.

| Key | Action |
|---|---|
| `Tab` or `Shift+Tab` | Moves into the list on the chosen row (or the one you last moved to), then to the effort control, on its chosen option. The two other options are skipped. |
| `ArrowDown` or `ArrowUp` | In the list: moves focus to the next or previous row that can be chosen. It stops at the ends. On the first row of a `searchable` list, Up goes back to the search field; in the search field, Down goes to the chosen row. |
| `Home` or `End` | In the list: moves focus to the first or last row that can be chosen. |
| `Enter` or `Space` | On a row: chooses that model at once and calls `onValueChange`. On an effort option: chooses it. |
| `→` or `←` | In the effort control: moves to the next or previous option and chooses it, so `onEffortChange` is called on every press. After High comes Low. |
| `Home` or `End` | In the effort control: moves to Low or High and chooses it. |

Arrow keys in the list only move focus, skipping disabled rows. A model is chosen with Enter, Space or a click, and the effort options are tabs that choose as you move.

## Behavior

What the card does with the model, the effort and the list, and what it leaves to you.

- **Not a select:** ModelSelect is two panes, not a native select, with no name, form value, placeholder or groups. If you need those, build around the card or use Combobox or Select.
- **One model is always chosen:** The card shows the value, or its own choice starting at the default or the first enabled model, and an unknown value falls back to the first. With no models the card is empty, so do not render it.
- **The effort:** Effort is separate from the model and keeps its value when the model changes. It has three fixed values (low, medium by default, high) and three fixed hints.
- **What each field shows:** Name and meta show in the list, with a reason under a disabled row. Name, description and specs show in the details, and icon and tag are used by Model Picker only.
- **Choosing:** A click on a row or option chooses it at once; there is no confirmation or save. When controlled, your value wins: if your state does not change, the card stays where it was.
- **Search:** Search adds a field above the list that filters by name, meta, description and tag. A model filtered out stays chosen with its details visible; use it from about six models.
- **Focus:** The list is one tab stop: the chosen row, or the row you last reached with the arrow keys. Focus does not choose; Enter or Space does.
- **A model or an effort that cannot be used:** A disabled model stays in the list, dimmed and skipped by arrow keys, with its reason under it. Effort has no disabled option: keep the old effort and show the reason next to the card.
- **Layout:** Side by side from a 640 px viewport, stacked below it. The card grows with the list, names wrap and nothing is cut off.
- **The shadow:** The card brings its own border and shadow. Pass a no-shadow class when it sits inside a box that already has a border.
- **Motion:** Rows and effort options change colour quickly. Nothing else on the card moves; the effort pill does not slide.
- **Reduced motion:** With reduced motion the colour changes keep running; there is no transform to remove.

## Anatomy

- `ModelSelect`: A card with a 1 px border, 12 px radius and a shadow, up to 560 px wide. List and details sit side by side from a 640 px viewport and stack below it.
- `Model list`: A listbox named Models, 208 px wide beside the details, with a divider towards them. It does not scroll, so the card grows with the list, and only one row is a tab stop.
- `Search field`: With search on: a 32 px field named Search models above the rows. A search without a match shows No model matches.
- `Row`: One model as an option button: the name in 14 px medium and the meta below in 12 px. The chosen row has the subtle fill, and a disabled row is dimmed with its reason under it.
- `Title`: The name of the chosen model, 16 px semibold, at the top of the details.
- `Description`: The description of the chosen model in 12 px, if it has one.
- `Specs`: The specs as rows of a description list: label on the left, value on the right in medium weight. Not drawn without specs.
- `Effort`: The Reasoning effort label and a small segmented control named the same, with Low, Medium and High. The options are announced as tabs.
- `Effort hint`: One 12 px line for the chosen effort: Quick answers, lowest cost; Balanced (the default); or Thinks longer on hard problems and costs more. The words are fixed.

## Best practices

### When to use

- Use a Model Select on a settings page or in a dialog, where people weigh models by context size and price and pick how hard the model thinks. For a prompt box chip use Model Picker.

### Do

- Give each model a short meta for the list and put compared facts into specs: context window, price per 1M tokens, speed. Use the same labels for every model so values line up.
- Keep the choice in your state and say what it changes, such as Applies to new chats. The card is not a form control: no name, no form value, no submit.
- Disable a model that cannot be used, give a reason and keep the old value. For an unusable effort, say so next to the card and offer a way out: another model, or the plan that includes it.
- Order the list the way people choose: most capable or recommended first, not alphabetically.

### Don't

- Don't use it for a long list without search. Rows do not scroll, so the card grows with every model; past about eight models, or when you need groups, use Combobox.
- Don't rely on effort for a model that does not think longer. Effort is separate from the model and never changes when it does; reset it yourself if a model needs it.
- Don't start a request when the model or effort changes. Picking is immediate with no confirmation; save when the person says so.
- Don't disable a model without a reason. A dimmed row with no explanation looks like a bug; say what to do, such as Rate limit reached · back in a minute.

## API reference

### ModelSelect

| Prop | Type | Default | Description |
|---|---|---|---|
| models* | ModelOption[] |  | The models, in the order of the list: `{ id, name, meta?, description?, specs?: [label, value][], disabled?, reason? }`. `id` is the value. `meta` shows under the name in the list; `description` and `specs` show in the details. `disabled` keeps the row visible but not choosable and `reason` says why. `icon` and `tag` belong to Model Picker and are ignored here. |
| bare | boolean | false | Drops the border, radius and shadow of the card, for use inside a popover or sheet that has its own frame (no double frame). |
| className | string |  | Extra classes for the card, for example `shadow-none` or a narrower `max-w-md`. |
| defaultEffort | "medium" \| "low" \| "high" | "medium" | The effort that starts chosen when you do not pass `effort`. `medium` by default. |
| defaultValue | string |  | The id that starts chosen when you do not pass `value`. The first model by default. |
| effort | "medium" \| "low" \| "high" |  | `low`, `medium` or `high`, for a controlled card. If you do not change it in `onEffortChange`, the effort stays where it was. |
| onEffortChange | (effort: Effort) => void |  | Called with the new effort on every click and every arrow key in the effort control. |
| onValueChange | (id: string) => void |  | Called with the id of the row that was clicked, also for the row that is already chosen. |
| searchable | boolean | false | Adds a search field above the list that filters by name, meta, description and tag. Default false. |
| value | string |  | The id of the chosen model, for a controlled card. If you do not change it in `onValueChange`, the card stays where it was. |

### ModelCard

| Prop | Type | Default | Description |
|---|---|---|---|
| model* | ModelOption |  |  |
| badge | React.ReactNode |  | Replaces the badge. Default: "Off" while turned off, else `model.tag`. |
| className | string |  |  |
| enabled | boolean | true | Whether the model is on. Default true. |
| enabledLabel | string | "On" | Text beside the switch. Default "On". |
| footer | React.ReactNode |  | Small print at the start of the footer, e.g. "1,204 requests". |
| onEnabledChange | (enabled: boolean) => void |  | Shows the on/off switch in the footer. |
| onSelect | () => void |  | Makes the name a button that covers the card. |
| selected | boolean | false | The model that new chats start with: primary rim and subtle background. |
| specs | [string, React.ReactNode][] |  | Label and value pairs in two columns. Default: `model.specs`. |

## Examples

### Details: with specs, a description only, names only

### Models: three, long names, six, six with search

### Control: the card keeps the choice, or your state does

### Marks, bare in a popover, and the model card

## In context

### A settings page: the choice is saved, and Save waits for a change

Change the model or effort and Save turns on. The card is not a form control, so the page keeps the choice in state and confirms what it stored.

### An effort the plan does not include: the card stays, the reason and the way out stand next to it

Press High. The card has no disabled option, so the handler keeps Medium and a warning says why and offers See plans; choosing Low or Medium clears it.

### A model that is rate limited: the row is disabled with the reason, the working one is offered

Claude Opus 5.5 is disabled with a reason: the row stays, ignores clicks and is skipped by the arrow keys. The alert offers Claude Sonnet 5.5, which switches at once.

## For AI agents

`get_component("model-select")`

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