LocaleSwitcher
Dropdown for switching the application's display language.
Playground
Variant
·
<LocaleSwitcher />01 Examples
LocaleSwitcher reads and sets the language through the
app's i18n setup, so mount it under your <I18nProvider>. Pass locales to choose which languages it offers.
Restrict the languages
Only the languages you list appear, in that order.
·
<LocaleSwitcher showFlag locales={['en', 'de', 'fr']} />In a settings panel
A language row inside a settings card.
Preferences
Language
Region
·
<div
class="bg-surface-elevated border-border-subtle w-full overflow-hidden rounded-2xl border"
>
<div class="border-border-subtle border-b px-5 py-3">
<h3 class="text-text-primary text-sm font-semibold">Preferences</h3>
</div>
<div class="divide-border-subtle divide-y">
<div class="flex items-center justify-between px-5 py-3">
<p class="text-text-primary text-sm font-medium">Language</p>
<LocaleSwitcher variant="outlined" size="sm" showFlag />
</div>
<div class="flex items-center justify-between px-5 py-3">
<p class="text-text-primary text-sm font-medium">Region</p>
<Select
aria-label="Region"
options={[
{ label: 'Europe', value: 'eu' },
{ label: 'North America', value: 'na' },
{ label: 'Asia', value: 'asia' }
]}
value="eu"
variant="outlined"
size="sm"
/>
</div>
</div>
</div>02 Customization
Primary-tinted trigger
The slotClasses prop restyles individual parts: the trigger, its chevron, the open list. Your classes are added to the built-in ones, so the default sizing and keyboard behaviour stay.
·
<LocaleSwitcher
showFlag
slotClasses={{
trigger: 'bg-primary-subtle border-primary text-primary-text hover:border-primary',
chevron: 'text-primary',
listbox: 'border-primary'
}}
/>This is one of five ways to restyle a block. See Customization for class, slotClasses, unstyled, preset and provider-level overrides.
03 Accessibility
Built-in ARIA
Inherits the Select listbox semantics:role="listbox", aria-expanded and aria-selected, plus a trigger aria-label.Keyboard
↑ ↓ navigate, Enter selects, Esc closes.Localized names
Each option's language name is shown in the current language.04 API Reference
28 props28 props
Add filter
Sort
Grouping · No column can be grouped
Summary · No column can be summarized
Column visibility
Prop | Type | Default | Description | |
|---|---|---|---|---|
class inherited | string | — | Extra classes merged onto the root wrapper element. | |
clearable inherited | boolean | false | Show a clear button when a value is selected. | |
closeOnClickOutside inherited | boolean | — | Whether the listbox closes on outside click. Default true.
Set to false to pin the listbox open while the consumer manages
dismissal explicitly. | |
closeOnEscape inherited | boolean | — | Whether the listbox closes on Escape key. Default true.
Set to false for inline contexts where Escape should be intercepted
by an outer widget (e.g. a row editor that wants to revert on Escape). | |
customItem inherited | Snippet<[SelectOption<string>, boolean, () => void]> | — | Replace the default per-option rendering. Receives the option, its
selection state, and a toggle callback (call to select/deselect).
The outer <div role="option"> container is still owned by Select for
ARIA correctness — the snippet renders the option's visible contents.
Positional args: (option, isSelected, toggle). | |
customTrigger inherited | Snippet<[SelectOption<string>[], boolean, () => void]> | — | Replace the entire trigger button (chevron, label, clear control) with a
custom element. Receives the selected options, current open state, and a
clear callback. Use this for icon-only triggers, badge-counter triggers,
or any non-standard chrome — the Select still owns open/close + selection
state via the returned callbacks.
Positional args: (selected, open, clear). | |
customTriggerContent inherited | Snippet<[SelectOption<string>[]]> | — | Replace only the trigger's text/label area (chevron and clear button stay
intact). Receives the selected options. Useful for showing icons next to
the label, badges with counts, or formatted multi-select summaries while
keeping the standard outlined-Select chrome.
It receives the selected options, which is [] for a null value even
where nullOption is set — the null option is a row, not a selection — so
a custom trigger renders nothing exactly where the default one says "All
strands"; render your own nullOption label for the empty case.
Positional args: (selected). | |
disabled inherited | boolean | false | disabled property | |
id inherited | string | — | Explicit id for the component. Auto-generated if omitted.
The id lands on the component's wrapper, which is not a labelable element.
The focusable trigger is derived from it as ${id}-trigger — that is
the id an external <label for> has to address, since a for pointing at
the wrapper focuses nothing. | |
locales | Locale[] | — | Restrict the displayed locales. Defaults to all locales registered in i18n. | |
mint | SelectSingleProps<string>['mint'] | 'none' | Micro-interaction preset, forwarded to the inner Select trigger. | |
onClickOutside inherited | () => void | — | Fires after an outside click closes the listbox. Use for analytics
or side-effects on dismiss. Does NOT control whether the listbox
closes — that is governed by closeOnClickOutside. | |
onEscape inherited | () => void | — | Fires after Escape closes the listbox. Use for analytics or to clear
ephemeral state on dismiss. Does NOT control whether the listbox
closes — that is governed by closeOnEscape. | |
onLocaleChange | (locale: Locale) => void | — | Called after the locale has been changed successfully. | |
onOpenChange inherited | (open: boolean) => void | — | Fires when the listbox opens or closes from user interaction (trigger
click, keyboard, selection, Escape, Tab-out, outside click). Receives the
new open state — use it e.g. to lazy-load options on first open. Not
called when the consumer writes bind:open directly. | |
open inherited | boolean | false | Controls whether the listbox is open. Supports bind:open for parents that
need to coordinate open/close (e.g. attaching a custom trigger button outside
the Select wrapper). | |
placeholder | string | — | Text shown while the active locale is not among locales, in place of the
localized default. While a locale loads, the localized loading text is
shown instead. | |
preset | string | — | Apply a named preset registered via <BlocksProvider presets={{ LocaleSwitcher: {...} }}>.
Resolved against the LocaleSwitcher key, not Select: a preset written
for the locale picker would otherwise style every select under the provider.
defaults.Select still applies — the resolved preset reaches Select as
instance slotClasses, so it wins over the provider's select-wide defaults
and loses to slotClasses / class written on this component.
A preset's overrides rules are matched against what you wrote here plus
Select's own variant defaults; an axis Select derives for itself (tier,
messageType, error, open) can match the wrong state — #360. | |
required inherited | boolean | false | Marks the field as mandatory: adds the asterisk to the label and sets
aria-required on the trigger. When name is set (and the field is not
disabled), an empty Select also blocks native form submission — the hidden
form-bridge input is exempt from constraint validation, so an invisible
required input participates in its place while nothing is selected. Focus
then returns to the trigger, which means no native validation bubble; pass
error to tell the reader what is wrong. | |
selectionIndicator inherited | checkmarknone | — | Selection indicator rendered next to each option.
- 'checkmark' — trailing check icon (default)
- 'none' — no indicator (typical when using customItem) | |
showFlag | boolean | false | Show flag emoji alongside locale name. | |
size | SelectSingleProps<string>['size'] xssmmdlg +1 more | 'sm' | Control size, forwarded to the inner Select. | |
slotClasses inherited | Partial<Record<SelectSlots, string>> | — | Per-slot class overrides merged with tv() styles. Slots: wrapper (root —
what class also targets) | base | trigger | triggerText | placeholder |
chevron | clear | listbox | option | optionLabel | optionHint | optionCheck |
optionCheckbox | group | groupLabel | label | requiredMark | message. | |
syncWidth inherited | boolean | true | Whether the listbox matches the trigger's width. Set false for icon-only
or compact triggers where the listbox should size to its content instead. | |
tier | SelectSingleProps<string>['tier'] modifycommit | 'modify' | Corner-radius tier, forwarded to the inner Select. Read from the wrapping
TierContext when unset. | |
unstyled inherited | boolean | — | Remove all default tv() classes. | |
usePortal inherited | boolean | true | When true, the listbox is rendered into the browser top layer via the native
popover API, so it cannot be clipped by overflow: auto ancestors. When
false, the listbox stays in the regular DOM flow — useful inside other
popovers/portals to avoid double-portaling. A scroll box that holds its
offset parent then clips it, so the list flips and caps its height to stay
inside that box. | |
variant inherited | SelectVariants['variant'] outlinedfilledghostunderline +1 more | 'outlined' | Visual style.
- outlined (default) — visible border, surface-base background
- filled — surface-interactive fill, no border (compact toolbars)
- ghost — transparent until hover/focus (dense menus, inline editors)
- underline — bottom-line only, no border-box (editorial knob-strips,
docs playgrounds)
- bare — no frame, no fill, no padding, no fixed height: an inline word
choice that keeps the listbox role. size keeps only the type step, and
focus is an outline in --blocks-focus-ring-color |
05 Types
4 types
Name | Kind | Category | Used by | Description | |
|---|---|---|---|---|---|
LocaleSwitcherProps | interface | props | — | Props interface for LocaleSwitcher component | |
SelectSingleProps | interface | props | — | Single-select arm. value is T | null, selectionIndicator excludes
'checkbox' (a checkmark or no indicator), nullOption is available,
multiPlaceholder is not — there's never more than one selected label
to summarize. | |
SelectValue | type | helper | — | Primitive value types accepted by Select / Combobox options. Strings are the default; numbers and booleans cover form fields bound to numeric IDs or yes/no flags without forcing the consumer to convert back and forth at every call site. | |
NullOptionConfig | interface | helper | — | Configuration for an explicit "no value" option rendered at the top of the listbox.
Selecting it sets value to null and fires onValueChange(null).
Pass a string to use it as the label, or an object for additional control:
nullOption="No selection"
nullOption={{ label: 'Leave unassigned' }} |
06 Installation
Import
·
import { LocaleSwitcher } from '@urbicon-ui/blocks';