Country select

Put it in a Field to give it a label, helper, and error. Without a Field, set aria-label. You don't write any options.

Anatomy

Countries and names

• The list covers all 249 ISO 3166-1 countries and territories, plus Kosovo (XK).
• Names come from the browser in the page's language (lang on <html>), or the browser's language when it isn't set. locale sets the language for one field; the list re-sorts for it.
• The value is the upper-case alpha-2 code, such as GB or US. A lower-case value is converted. Store and submit the code, not the name.
• Flags load the first time one is shown, from the library's own files. Until then, their space is kept empty, so nothing shifts.

Filtering

• Type part of a name, in any case and anywhere in the name: "kingdom" finds "United Kingdom".
• Accents don't matter: "curacao" finds "Curaçao".
• The two-letter code works too: "gb" finds the United Kingdom.
• Nothing is chosen until people choose an option. Leaving the field restores the chosen country. People can't add a country that isn't in the list.

Dial codes

dial-code adds the calling code to each name: "Netherlands (+31)". Typing digits, such as "44", then finds countries by code. Territories with no calling code show none.

Compact

compact shrinks the field to the flag and the calling code, to sit beside a number field. Use it with dial-code. The clear button is hidden, and the menu stays wide enough for full names. The field fits about five characters, so a typed name scrolls inside it; read the matches in the menu. Focusing the field selects the code, so typing replaces it.

Name a compact field with aria-label: a visible label above it would name the whole row. bare also removes the field's border, background, focus ring, and chevron, for use inside another field's box. Phone input does all this for you.

Sizes

States

The states are Combobox's. Hover doesn't change the field; keyboard focus colors and thickens its border.

• disabled: can't be focused or opened, and isn't submitted.
• readonly: shows the country and submits it, but can't be edited or opened. The flag stays; the clear button and chevron are hidden.
• Error: set error on the Field.

When to use

• Use a country select whenever people pick a country: sign-up, checkout, address, billing.
• Use a Phone input for phone numbers. It includes the country code picker.
• Use a Combobox with your own options for other long lists, such as currencies or time zones.

Content

• Label: "Country", or what the country is for: "Country of residence", "Billing country". Sentence case, no colon.
• Error: say how to fix it: "Select your country of residence".

More in Errors.

Do / Don't

Related

• Combobox: the same field for your own long lists.
• Phone input: a phone number field with a compact country select.
• Field: the label, helper, and error around it.
• Select family: how these compare.

API

Attributes

<option> children are ignored: the list is built in.

Events

change fires when someone chooses a country or clears the field. It doesn't fire while they type, or when you set value in code.

In a form, the code submits under name, and a form reset restores the starting value.

CSS

• ::part(field): the field.
• ::part(listbox): the menu.

Tokens

Everything else uses Combobox's tokens.

The flag's colors are its own.

Accessibility

Built in:

• Everything in Combobox: one Tab stop, the match count announced as people type, focus kept in the field.
• Flags are hidden from screen readers. The country name is the accessible name of each option and of the field.

Your part:

• Give it a name: a Field label, or aria-label when it is compact.
• If you set locale, use a real language tag, such as fr or pt-BR.

The keyboard is Combobox's.

Contrast limits

• Field border: 1.33:1 in light and 2.00:1 in dark, under the 3:1 minimum; 4.22:1 in high contrast. Always show a label.