Country Select

"use client"

import * as React from "react"

The CountrySelect component picks one country from a searchable list. Use it for country of residence, a transfer destination or a billing address. Put the countries people pick most in a popular group on top, and keep unsupported countries listed but not selectable so people know why they cannot pick them. Pick it over a plain Select when the list is long enough to need search, and use PhoneField instead when you collect a phone number.

Installation#

pnpmnpmyarnbun
pnpm dlx shadcn@latest add @dots/country-select
Copy

Usage#

Copyimport { CountrySelect, type Country } from "@/components/ui/country-select"

Copyconst countries: Country[] = [
  { code: "CA", name: "Canada", dialCode: "+1" },
  { code: "GB", name: "United Kingdom", dialCode: "+44" },
  { code: "US", name: "United States", dialCode: "+1" },
]
 
<CountrySelect
  label="Country of residence"
  countries={countries}
  defaultValue="US"
/>

Composition#

CountrySelect builds the whole picker. Use the parts on their own to put the list in a sheet or page:

CopyCountrySelect
├── Label
├── SelectTrigger
│   └── CountryFlag + name or calling code
├── description (Text slot="description")
├── FieldError
└── Autocomplete
    └── SelectPopover
        ├── SelectInput (search)
        └── CountryList
            └── CountryListItem
                └── CountryFlag

Features#

• Search that matches the name, the calling code and the ISO code, ignoring accents and case
• An optional popular group on top; those countries are not repeated below
• Unavailable countries shown with a marker but not selectable
• A trigger that shows the name or the calling code
• Monochrome flags when you pass them, a round code chip when you do not
• Label, description and error message, with form name and validation from React Aria Select
• CountryList exported on its own for sheets and full-page pickers

Popular and unavailable#

Pass country codes to popular to list them first, for example from recent transfers or the person's location. Rename the group with popularLabel. Mark countries you do not support yet with isUnavailable.

"use client"

import {

Calling codes#

Set display="dial-code" to show the calling code on the trigger, and showDialCode to show codes in the list. Use size="sm" for a compact pill.

"use client"

import {

Invalid#

Set isInvalid and an errorMessage, or use isRequired with form validation.

"use client"

import {

Disabled#

Set isDisabled when the country can no longer be changed, and say why in the description.

"use client"

import {

List on its own#

CountryList is the same list without the trigger and popover. Wrap it in React Aria Autocomplete with a SearchField to build a picker in a sheet or on its own page.

"use client"

import * as React from "react"

Copyconst { contains } = useFilter({ sensitivity: "base" })
 
<Autocomplete filter={contains}>
  <SearchField aria-label="Search countries">
    <Input placeholder="Search countries" />
  </SearchField>
  <CountryList
    aria-label="Country of residence"
    countries={countries}
    selectionMode="single"
    selectedKeys={[country]}
    onSelectionChange={onSelectionChange}
  />
</Autocomplete>

Accessibility#

CountrySelect is built on React Aria Select and Autocomplete. The trigger, list and search field get their roles, keyboard navigation, typeahead and focus management from React Aria, and the description and error are linked to the field.

• Pass a visible label. Without one, pass aria-label, for example "Country code" next to a phone number.
• The search field is named by searchLabel. Change it when you translate the interface.
• Flags are decorative and hidden from screen readers; the name or code always sits next to them.
• With display="dial-code" the country name is still read before the calling code.
• Unavailable countries are disabled options, and the unavailable marker is read after the name.
• Give a standalone CountryList an aria-label and its search field an aria-label.

API Reference#

CountrySelect#

Accepts React Aria Select props such as isDisabled, isInvalid, isRequired, name and aria-label, except items, selectionMode and the selection props it replaces.

Country#

The shape of each entry in countries.

CountryList#

The list on its own. Accepts React Aria ListBox props such as aria-label, selectionMode, selectedKeys and onSelectionChange, except items, children and renderEmptyState.

CountryListItem#

One country row. Accepts SelectItem props except id, children and textValue, which come from the country.

CountryFlag#

The round mark next to a country: its flag, or its code when there is no flag. Decorative. Accepts Avatar props except children and size.