# React Native Country Picker

> React Native country picker with flags and dialing codes: 250 countries, search by name in any language, ISO code or +dial code, preferred countries on top, localized names, single or multiple. Pure JS, works in Expo Go.

# CountryPicker

`CountryPicker` is a React Native form field for choosing a country: about 250 countries with flag emojis and international dialing codes, searchable by English or native name, ISO code or `+` dialing code. Country names follow the device's language. It's a [`Select`](./select) with the country list built in, so it takes the same props: a bottom sheet on phones, a dropdown on the web, multiple selection, a clear button and the [iOS, Material or web design](../guides/designs).

No images or data files to add: flags are emoji, and the list is about 11 KB, parsed on first use.

```tsx
import { CountryPicker } from 'patine-ui';
```

```tsx live
import { useState } from 'react';
import { CountryPicker } from 'patine-ui';
import type { CountryCode } from 'patine-ui';

export default function Example() {
  const [country, setCountry] = useState<CountryCode | null>('IL');
  return <CountryPicker label="Country" value={country} onValueChange={setCountry} />;
}
```

Try searching `deutschland`, `usa`, `+44` or `JP`. The value is the ISO 3166-1 alpha-2 code, such as `'IL'`. [`getCountry`](#utilities) turns it into the name, flag and dialing code.

## Example: where to ship

A checkout's delivery step: the countries the shop ships to most come first, and the delivery time, price and customs note follow the country you pick.

```tsx live
import { useState } from 'react';
import { Alert, Box, CountryPicker, HStack, Text, VStack, getCountry } from 'patine-ui';
import type { CountryCode } from 'patine-ui';

const EU = ['AT', 'BE', 'DE', 'DK', 'ES', 'FI', 'FR', 'IE', 'IT', 'NL', 'PL', 'PT', 'SE'];
const quote = (code: string) =>
  code === 'NL'
    ? { days: '1–2 business days', price: 'Free' }
    : EU.includes(code)
      ? { days: '2–4 business days', price: '€6.90' }
      : { days: '5–9 business days', price: '€19.00', customs: true };

export default function Example() {
  const [country, setCountry] = useState<CountryCode | null>('NL');
  const info = country ? quote(country) : null;
  return (
    <VStack gap="md" style={{ width: '100%', maxWidth: 420 }}>
      <CountryPicker label="Ship to" preferred={['NL', 'BE', 'DE', 'FR']} value={country} onValueChange={setCountry} />
      {country && info ? (
        <Box border radius="md" padding="md" gap="xs">
          <HStack justify="space-between">
            <Text weight="medium">Standard to {getCountry(country)?.name}</Text>
            <Text weight="semibold">{info.price}</Text>
          </HStack>
          <Text size="sm" color="textSecondary">Arrives in {info.days}</Text>
        </Box>
      ) : null}
      {info?.customs ? (
        <Alert variant="warning" title="Customs may apply" description="Orders outside the EU can be charged import duty on arrival, paid to the carrier." />
      ) : null}
    </VStack>
  );
}
```

## Preferred countries and dialing codes

`preferred` pins countries to the top under their own header, in the order you give. `showDialCode` adds each country's code under its name.

```tsx live
import { useState } from 'react';
import { CountryPicker } from 'patine-ui';
import type { CountryCode } from 'patine-ui';

export default function Example() {
  const [country, setCountry] = useState<CountryCode | null>(null);
  return (
    <CountryPicker
      label="Phone country"
      preferred={['US', 'GB', 'CA']}
      showDialCode
      value={country}
      onValueChange={setCountry}
    />
  );
}
```

## Phone numbers

For a phone number, use [`PhoneField`](./phone-field): this country list behind a flag and calling code button, with the number formatted as it's typed and stored in E.164.

## Several countries

`multiple` turns the field into chips, as with `Select`. `maxSelected` caps the count.

```tsx live
import { useState } from 'react';
import { CountryPicker } from 'patine-ui';
import type { CountryCode } from 'patine-ui';

export default function Example() {
  const [visited, setVisited] = useState<CountryCode[]>(['FR', 'JP']);
  return <CountryPicker label="Countries you've visited" multiple value={visited} onValueChange={setVisited} />;
}
```

## A subset of countries

`countries` limits the list to the ones you ship to, and `exclude` drops some. Both take ISO codes, and the list is always sorted by name.

```tsx live
import { useState } from 'react';
import { CountryPicker } from 'patine-ui';
import type { CountryCode } from 'patine-ui';

const EU_SHIPPING: CountryCode[] = ['AT', 'BE', 'DE', 'ES', 'FR', 'IE', 'IT', 'NL', 'PT'];

export default function Example() {
  const [country, setCountry] = useState<CountryCode | null>(null);
  return <CountryPicker label="Ship to" countries={EU_SHIPPING} value={country} onValueChange={setCountry} />;
}
```

Pass `countries`, `exclude` and `preferred` from a constant, not a new array on every render, so the list is built once.

To pick a state and a city under the country, see the [dependent selects example](/examples/dependent-selects).

## Country names in other languages

Names come from `Intl.DisplayNames` in `locale`, the device locale by default. Search still matches the English and native names in every language. Where the JavaScript engine has no `Intl.DisplayNames`, names fall back to English.

```tsx live
import { useState } from 'react';
import { CountryPicker } from 'patine-ui';
import type { CountryCode } from 'patine-ui';

export default function Example() {
  const [country, setCountry] = useState<CountryCode | null>('DE');
  return (
    <CountryPicker
      label="Land"
      placeholder="Land auswählen"
      searchPlaceholder="Suchen"
      locale="de"
      value={country}
      onValueChange={setCountry}
    />
  );
}
```

## Utilities

The country data comes from [countries-list](https://github.com/annexare/Countries) (MIT) and is exported for your own UIs, such as a flag next to a username or a dialing code in a form.

| Export | Description |
| --- | --- |
| `getCountry(code)` | `{ code, name, nativeName?, dialCode, flag, keywords }` for an ISO code in any case, or `undefined` |
| `getAllCountries()` | Every `Country`, sorted by code |
| `getCountryFlag(code)` | The flag emoji for an ISO code: `'jp'` → 🇯🇵 |

```ts
getCountry('il'); // { code: 'IL', name: 'Israel', nativeName: 'יִשְׂרָאֵל', dialCode: '+972', flag: '🇮🇱', keywords: [] }
```

## Props

Every [`Select` prop](./select#api) works, apart from the server search ones (`options`, `loadOptions`, `onSearchChange`, `loading` and the rest): the list is built in. `value` is a `CountryCode`, or `CountryCode[]` with `multiple`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `countries` | `CountryCode[]` | all | Only these countries. |
| `exclude` | `CountryCode[]` | — | Leave these out. |
| `preferred` | `CountryCode[]` | — | Shown first, in this order, under their own header. |
| `preferredLabel` | `string` | `'Suggested'` | Header above `preferred`. |
| `allCountriesLabel` | `string` | `'All countries'` | Header above the rest when `preferred` is set. |
| `showDialCode` | `boolean` | `false` | Show each country's dialing code under its name. |
| `locale` | `string` | device locale | Language of the country names. |
| `placeholder` | `string` | `'Select a country'` | Shown while nothing is selected. |
| `searchPlaceholder` | `string` | `'Search countries'` | Search field placeholder. |
| `sheet` | `Partial<SheetChromeProps>` | `sheetProps.height: 0.8` | Sheet options. The sheet opens at 80% of the screen so it doesn't jump as search narrows the list. |

### Types

```ts
type CountryCode = 'AD' | 'AE' | 'AF' | … ; // ISO 3166-1 alpha-2

interface Country {
  code: CountryCode;
  name: string; // English
  nativeName?: string; // in the country's own language, when different
  dialCode: string; // '+972'
  flag: string; // '🇮🇱'
  keywords: string[]; // aliases ('USA') and other dialing codes
}
```

## Related

- [PhoneField](./phone-field): this country list behind a phone number field
- [Select](./select): the field it's built on, with every prop
- [Country and phone code example](/examples/country-select)
- [Dependent selects example](/examples/dependent-selects): a state and a city under the country
