# Model Selector (/docs/agent-ui/components/model-selector)

Use a model selector in a prompt's toolbar when people can choose which model answers. The field shows the chosen model and its provider in one compact row, and typing in it filters the list, best match first, with the matching letters marked. Place [Reasoning Effort](./reasoning-effort.mdx) beside it when the model can think harder.

<Example caption="Type son55 in the Model field to find Claude Sonnet 5.5, then press Enter. Claude Opus 5.5 is disabled, so it can't be chosen.">
<Basic />

```tsx
"use client";
import { useState } from "react";
import { Composer, ComposerInput, ComposerSubmit } from "@/components/ui/composer";
import { ModelSelector } from "@/components/ui/model-selector";
import { ReasoningEffort } from "@/components/ui/reasoning-effort";
import { AnthropicLogo, GeminiLogo, MicrosoftLogo, OpenAILogo, XAILogo } from "./logos";

const models = [
  {
    id: "claude-opus-5.5",
    name: "Claude Opus 5.5",
    group: "Anthropic",
    description: "Not on your plan",
    disabled: true,
    icon: <AnthropicLogo />,
  },
  { id: "claude-sonnet-5.5", name: "Claude Sonnet 5.5", group: "Anthropic", icon: <AnthropicLogo /> },
  {
    id: "gpt-6.1-sol",
    name: "GPT-6.1 Sol",
    group: "OpenAI",
    description: "Deep reasoning",
    icon: <OpenAILogo />,
  },
  { id: "gpt-6-astra", name: "GPT-6 Astra", group: "OpenAI", icon: <OpenAILogo /> },
  { id: "gpt-5.6-sol", name: "GPT-5.6 Sol", group: "OpenAI", icon: <OpenAILogo /> },
  {
    id: "gpt-6.1-terra",
    name: "GPT-6.1 Terra",
    group: "OpenAI",
    description: "Fast and affordable",
    icon: <OpenAILogo />,
  },
  {
    id: "mai-code-2",
    name: "MAI Code 2",
    group: "Microsoft",
    description: "Built for code",
    icon: <MicrosoftLogo />,
  },
  {
    id: "gemini-4-argon",
    name: "Gemini 4 Argon",
    group: "Google",
    description: "Long context",
    icon: <GeminiLogo />,
  },
  { id: "gemini-3.8-flash", name: "Gemini 3.8 Flash", group: "Google", icon: <GeminiLogo /> },
  { id: "grok-4.7", name: "Grok 4.7", group: "xAI", icon: <XAILogo /> },
];

export default function ModelSelectorExample() {
  const [model, setModel] = useState<string | null>("claude-sonnet-5.5");
  const [effort, setEffort] = useState<string | null>("medium");
  return (
    <Composer aria-label="Message" className="w-full max-w-xl" onSubmit={() => undefined}>
      <ComposerInput aria-label="Prompt" placeholder="Ask anything" />
      <div className="flex items-center gap-2" style={{ gridArea: "attach" }}>
        <ModelSelector models={models} value={model} onValueChange={setModel} />
        <ReasoningEffort value={effort} onValueChange={setEffort} />
      </div>
      <ComposerSubmit />
    </Composer>
  );
}
```
</Example>

## Installation [#installation]

```bash tab="React"
npx shadcn@latest add @kind-ui/model-selector
```

```bash tab="Web Components"
npx shadcn@latest add @kind-ui/model-selector-web
```

## Composition [#composition]

```text
ModelSelector
├── ModelSelectorTrigger
│   ├── ModelSelectorIcon
│   └── ModelSelectorInput
└── ModelSelectorContent
    ├── ModelSelectorEmpty
    └── ModelSelectorGroup
        └── ModelSelectorItem
```

`ModelSelector` is a group named by its `label` that holds UI SDK's Combobox. `ModelSelectorTrigger` is the field: the chosen model's icon (`ModelSelectorIcon`), the search field, the chosen model's group and a button that opens the list. `ModelSelectorInput` is the search field, which shows the chosen model's name while the list is closed. `ModelSelectorContent` is the list, with a `ModelSelectorGroup` for each provider, a `ModelSelectorItem` for each model and `ModelSelectorEmpty` while nothing matches.

## Usage [#usage]

### Models [#models]

Pass `models`, each with an `id` and a `name`, and optionally a `group`, a `description`, an `icon` and `disabled`. The list shows the groups in the order they first appear, and each model with its description under its name. A disabled model stays in the list, dimmed, and can't be chosen by pointer, keyboard or `setValue`.

