# Country Select

> React country select with search, emoji flags and names localised by Intl.DisplayNames. Returns ISO codes, pins top countries and submits with forms.

- Kind: Component (Forms)
- Docs: https://ui.minidev.pro/docs/country-select
- Source (registry JSON with the full file): https://ui.minidev.pro/r/country-select.json
- License: MIT. One file, yours to edit after install.

## When to use

Use it for billing, shipping and sign-up forms. The value is an ISO 3166-1 alpha-2 code ("US", "DE"). Search matches the start of any word in the localised or English name, or the exact two-letter code, ignoring accents. Pin the countries most of your users pick with `priority`. Built on Base UI Combobox, styled like Combobox; use Combobox for any other long list and PhoneInput for phone numbers. The `countries(locale)` helper returns the same sorted list for your own fields, such as the country column in TaxFields.

## Installation

### shadcn CLI (copies the source into your project)

```bash
npx shadcn@latest add @minidev/country-select
```

Writes `components/ui/country-select.tsx` and installs its npm dependencies. Older CLI versions: `npx shadcn@latest add https://ui.minidev.pro/r/country-select.json`.

### npm package

```bash
npm i minidev-ui-kit @base-ui/react lucide-react
```

Add the tokens to your global stylesheet once:

```css
@import "tailwindcss";
@import "minidev-ui-kit/styles.css";
@source "../node_modules/minidev-ui-kit";
```

Next.js also needs `transpilePackages: ["minidev-ui-kit"]` in next.config.

## Import

After the shadcn install:

```tsx
import { CountrySelect, countries } from "@/components/ui/country-select"
```

From the npm package:

```tsx
import { CountrySelect } from "minidev-ui-kit/ui/country-select"
```

## Usage

```tsx
import { CountrySelect } from "@/components/ui/country-select"

export function Example() {
  return (
    <CountrySelect />
  )
}
```

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `value` | `string` | - | no | Controlled selection, an ISO 3166-1 alpha-2 code such as "US". Leave undefined for an uncontrolled select. |
| `defaultValue` | `string` | - | no | Initial code for the uncontrolled select. |
| `onValueChange` | `(code: string) => void` | - | no | Called with the picked country's upper-case code. |
| `locale` | `string` | `"en"` | no | BCP 47 locale for the country names and their sort order, for example "de" or "ja". |
| `priority` | `string[]` | `[]` | no | Codes pinned in a "Suggested" group above the rest, in this order. They are not repeated below. |
| `exclude` | `string[]` | `[]` | no | Codes to leave out, for example countries you do not ship to. |
| `showFlag` | `boolean` | `true` | no | Show the emoji flag before each name. |
| `placeholder` | `string` | `"Select country"` | no | Trigger text while nothing is selected. |
| `searchPlaceholder` | `string` | `"Search countries…"` | no | Placeholder of the search field inside the popup. |
| `emptyText` | `string` | `"No country found"` | no | Shown when the search matches nothing. |
| `priorityLabel` | `string` | `"Suggested"` | no | Heading of the `priority` group. |
| `disabled` | `boolean` | - | no |  |
| `id` | `string` | - | no | Id for the trigger, so a `<label htmlFor>` or FormField can name it. |
| `name` | `string` | - | no | Submits the selected code under this name inside a `<form>`. |
| `required` | `boolean` | - | no | Requires a selection before the form submits. |
| `aria-label` | `string` | - | no | Accessible name when there is no visible label. |
| `className` | `string` | - | no | Classes for the trigger button (width defaults to w-64). |

## Examples

### Billing country with suggestions

priority pins the countries most customers pick in a Suggested group; the value is the ISO code.

```tsx
function BillingCountry() {
  const [country, setCountry] = React.useState("GB")
  return (
    <div className="flex w-64 flex-col gap-3">
      <FormField id="billing-country" label="Billing country" description="Used for VAT on Lumen invoices.">
        <CountrySelect id="billing-country" value={country} onValueChange={setCountry} priority={["US", "GB", "CA", "DE"]} />
      </FormField>
      <p className="text-xs text-fg-muted">
        Stored as <code className="font-mono text-fg">{country}</code>
      </p>
    </div>
  )
}
```

### Names in the user's language

locale renames and re-sorts every country through Intl.DisplayNames. Search still matches the English name and the code.

```tsx
function LocalisedNames() {
  const [locale, setLocale] = React.useState("de")
  return (
    <div className="flex w-64 flex-col gap-3">
      <SegmentedControl
        aria-label="Language"
        size="sm"
        options={[{ value: "en", label: "English" }, { value: "de", label: "Deutsch" }, { value: "ja", label: "日本語" }]}
        value={locale}
        onChange={setLocale}
      />
      <CountrySelect aria-label="Country" locale={locale} defaultValue="CH" />
      <p className="text-xs text-fg-muted">
        The first five names in this locale: {countries(locale).slice(0, 5).map((c) => c.name).join(", ")}
      </p>
    </div>
  )
}
```

