{"slug":"model-picker","category":"composer","job":"steer","added":"2026-11-07T22:47Z","title":"Model Picker","description":"A composer chip that opens a list of models, each with a one-line description, plan-locked options that lead to an upgrade, and an extended-thinking switch.","url":"https://ai-patterns.app/patterns/composer/model-picker","markdown":"https://ai-patterns.app/patterns/composer/model-picker.md","json":"https://ai-patterns.app/api/patterns/composer/model-picker","seenIn":[{"team":"Cursor","source":"https://docs.cursor.com/models"},{"team":"chatgpt","source":"https://help.openai.com/en/articles/20001354-gpt-6-and-other-models-in-chatgpt"},{"team":"Claude","source":"https://support.claude.com/en/articles/8664678-change-the-model-effort-and-thinking-settings"},{"team":"Google Gemini","source":"https://support.google.com/gemini/answer/18648722?hl=en"},{"team":"v0","source":"https://v0.app/changelog"}],"spec":"# Model Picker\n\n## Summary\nA compact chip in the composer that opens a list of models, each with a one-line description of what it is good at, plus an optional extended-thinking switch. It lets users trade speed for capability per message without leaving the prompt.\n\n## When to use\n- Products that offer more than one model or reasoning mode, and where the choice changes the result in a way users can feel (speed, depth, cost).\n- Power-user surfaces — chat, coding assistants, research tools — where people switch models between tasks.\n- Plans that unlock better models, so locked options double as an upgrade path.\n\n## When not to use\n- A single model, or models that differ only in ways users can't perceive. Route automatically instead of asking.\n- Consumer surfaces where the choice would be noise. Offer an \"auto\" default and hide the picker behind settings.\n- Choosing a provider or API key — that is configuration, not a per-message choice.\n\n## Anatomy\n- Trigger chip: the selected model's name, a \"· Thinking\" suffix when extended thinking is on, and a chevron.\n- Menu: one row per model with name, optional badge (\"New\", \"Beta\") and a one-line description.\n- Selected indicator: a check on the current model.\n- Locked rows: muted name and an \"Upgrade\" tag (or a lock icon when there is no upgrade path).\n- Optional footer: an extended-thinking switch with a short explanation.\n\n## Behavior\n- The menu opens above the trigger by default, because composers sit at the bottom of the screen.\n- Choosing a model closes the menu and returns focus to the trigger; toggling thinking keeps it open.\n- Locked models stay visible and can't be selected. Choosing one closes the menu and starts the upgrade flow instead, so the row is an upgrade path, not a dead end.\n- The choice persists for the conversation (and ideally as the user's default). A model change mid-conversation applies to the next message, not to past ones.\n- Clicking outside, pressing Escape or tabbing away closes the menu.\n\n## Content guidelines\n- Describe what a model is for, not its parameters: \"Quick answers for everyday tasks\", not \"8B params, 128k context\".\n- Keep names short and stable; put version numbers in the description or badge, not the trigger.\n- Order models from fastest to most capable, so the list reads as a scale.\n- Use badges sparingly — one \"New\" at a time.\n\n## Accessibility\n- The trigger is a real button with `aria-haspopup=\"listbox\"` and `aria-expanded`.\n- The list uses `role=\"listbox\"` with `role=\"option\"` rows, `aria-selected` on the current model and `aria-disabled` on locked ones; focus stays on the list and `aria-activedescendant` tracks the highlighted row.\n- Arrow keys move, Home/End jump, Enter or Space selects, Escape closes and returns focus to the trigger.\n- The thinking control is a `role=\"switch\"` with a visible label.\n\n## Related patterns\n- **Prompt Bar** — Use it instead when a minimal dropdown is enough and models don't need descriptions, plan gating or a thinking switch.\n- **Cost Estimate** — Use it as well when models are priced differently, so people see what the chosen one will cost before running.\n- **Rate Limit** — Use it as well when people hit limits on an expensive model, and point them to the picker to step down.\n","code":"\"use client\";\n\nimport * as React from \"react\";\nimport { AnimatePresence, motion } from \"motion/react\";\nimport { Check, ChevronDown, Lock } from \"lucide-react\";\n\nimport { cn } from \"@/lib/utils\";\n\nexport interface ModelOption {\n id: string;\n label: string;\n /** One line on what the model is good at — not a spec sheet. */\n description?: string;\n /** A short tag such as \"New\" or \"Beta\". */\n badge?: string;\n /** Not available on the user's plan: shown, but not selectable. */\n locked?: boolean;\n}\n\nexport interface ModelPickerProps {\n models: ModelOption[];\n value: string;\n onChange: (id: string) => void;\n /** Show an extended-thinking switch under the list when this is defined. */\n thinking?: boolean;\n onThinkingChange?: (thinking: boolean) => void;\n thinkingLabel?: string;\n upgradeLabel?: string;\n onUpgrade?: () => void;\n /** Which way the menu opens. Composers sit at the bottom, so \"up\" is the default. */\n side?: \"up\" | \"down\";\n className?: string;\n}\n\nexport function ModelPicker({\n models,\n value,\n onChange,\n thinking,\n onThinkingChange,\n thinkingLabel = \"Extended thinking\",\n upgradeLabel = \"Upgrade\",\n onUpgrade,\n side = \"up\",\n className,\n}: ModelPickerProps) {\n const [open, setOpen] = React.useState(false);\n const [active, setActive] = React.useState(0);\n const rootRef = React.useRef(null);\n const triggerRef = React.useRef(null);\n const listRef = React.useRef(null);\n const id = React.useId();\n\n const selected = models.find((m) => m.id === value) ?? models[0];\n\n React.useEffect(() => {\n if (!open) return;\n function handle(e: MouseEvent) {\n if (rootRef.current && !rootRef.current.contains(e.target as Node)) setOpen(false);\n }\n document.addEventListener(\"mousedown\", handle);\n return () => document.removeEventListener(\"mousedown\", handle);\n }, [open]);\n\n function openMenu() {\n setActive(Math.max(0, models.findIndex((m) => m.id === selected?.id)));\n setOpen(true);\n requestAnimationFrame(() => listRef.current?.focus());\n }\n\n function close() {\n setOpen(false);\n triggerRef.current?.focus();\n }\n\n function choose(index: number) {\n const model = models[index];\n if (!model) return;\n if (model.locked) {\n // A locked row is an upgrade path, not a dead end.\n if (onUpgrade) {\n setOpen(false);\n onUpgrade();\n }\n return;\n }\n onChange(model.id);\n close();\n }\n\n function handleListKeyDown(e: React.KeyboardEvent) {\n if (e.key === \"ArrowDown\") {\n e.preventDefault();\n setActive((i) => (i + 1) % models.length);\n } else if (e.key === \"ArrowUp\") {\n e.preventDefault();\n setActive((i) => (i - 1 + models.length) % models.length);\n } else if (e.key === \"Home\") {\n e.preventDefault();\n setActive(0);\n } else if (e.key === \"End\") {\n e.preventDefault();\n setActive(models.length - 1);\n } else if (e.key === \"Enter\" || e.key === \" \") {\n e.preventDefault();\n choose(active);\n } else if (e.key === \"Escape\" || e.key === \"Tab\") {\n if (e.key === \"Escape\") e.preventDefault();\n close();\n }\n }\n\n return (\n
\n (open ? setOpen(false) : openMenu())}\n onKeyDown={(e) => {\n if (e.key === \"ArrowDown\" || e.key === \"ArrowUp\") {\n e.preventDefault();\n openMenu();\n }\n }}\n className=\"flex items-center gap-1 rounded-lg px-2 py-1 text-xs font-medium text-muted-foreground transition-colors hover:bg-accent hover:text-foreground aria-expanded:bg-accent aria-expanded:text-foreground\"\n >\n {selected?.label}\n {thinking && · Thinking}\n \n \n\n \n {open && (\n \n \n {models.map((model, i) => {\n const isSelected = model.id === selected?.id;\n return (\n setActive(i)}\n onClick={() => choose(i)}\n className={cn(\n \"flex cursor-pointer items-start gap-2 rounded-lg px-2.5 py-2\",\n i === active && \"bg-accent\",\n model.locked && !onUpgrade && \"cursor-default\"\n )}\n >\n
\n
\n \n {model.label}\n \n {model.badge && (\n \n {model.badge}\n \n )}\n
\n {model.description && (\n

{model.description}

\n )}\n
\n {model.locked ? (\n onUpgrade ? (\n // Not a nested button: the whole row is the upgrade action.\n \n \n {upgradeLabel}\n \n ) : (\n \n )\n ) : (\n isSelected && \n )}\n \n );\n })}\n \n\n {thinking !== undefined && (\n
\n \n

Slower, more careful answers for hard problems.

\n
\n )}\n \n )}\n \n
\n );\n}\n\nfunction Switch({\n checked,\n onCheckedChange,\n label,\n}: {\n checked: boolean;\n onCheckedChange: (checked: boolean) => void;\n label: string;\n}) {\n return (\n onCheckedChange(!checked)}\n className={cn(\n \"relative inline-flex h-5 w-9 shrink-0 items-center rounded-full transition-colors\",\n checked ? \"bg-foreground\" : \"bg-muted-foreground/30\"\n )}\n >\n \n \n );\n}\n","dependencies":["lucide-react","motion"],"localImports":["@/lib/utils"]}