```tsx
<ModelSelector
  models={[
    { id: "gpt-6.1-sol", name: "GPT-6.1 Sol", group: "OpenAI", icon: "/logos/openai.svg" },
    { id: "claude-sonnet-5.5", name: "Claude Sonnet 5.5", group: "Anthropic", description: "Balanced" },
  ]}
  defaultValue="claude-sonnet-5.5"
  onValueChange={(id) => setModel(id)}
/>
```

Pass `value` and `onValueChange` to control the chosen model, or `defaultValue` to start with one. `onValueChange` gets the model's `id`, with the reason `input-change` when a person chose it, or `imperative` from `setValue`.

### Icons [#icons]

Give a model an `icon` to show it before the name, in its list row and, once it's chosen, in the field before the search text. In React, `icon` is an image URL or an element, like an inline `<svg>`:

```tsx
const models = [
  { id: "claude-sonnet-5.5", name: "Claude Sonnet 5.5", group: "Anthropic", icon: <AnthropicLogo /> },
  { id: "grok-4.7", name: "Grok 4.7", group: "xAI", icon: "/logos/xai.svg" },
];
```

Icons render at 16px. A monochrome SVG drawn with `currentColor` takes the text color, so it reads in light and dark. Icons are decorative and hidden from assistive technology, so the model's name stays its label. Rows keep one height and their names line up, whether or not a model has an icon. The package ships no logos; you pass your own.

### Searching [#searching]

Typing in the field filters the list as you type. A model matches when its name, group or description holds the letters in order, so "son55" finds Claude Sonnet 5.5. Within each group, the best match comes first, and a group with no match is hidden. The letters that matched the name are marked. When nothing matches, the list says "No models found.".

The field keeps its width whatever the model's name, so choosing a longer one moves nothing beside it; a long name is cut short with an ellipsis. Set `--kind-model-selector-width` to change the width.

### Keyboard [#keyboard]

The field is one Tab stop. Typing or Down Arrow opens the list. While you type, the best match is highlighted, so Enter chooses it; the arrow keys move the highlight, skipping disabled models. Escape closes the list and puts the chosen model's name back, with focus still in the field.

### Motion [#motion]

The list rises and fades in below the field. Under `prefers-reduced-motion`, or with `motion="reduced"`, it only fades, over 120 ms, and with `motion="none"` it opens at once.

## API Reference [#api-reference]

### ModelSelectorOptions

| Prop             | Type                                                                                                     | Description                                                                                                                                                                 |
| ---------------- | -------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `models?`        | `ModelOption<unknown>[] \| undefined`                                                                    | The models to choose from, grouped by their `group` in the order groups first appear. The primitive passes each `icon` through to the render layer untouched. Default: `[]` |
| `value?`         | `string \| null \| undefined`                                                                            | The chosen model's id. Passing it controls it: change it in `onValueChange`.                                                                                                |
| `defaultValue?`  | `string \| null \| undefined`                                                                            | The chosen model's id at first, when `value` isn't passed. Default: `null`                                                                                                  |
| `onValueChange?` | `((value: string \| null, details: ChangeDetails<ModelSelectorValueChangeReason>) => void) \| undefined` | Called when a person or `setValue` chooses a model, with why.                                                                                                               |
| `label?`         | `string \| undefined`                                                                                    | Names the picker and its search field. Default: `"Model"`                                                                                                                   |
| `placeholder?`   | `string \| undefined`                                                                                    | Shown in the search field while no model is chosen. Default: `"Search models"`                                                                                              |
| `openLabel?`     | `string \| undefined`                                                                                    | Names the button that opens the list. Default: `"Show models"`                                                                                                              |
| `disabled?`      | `boolean \| undefined`                                                                                   | Whether the picker can't be focused or changed. Default: `false`                                                                                                            |
| `motion?`        | `"auto" \| "none" \| "reduced"`                                                                          | How the list opens and closes. `"auto"` follows `prefers-reduced-motion`. Default: `"auto"`                                                                                 |

### Agent [#agent]

An agent connected with `createAgent` finds the model selector by its label and reads the chosen model's `id`. Its `setValue` takes a model's `id` or its name, the same as a person choosing it, and refuses a model that isn't listed. A disabled model returns `false` and changes nothing. It needs no person to confirm.

### ModelSelectorAgentActions

| Prop       | Type                      | Description                                                                                                |
| ---------- | ------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `setValue` | `(id: string) => boolean` | Chooses a model, as a person would. Returns `false` for an unknown or disabled model, or a refused change. |

<Caption>
Runs in React and Web Components. On `<kind-model-selector>`, set `models` and `value` as properties, and listen for `modelchange`, with the model's `id` as `event.detail.value`. A model's `icon` is an image URL or an Element, which the element clones into each row. The element fills in its field and list when it has no children.
</Caption>