Forms
LanguageSelect
A language picker showing each language in its own name, with an optional flag — as a full-width field with search, or a compact icon button for a navbar.
<UiLanguageSelect />Model value
modelValue is the selected language code — en, de, pt-BR. Pass it to control the selection yourself; the picker never falls back to empty, so a code that matches nothing in the list shows the first entry rather than a blank trigger.
The selection never falls back to empty — an unrecognised modelValue shows the first entry in the list rather than the placeholder, because a UI is always rendering in *some* language. The placeholder only appears if languages is empty.
Default value
defaultValue is the language the picker starts on when you leave it uncontrolled, given as the same code. It applies once, on mount — after that the picker owns the selection, and passing modelValue takes it over entirely.
Languages
languages replaces the built-in eight-language list rather than merging with it, so include every option you want offered. Each entry is the language's own name (Deutsch, not German — that's the convention for a picker someone reaches for precisely because they can't read the current language), a code used as the value, an optional englishName that only the search box sees, and an optional flag URL. Regional variants are just entries with a longer code.
Each language is listed under its own name (Deutsch, not German) — that is the convention for a picker someone reaches for precisely because they cannot read the current language. englishName is never rendered; it exists so the search box also matches german, alongside the code.
languages fully replaces the built-in eight-language list rather than merging with it — include every option you want shown. flag is optional per entry, so a custom list needs no image assets.
A flag denotes a country, not a language, so the built-in list pairs each language with its most associated country (English with GB, Portuguese with BR). Where that is wrong or contentious for your audience, pass your own languages or set show-flags="false" for a globe icon instead.
Trigger
trigger chooses the shape of the control: a full-width field for a form, or a compact square icon button showing just the current flag for a navbar or footer. Each gets its own section below.
trigger="field" is a full-width form control with a search box; trigger="compact" is a square icon button showing only the current flag, with no search box and the list aligned to the trigger's right edge. Override either with searchable and content.align.
Show flags
showFlags puts a flag beside each language; turn it off for a globe icon and text only. A flag denotes a country, not a language, so drop them where that mapping would be wrong or contentious for your audience.
Searchable
searchable puts a search box above the list. It follows the trigger by default — on for field, off for compact, where the list is usually short enough not to need one — so set it only to go against that. The box matches each entry's englishName and code as well as its own name, which is what lets someone find 日本語 by typing “japanese”.
Placeholder
placeholder is what the field trigger shows when the current value matches no language in the list. With the built-in list that only happens briefly, if at all — it matters once you pass a languages array that a stored preference might have fallen out of.
Disabled
disabled switches off the trigger so the list can't be opened — for a language that's fixed by the account, or a form that's mid-save.
Variant
variant picks between the ringed outline trigger on the page background and the filled, ringless soft one, which gets its own section below.
Content
content positions the dropdown: side (bottom or top), align and sideOffset. align defaults to end for the compact trigger, since that one usually sits at the right edge of a navbar and a list aligned left would hang off the screen. Reach for this when the trigger sits near an edge the list would otherwise open across.
Open
open controls whether the list is showing. Pass it to drive the panel from your own state — opening the picker from a keyboard shortcut, or closing it when a step completes — and bind it with v-model:open so the reader's own clicks still land. Omit it and the component manages that itself.
Default open
defaultOpen starts the list expanded on mount while leaving the open state uncontrolled. It's a narrow tool — a language step that exists only to be answered — and wrong anywhere the picker is one field among several.
`trigger="compact"`
A square icon button showing just the current flag, for a navbar or footer. No search box, and the list aligns to the trigger's right edge.
The compact trigger is icon-only, so it carries an aria-label naming the current language — screen reader users hear the selection that sighted users read off the flag.
`variant="soft"`
A filled, tinted background with no ring.
API Reference
Generated from the component's source — props, slots and emits as the component actually declares them.
Props
"field" | "compact"'field'booleanstring'Select language…'LanguageSelectContentProps{ side: 'bottom', sideOffset: 8 }booleanEmits
update:modelValue[value: string]update:open[value: boolean]Types
interface Language {
/**
* The language's own name, in that language — 'Deutsch', not 'German'. This is what's rendered.
*/
name: string;
/**
* ISO 639-1 (or BCP 47) code, e.g. 'de' or 'pt-BR'. Used as the selection value.
*/
code: string;
/**
* The English name. Never rendered — it's matched by the search box, so someone who can't read
* the script can still find '日本語' by typing 'japanese'.
*/
englishName?: string;
/**
* URL of the flag image rendered next to the language, passed straight to `Avatar`'s `src`.
*/
flag?: string;
}interface LanguageSelectContentProps {
align?: "start" | "center" | "end";
side?: "bottom" | "top";
sideOffset?: number;
}