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.
Installation
npx shadcn@latest add @minidev/country-select
MiniDev UI is in the shadcn registry directory, so the short form works with no setup. Older CLI versions can use the full URL: npx shadcn@latest add https://ui.minidev.pro/r/country-select.json
Usage
import { CountrySelect } from "@/components/ui/country-select"
export function Example() {
return (
<CountrySelect />
)
}
Exports CountrySelect countries
API reference
| Prop | Type | Default |
|---|---|---|
| valueControlled selection, an ISO 3166-1 alpha-2 code such as "US". Leave undefined for an uncontrolled select. | string | - |
| defaultValueInitial code for the uncontrolled select. | string | - |
| onValueChangeCalled with the picked country's upper-case code. | (code: string) => void | - |
| localeBCP 47 locale for the country names and their sort order, for example "de" or "ja". | string | "en" |
| priorityCodes pinned in a "Suggested" group above the rest, in this order. They are not repeated below. | string[] | [] |
| excludeCodes to leave out, for example countries you do not ship to. | string[] | [] |
| showFlagShow the emoji flag before each name. | boolean | true |
| placeholderTrigger text while nothing is selected. | string | "Select country" |
| searchPlaceholderPlaceholder of the search field inside the popup. | string | "Search countries…" |
| emptyTextShown when the search matches nothing. | string | "No country found" |
| priorityLabelHeading of the `priority` group. | string | "Suggested" |
| disabled | boolean | - |
| idId for the trigger, so a `<label htmlFor>` or FormField can name it. | string | - |
| nameSubmits the selected code under this name inside a `<form>`. | string | - |
| requiredRequires a selection before the form submits. | boolean | - |
| aria-labelAccessible name when there is no visible label. | string | - |
| classNameClasses for the trigger button (width defaults to w-64). | string | - |
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.
Keyboard interactions
| Key | Action |
|---|---|
| EnterorSpace | On the trigger, opens the list and moves focus to the search field. |
| ArrowDownorArrowUp | 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>withrole="combobox",aria-haspopup="dialog"andaria-expanded, plusaria-required="true"whenrequiredis set. Name it witharia-label, or pass the sameidtoFormField. - 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>withautocomplete="country"holds the code. Withrequired, submitting the form with no country blocks the submit and moves focus to the trigger.
Frequently asked questions
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.
Dependencies
npm
Built from
Examples
Billing country with suggestions
priority pins the countries most customers pick in a Suggested group; the value is the ISO code.
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.
In a plain form
name submits the code with the form; exclude drops places you cannot ship to, and showFlag={false} hides the flags.