|
| 1 | +--- |
| 2 | +title: Locale Picker |
| 3 | +description: Region picker with locale-derived defaults — currency, date and number formats, and first day of week. Searchable, keyboard accessible, and RTL-aware. |
| 4 | +--- |
| 5 | + |
| 6 | +import { PreviewComponents } from "@/components/docs/preview-components"; |
| 7 | +import { LocalePickerDemo } from "@/components/docs/locale-picker-demo"; |
| 8 | +import { Tabs, Tab } from "fumadocs-ui/components/tabs"; |
| 9 | + |
| 10 | +<PreviewComponents registryName="locale-picker"> |
| 11 | + <LocalePickerDemo /> |
| 12 | +</PreviewComponents> |
| 13 | + |
| 14 | +## Installation |
| 15 | + |
| 16 | +<Tabs |
| 17 | + items={["shadcn", "Elements CLI"]} |
| 18 | + defaultValue="shadcn" |
| 19 | + className="bg-transparent border-none" |
| 20 | +> |
| 21 | + <Tab value="shadcn" className="border-none bg-transparent p-0 mt-3"> |
| 22 | + <Tabs items={["npx", "pnpm", "yarn", "bun"]} defaultValue="npx" groupId="installation-tabs"> |
| 23 | + <Tab value="npx">```bash npx shadcn@latest add @elements/locale-picker ```</Tab> |
| 24 | + <Tab value="pnpm">```bash pnpm dlx shadcn@latest add @elements/locale-picker ```</Tab> |
| 25 | + <Tab value="yarn">```bash yarn dlx shadcn@latest add @elements/locale-picker ```</Tab> |
| 26 | + <Tab value="bun">```bash bunx shadcn@latest add @elements/locale-picker ```</Tab> |
| 27 | + </Tabs> |
| 28 | + </Tab> |
| 29 | + <Tab value="Elements CLI" className="border-none bg-transparent p-0 mt-3"> |
| 30 | + <Tabs items={["npx", "pnpm", "yarn", "bun"]} defaultValue="npx" groupId="elements-cli-tabs"> |
| 31 | + <Tab value="npx">```bash npx @babelize/elements add locale-picker ```</Tab> |
| 32 | + <Tab value="pnpm">```bash pnpm dlx @babelize/elements add locale-picker ```</Tab> |
| 33 | + <Tab value="yarn">```bash yarn dlx @babelize/elements add locale-picker ```</Tab> |
| 34 | + <Tab value="bun">```bash bunx @babelize/elements add locale-picker ```</Tab> |
| 35 | + </Tabs> |
| 36 | + </Tab> |
| 37 | +</Tabs> |
| 38 | + |
| 39 | +## Usage |
| 40 | + |
| 41 | +```tsx |
| 42 | +"use client"; |
| 43 | + |
| 44 | +import { useState } from "react"; |
| 45 | +import { LocalePicker } from "@/components/ui/locale-picker"; |
| 46 | + |
| 47 | +export function SettingsRegion() { |
| 48 | + const [locale, setLocale] = useState("en-IN"); |
| 49 | + |
| 50 | + return ( |
| 51 | + <LocalePicker |
| 52 | + regions={["IN", "US", "GB", "DE", "JP"]} // ISO 3166-1 alpha-2 codes |
| 53 | + defaultValue="en-IN" // omit for uncontrolled, use value instead |
| 54 | + onValueChange={setLocale} // receives the full BCP 47 tag, e.g. "en-US" |
| 55 | + /> |
| 56 | + ); |
| 57 | +} |
| 58 | +``` |
| 59 | + |
| 60 | +## Props |
| 61 | + |
| 62 | +| Prop | Type | Required | Default | Description | |
| 63 | +| --------------- | -------------------------- | -------- | ------------------- | -------------------------------------------------------------- | |
| 64 | +| `regions` | `string[]` | Yes | — | Regions to choose from, ISO 3166-1 alpha-2 codes | |
| 65 | +| `value` | `string` | No | — | Selected locale (BCP 47) — pass this to control the component | |
| 66 | +| `defaultValue` | `string` | No | `en-<first region>` | Initial selected locale when uncontrolled | |
| 67 | +| `onValueChange` | `(locale: string) => void` | No | — | Callback when the region changes — receives the new BCP 47 tag | |
| 68 | +| `label` | `"native" \| "english"` | No | `"english"` | Region names in English, or localized to the selected locale | |
| 69 | +| `showFlags` | `boolean` | No | `true` | Show the region's flag emoji next to its name | |
| 70 | +| `maxHeight` | `number \| string` | No | `"15rem"` | Max height of the scrolling option list, before it scrolls | |
| 71 | +| `className` | `string` | No | — | Additional CSS classes | |
| 72 | + |
| 73 | +The selected value is a full BCP 47 tag: its **region** subtag is the picked |
| 74 | +region, and its **language** subtag survives region changes. Picking Germany |
| 75 | +from `en-IN` yields `en-DE`; picking it from `fr-JP` yields `fr-DE`. |
| 76 | + |
| 77 | +## Derived defaults |
| 78 | + |
| 79 | +The summary card derives everything from the selected locale through `Intl` — |
| 80 | +no data bundled beyond an ISO 4217 fallback table for the currency code: |
| 81 | + |
| 82 | +| Row | Source | |
| 83 | +| -------------- | -------------------------------------------------------------------------------- | |
| 84 | +| Currency | Region → ISO 4217 code, previewed with `Intl.NumberFormat` (`style: "currency"`) | |
| 85 | +| Date format | `Intl.DateTimeFormat` (`dateStyle: "medium"`) on a fixed sample date | |
| 86 | +| Number format | `Intl.NumberFormat` on a fixed sample amount | |
| 87 | +| Week starts on | `Intl.Locale#getWeekInfo()` where available, with a regional fallback | |
| 88 | + |
| 89 | +Regions without a currency mapping show an em dash rather than a guess. |
| 90 | + |
| 91 | +## Keyboard support |
| 92 | + |
| 93 | +The popup follows the WAI-ARIA combobox pattern: focus stays in the search |
| 94 | +field, which is exposed as a `role="combobox"`, and the highlighted option is |
| 95 | +announced through `aria-activedescendant`. |
| 96 | + |
| 97 | +| Key | Action | |
| 98 | +| -------------------------------- | ------------------------------------------------------------- | |
| 99 | +| `Enter`, `Space`, or click | Open the popup from the trigger | |
| 100 | +| `ArrowDown` / `ArrowUp` (closed) | Open with the first / last region highlighted | |
| 101 | +| `ArrowDown` / `ArrowUp` | Move the highlight, wrapping at both ends | |
| 102 | +| `Home` / `End` | Highlight the first / last region | |
| 103 | +| `Enter` | Select the highlighted region and return focus to the trigger | |
| 104 | +| `Escape` | Close the popup and return focus to the trigger | |
| 105 | +| Typing | Filter by name or code; the highlight restarts at the top | |
| 106 | + |
| 107 | +## Features |
| 108 | + |
| 109 | +- **Derived defaults** — currency, date format, number format, and first day of week, resolved live through `Intl` |
| 110 | +- **Dropdown with search** — filter regions by English name, localized name, or code |
| 111 | +- **RTL-aware** — flips direction for RTL locales (ar, he, fa, ur) via `dir` on the root |
| 112 | +- **Keyboard accessible** — arrow keys, Home / End, Enter, and Escape navigation |
| 113 | +- **ARIA labels** — `role="combobox"` search field with `aria-activedescendant`, plus `aria-expanded`, `aria-haspopup`, and `aria-selected` |
| 114 | +- **Dark mode** — built with Tailwind CSS, dark-mode compatible |
| 115 | +- **Controlled or uncontrolled** — `value` / `defaultValue` / `onValueChange` |
| 116 | + |
| 117 | +## Examples |
| 118 | + |
| 119 | +### Controlled |
| 120 | + |
| 121 | +```tsx |
| 122 | +"use client"; |
| 123 | + |
| 124 | +import { LocalePicker } from "@/components/ui/locale-picker"; |
| 125 | + |
| 126 | +export function SettingsRegion({ locale, setLocale }) { |
| 127 | + return ( |
| 128 | + <LocalePicker |
| 129 | + regions={["IN", "US", "GB", "DE", "JP"]} |
| 130 | + value={locale} |
| 131 | + onValueChange={setLocale} |
| 132 | + /> |
| 133 | + ); |
| 134 | +} |
| 135 | +``` |
| 136 | + |
| 137 | +### Native region names |
| 138 | + |
| 139 | +```tsx |
| 140 | +<LocalePicker regions={["IN", "US", "GB", "DE", "JP"]} defaultValue="de-DE" label="native" /> |
| 141 | +``` |
| 142 | + |
| 143 | +With `de-DE` selected, the trigger reads "Deutschland" and the options read |
| 144 | +"Vereinigte Staaten", "Vereinigtes Königreich", and so on. |
| 145 | + |
| 146 | +## Dependencies |
| 147 | + |
| 148 | +This component uses: |
| 149 | + |
| 150 | +- `clsx` and `tailwind-merge` (bundled as dependencies) |
| 151 | + |
| 152 | +Peer dependencies: |
| 153 | + |
| 154 | +- `react` >= 18 |
| 155 | +- `react-dom` >= 18 |
| 156 | +- `tailwindcss` >= 3 |
| 157 | + |
| 158 | +## Credits |
| 159 | + |
| 160 | +Created by [ujwalbajaj](https://github.com/ujwalbajaj). |
0 commit comments