CountrySelect
country-selectSearches and selects countries with codes, flags, and optional calling prefixes.
Usage
Basic usage
Single-select the country/region, and the search will match all fields of Chinese/English/code/area code.
<CountrySelect defaultValue="CN" className="w-72" />Show area code
showDialCode Fill in the international area code on the right side of the drop-down line.
<CountrySelect defaultValue="US" showDialCode className="w-72" />Multiple choice (chips)
multiple has been selected to be echoed as chips, and you can continue to search and add.
<CountrySelect multiple defaultValue={["CN", "US", "JP"]} className="w-80" />Size
size supports sm / md / lg.
<>
<CountrySelect size="sm" defaultValue="GB" className="w-72" />
<CountrySelect size="lg" defaultValue="FR" className="w-72" />
</>Disabled / Invalid state
disabled blocks interaction; invalid trigger becomes danger stroke.
<>
<CountrySelect disabled defaultValue="FR" className="w-72" />
<CountrySelect invalid className="w-72" />
</>When to use
Use CountrySelect to choose one or more countries or regions from 250 built-in entries with flag emoji, Chinese and English names, and dialing codes. Search accepts either language, ISO codes, and dialing codes. Use Combobox for a custom flat list or RegionCascader for Chinese provinces and cities.
Import
import { CountrySelect, getCountry, flagEmoji, countrySearchText, filterCountries, countries } from "@hulianui/ui"Props
| Name | Type | Default | Description |
|---|---|---|---|
| value | string | string[] | - | Controlled value: single selection is ISO2 code string; multiple selection is code array |
| defaultValue | string | string[] | - | uncontrolled initial value |
| multiple | boolean | false | Multiple selection (chips) |
| showEnglish | boolean | true | Whether to display the English name in the option line |
| showDialCode | boolean | false | Whether the item line displays the international area code |
| placeholder | string | "\u9009\u62e9\u56fd\u5bb6/\u5730\u533a" | Trigger placeholder; the built-in Chinese copy means “Select a country or region.” |
| searchPlaceholder | string | "\u641c\u7d22\u56fd\u5bb6 / \u533a\u53f7\u2026" | Search placeholder; the built-in Chinese copy means “Search country or dialing code…”. |
| size | "sm" | "md" | "lg" | "md" | Trigger size |
| disabled | boolean | false | Disable |
| invalid | boolean | false | Invalid state |
| className | string | - | Additional class name for the trigger. |
Events
| Event | Type | Description |
|---|---|---|
| onChange | (next: string | string[]) => void | Select change callback; single selection returns string, multiple selection returns string[] |
Usage guidelines
valueandonChangeusestringin single-select mode andstring[]in multi-select mode. The callback exposes the union type, so narrow it frommultipleor with anastype assertion before treating it as an array.- Stored values are ISO 3166-1 alpha-2 codes such as
"CN", not display names. Resolve display data withgetCountry(code). - Native attributes that are not listed in Props (
aria-*,data-*,id,title, …) land on the trigger (the input inside the chips shell in multiple mode) rather than on the outer container, because that is the element which takes focus and is announced. Thearia-requiredinjected by<Field required>travels the same way (#293).
Related
SecretField · Combobox · Listbox · Mentions · InputOTP · Rating
Playground
<CountrySelect value={code} onChange={setCode} showDialCode />
{/* Multiple selection */}
<CountrySelect multiple value={codes} onChange={setCodes} />