### In a plain form

name submits the code with the form; exclude drops places you cannot ship to, and showFlag={false} hides the flags.

```tsx
<form
  onSubmit={(e) => {
    e.preventDefault()
    console.log(new FormData(e.currentTarget).get("ship_to")) // "FR"
  }}
>
  <FormField id="ship-to" label="Ship to" required>
    <CountrySelect id="ship-to" name="ship_to" required exclude={["AQ", "BV", "HM"]} showFlag={false} />
  </FormField>
  <Button type="submit" size="sm">Continue</Button>
</form>
```

## Keyboard interactions

| Key | Action |
| --- | --- |
| `Enter` or `Space` | On the trigger, opens the list and moves focus to the search field. |
| `ArrowDown` or `ArrowUp` | On the trigger, also opens the list. In the search field, moves the highlight through the countries. |
| `Enter` | In the search field, picks the highlighted country, closes the list and returns focus to the trigger. The first match is highlighted as you type, so "ger" then Enter picks Germany. |
| `Escape` | Closes the list without changing the value and returns focus to the trigger. |

## Accessibility

- The trigger is a `<button>` with `role="combobox"`, `aria-haspopup="dialog"` and `aria-expanded`, plus `aria-required="true"` when `required` is set. Name it with `aria-label`, or pass the same `id` to [`FormField`](https://ui.minidev.pro/docs/form-field).
- Flags and the code column are `aria-hidden`, so each option is announced by its country name only. The search field is labelled "Search countries".
- With `name`, a visually hidden `<input>` with `autocomplete="country"` holds the code. With `required`, submitting the form with no country blocks the submit and moves focus to the trigger.

## FAQ

### How do I use CountrySelect in a form or with React Hook Form?

In a plain `<form>`, pass `name`: a hidden input submits the code, so `FormData` gives `ship_to=FR`, and `required` stops the submit while nothing is picked. With React Hook Form, use a `Controller`: `render={({ field }) => <CountrySelect value={field.value} onValueChange={field.onChange} aria-label="Country" />}`.

### How do I show country names in the user's language?

Pass `locale`, for example `locale="de"` for "Deutschland" and "Schweiz". Names come from the browser's `Intl.DisplayNames` and are sorted with `Intl.Collator` for that locale, so no translation files ship. Search still matches the English name and the code, so "germany" and "de" both find Deutschland.

### Why do the flags show as two letters such as "US" on Windows?

Each flag is an emoji built from the code's two regional indicator letters. Windows has no flag emoji, so Chrome and Edge there draw the letters instead. If that matters for your users, pass `showFlag={false}`; the name and the code still show.

### Can I reuse the country list in my own fields or tables?

Yes. `countries("fr")` is exported from the same file and returns `{ code, name, flag }` for all 249 ISO 3166-1 codes, sorted by name in that locale. Use it to print a stored code as a name, or for the country column next to [`TaxFields`](https://ui.minidev.pro/docs/tax-fields).

## Rules for generating code

- Use semantic tokens only (bg, surface, sunken, border, fg, fg-muted, fg-subtle, ink, accent, success, warning, danger). Never raw hex or palette steps like blue-500.
- Shadows only from the set: shadow-xs, shadow-sm, shadow-raised, shadow-md, shadow-lg, shadow-overlay.
- Numbers use tabular-nums. Dark mode is the `dark` class on <html>; components never branch on theme.

## Dependencies

- npm: `@base-ui/react`, `lucide-react`

## Related

- [Combobox](https://ui.minidev.pro/docs/combobox/md): Shadcn style combobox: a popover select with a filter input, check mark on the chosen item and an empty message. Built on Base UI popover for React.
- [Phone Input](https://ui.minidev.pro/docs/phone-input/md): A telephone number field with type tel, a numeric keypad on mobile, tel autocomplete, tabular digits and a default aria label. Styled like the React base input.
- [Tax Fields](https://ui.minidev.pro/docs/tax-fields/md): Checkout tax fields with country and a monospace VAT or EIN tax ID input in a two-column grid. Drop it into billing address forms for business customers.
- [Autocomplete](https://ui.minidev.pro/docs/autocomplete/md): Text input that filters string options as you type, using ARIA combobox and listbox roles. Works controlled or uncontrolled and lists up to eight matches.
- [Calendar Month](https://ui.minidev.pro/docs/calendar-month/md): Month calendar grid with weekday headers and clickable day cells that highlight the selected date. A simple Tailwind base for date views and schedulers.
- [Character Count](https://ui.minidev.pro/docs/character-count/md): Live React character counter that shows the current count against a limit and turns red when it goes over. Announces changes politely to screen readers.

---

All 557 components: https://ui.minidev.pro/llms.txt (full text: https://ui.minidev.pro/llms-full.txt).
