Skip to content

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.

src/registry/ui/country-select.tsx/r/country-select.json

Installation

bash
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

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

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

Exports CountrySelect countries

API reference

CountrySelect props
PropTypeDefault
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.booleantrue
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"
disabledboolean-
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

Keyboard interactions
KeyAction
EnterorSpaceOn the trigger, opens the list and moves focus to the search field.
ArrowDownorArrowUpOn the trigger, also opens the list. In the search field, moves the highlight through the countries.
EnterIn 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.
EscapeCloses 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.
  • 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.

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

@base-ui/reactlucide-react

Built from

No other MiniDev files

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.

All form components