# Country Picker

Searchable country list with flags and dial codes that opens from a field or settings row, or sits inline. Picking a country flies its flag into the field. Use the built-in list or bring your own.

> Composed · Pro · Forms & Inputs — React Native, Expo Go compatible.

## Install

```bash
npx @lumioui/cli add pro/country-picker
```

## Import

```tsx
import { flagImageUrl, CountryFlag, currencyFlagCode, CountryList, CountryPicker } from "@/components/ui/country-picker/country-picker";
```

## Variants

- `esim` — eSIM destination: `npx @lumioui/cli add pro/country-picker-esim`
- `residence` — Onboarding residence: `npx @lumioui/cli add pro/country-picker-residence`
- `shipping` — Shipping country: `npx @lumioui/cli add pro/country-picker-shipping`

## Props

### CountryFlag

| Prop | Type | Notes |
| --- | --- | --- |
| `code?` | `string` | ISO 3166-1 alpha-2 code (`"GB"`, case-insensitive). flagcdn also  serves `"EU"` and the UK nations (`"GB-SCT"`). |
| `country?` | `Country` | Country record — shorthand for `code={country.code}`. |
| `size?` | `"sm" | "md" | "lg"` | Slot size — "sm" 20pt flag (chips, inline), "md" 24pt (fields, rows),  "lg" 28pt (hero field). |
| `className?` | `string` | — |

### CountryList

| Prop | Type | Notes |
| --- | --- | --- |
| `value?` | `string` | Controlled ISO code. Omit with `defaultValue` for uncontrolled use. |
| `defaultValue?` | `string` | Uncontrolled initial ISO code. |
| `onValueChange?` | `(code: string, country: Country) => void` | Fires with the picked ISO code. |
| `countries?` | `Country[]` | Country data. Defaults to the built-in ~48-country list. |
| `suggested?` | `string[]` | ISO codes pinned in a "Suggested" group above the full list (hidden  while searching). |
| `showDialCode?` | `boolean` | Show the dial code on each row. Default true. |
| `searchable?` | `boolean` | Show the search field. Default true. |
| `searchPlaceholder?` | `string` | Search field placeholder. Default "Search countries". |
| `grouped?` | `boolean` | Group rows into inset rounded cards (on a canvas). Default false —  plain rows, for use inside a sheet. |
| `scrollEnabled?` | `boolean` | Allow the list to scroll itself. Turn off when embedding in a parent  ScrollView. Default true. |
| `contentInsetBottom?` | `number` | Extra bottom padding inside the scroll content (safe-area, CTA bar). |
| `allLabel?` | `string` | Header label of the full list. Default "All countries". |
| `className?` | `string` | — |

### CountryPicker

| Prop | Type | Notes |
| --- | --- | --- |
| `value?` | `string` | Controlled ISO code. Omit with `defaultValue` for uncontrolled use. |
| `defaultValue?` | `string` | Uncontrolled initial ISO code. |
| `onValueChange?` | `(code: string, country: Country) => void` | Fires with the picked ISO code and its record. |
| `open?` | `boolean` | Controlled sheet state. Omit with `defaultOpen` for uncontrolled. |
| `defaultOpen?` | `boolean` | Uncontrolled initial sheet state. |
| `onOpenChange?` | `(open: boolean) => void` | Fires when the sheet opens or closes. |
| `countries?` | `Country[]` | Country data. Defaults to the built-in list. |
| `suggested?` | `string[]` | ISO codes pinned in the "Suggested" group. |
| `trigger?` | `"field" | "row" | "none"` | Trigger style: "field" form input, "row" settings row, "none" no  trigger (drive `open` yourself — PhoneInput does). Default "field". |
| `label?` | `string` | Field label above the trigger, or the row's left label. |
| `placeholder?` | `string` | Trigger text with nothing picked. Default "Select country". |
| `title?` | `string` | Sheet title. Default "Country or region". |
| `showDialCode?` | `boolean` | Show dial codes in rows (and on the field trigger). Default true on  rows, false on the trigger. |
| `searchPlaceholder?` | `string` | Search field placeholder. |
| `disabled?` | `boolean` | — |
| `className?` | `string` | — |

## Icons rendered

- `chevron-right` — /icons.html?i=chevron-right
- `globe` — /icons.html?i=globe
- `chevron-down` — /icons.html?i=chevron-down
- `x` — /icons.html?i=x

Source: https://lumioui.com/components/country-picker