Model Picker · paneui

Installation

pnpm dlx shadcn@latest add @paneui/model-picker

Usage

import { EffortPicker, ModelPicker, ModePicker } from "@/components/ui/model-picker"

<ModePicker modes={modes} value={mode} onValueChange={setMode} />
<ModelPicker models={models} value={model} onValueChange={setModel} />
<EffortPicker value={effort} onValueChange={setEffort} />

Examples

Searchable

Use when the list runs past a screen, such as a model router's catalogue.

Composer Picker

ACP

Feed ModePicker from an agent's SessionModeState, ModelPicker from a config option with category: "model" (grouped options map to provider), and EffortPicker from category: "thought_level".

Search

With searchable focus stays in the search field: arrow keys move the highlight, Enter picks, Escape closes. Words match the label, value and group in any order. maxPerGroup caps each group until you search or press its “Show all” row; the current choice stays visible past the cap.

Descriptions

Model and effort rows show the name alone; a description you pass is kept and shows with showDescriptions. ModePicker and ComposerPicker show descriptions by default, since an access level needs its consequence spelled out.

Logos

Give each model its vendor's mark with <BrandIcon color="brand">. Marks the brand icon package leaves out, such as OpenAI and xAI, ship in @paneui/ui/lib/brand-marks with the same shape.

Testing

Every option carries its value as data-value, so tests can pick one without matching its label.

Tone

A mode with tone: "warning" (full access) or "destructive" colours the trigger while selected, so a risky setting is visible at a glance.

API Reference

ComposerPicker

options*: PickerOption[]; { value, label, description?, icon?, group?, tone?, disabled? }.
value: string; Selected value.
onValueChange: (value: string) => void; Called on pick.
label*: string; Accessible name of the trigger.
icon: ReactNode; Trigger glyph when the option has none.
heading: string; Label above the options.
side= "top": "top" | "bottom"; Menu side (top suits a composer at the bottom).
align= "start": "start" | "center" | "end"; Menu alignment.
footer: ReactNode; Menu items under the options; with searchable, a plain button or link.
searchable= false: boolean; Search field at the top of the list.
searchPlaceholder= "Search": string; Placeholder and accessible name of the search field.
emptyLabel= "No results": ReactNode; Shown when nothing matches.
maxPerGroup: number; With searchable, options shown per group before “Show all”.
compact= false: boolean; Inside an AgentComposer toolbar narrower than 28rem (phones, tablets, split panes), show only the glyph and chevron; the label stays the accessible name. ModePicker and EffortPicker default to true.
showDescriptions= true: boolean; Show each option's description under its name. ModelPicker and EffortPicker default to false.

Prop	Type	Default	Description
options*	PickerOption[]	—	`{ value, label, description?, icon?, group?, tone?, disabled? }`.
value	string	—	Selected value.
onValueChange	(value: string) => void	—	Called on pick.
label*	string	—	Accessible name of the trigger.
icon	ReactNode	—	Trigger glyph when the option has none.
heading	string	—	Label above the options.
side	"top" \| "bottom"	"top"	Menu side (top suits a composer at the bottom).
align	"start" \| "center" \| "end"	"start"	Menu alignment.
footer	ReactNode	—	Menu items under the options; with `searchable`, a plain button or link.
searchable	boolean	false	Search field at the top of the list.
searchPlaceholder	string	"Search"	Placeholder and accessible name of the search field.
emptyLabel	ReactNode	"No results"	Shown when nothing matches.
maxPerGroup	number	—	With `searchable`, options shown per group before “Show all”.
compact	boolean	false	Inside an `AgentComposer` toolbar narrower than 28rem (phones, tablets, split panes), show only the glyph and chevron; the label stays the accessible name. `ModePicker` and `EffortPicker` default to `true`.
showDescriptions	boolean	true	Show each option's `description` under its name. `ModelPicker` and `EffortPicker` default to `false`.

ModelPicker

Preset grouped by provider.

models*: { id, name, description?, provider?, icon? }[]; Models to offer.

Prop	Type	Default	Description
models*	{ id, name, description?, provider?, icon? }[]	—	Models to offer.

EffortPicker

Preset with a bolt glyph.

levels= low / medium / high: { value, label, description? }[]; Effort levels.

Prop	Type	Default	Description
levels	{ value, label, description? }[]	low / medium / high	Effort levels.

ModePicker

Preset with a shield glyph.

modes*: { id, name, description?, icon?, tone? }[]; Modes or access levels.

Prop	Type	Default	Description
modes*	{ id, name, description?, icon?, tone? }[]	—	Modes or access levels.