Combobox

items is the list of options, and unlike Select it's searchable by default — typing in the field filters it client-side. A bare string or number is the shorthand for an option whose label and value match; the long form is { label, value } with an optional icon and disabled. Mixing in { type: 'label' } and { type: 'divider' } entries is how a long list gets grouped.

modelValue is the selected value — the option's value, not its label, and an array of them once multiple is set. Pass it to control the selection yourself; v-model is the usual binding, so the reader's choice flows back.

defaultValue is what's selected on first render while the combobox still owns its own state. Reach for it when a starting choice is genuinely sensible — the reader's own country, the most common option — and you don't otherwise need to hold the value.

multiple lets more than one option be selected, and turns the selected set into removable tags inside the field.

placeholder is what the trigger reads while nothing is selected — distinct from searchPlaceholder, which belongs to the filter box inside the open list. Phrase it as the instruction it is, since it disappears the moment there's a value to show.

searchPlaceholder is the hint inside the search box at the top of the open list, defaulting to “Search…”. Worth naming what's being searched when the list holds something less obvious than its label suggests.

icon sits at the start of the trigger while nothing is selected; once an option carrying its own icon is chosen, that one replaces it. It's a way to say what the field is for without spending a label on it.

icon is usually just a name, but it also takes { name, color, fill }. color tints an option's own icon, independent of whether that option is selected — use it to flag a choice at a glance, like a status dot or a severity level, without coloring the label along with it. fill draws the icon's filled variant, for the icons that ship one.

disabled locks the whole input. Individual options can opt out on their own with a per-item disabled instead.

clearable shows a button to clear the current selection.

outline is the ringed field on the page background, and the right default wherever the control stands on its own. subtle is that same ring on a raised surface, matching a Card's own subtle, so the control belongs to the card it sits on. soft drops the ring for a plain fill. ghost shows nothing until hover, for a control sitting in a toolbar — it's the only one with a hover state, since without a resting fill it would otherwise give no sign it can be clicked.

content positions the dropdown relative to the field: side, align and sideOffset. Reach for it when the combobox sits near an edge the list would otherwise open across.

open controls whether the dropdown is showing. Pass it to drive the list from your own state and bind it with v-model:open so the reader's clicks still register; omit it and the combobox manages that itself.

defaultOpen starts the dropdown expanded on mount while leaving the open state uncontrolled — reasonable for a step whose only purpose is the choice, wrong wherever the field is one of several.