LocaleSwitcher

Dropdown for switching the application's display language.

Variant

Size

Show Flag

Disabled

<LocaleSwitcher
  size="sm"
  variant="outlined"
/>

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
        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 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

6 props

Prop	Type	Default	Description
`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. Redeclared from SelectSingleProps so the inheritance is a documented contract rather than an accident of the Omit list.
`onLocaleChange`	`(locale: Locale) => void`	—	Called after the locale has been changed successfully.
`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.
`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.

05 Types

Local type definitions used by this component.

4 types

Only referenced

Name	Kind	Category	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';