Localization

The address elements and the checkout element ship with a built-in ISO-3166-1 alpha-2 country directory. Filter the rendered list, preselect a country, and reach the directory programmatically via overflow.locales.

Filter the country list

fields.country.supportedCountries on billingAddress and shippingAddress restricts which countries render in the country dropdown:

overflow.billingAddress({
  fields: {
    country: { supportedCountries: ['US', 'CA', 'GB'] },
  },
});

Pass an array of ISO-3166-1 alpha-2 codes. Omit the field entirely to render the full directory. The array must be non-empty (an empty array fails type-check so a typo can never accidentally hide every country).

Preselect a country

defaultCountry on billingAddress and shippingAddress seeds the country atom at mount:

overflow.shippingAddress({
  defaultCountry: 'CA',
  fields: { country: { supportedCountries: ['US', 'CA', 'GB'] } },
});

If the seed is missing from the directory or excluded by supportedCountries, the country atom falls back to the placeholder option and logs a single console warning.

`overflow.locales`

The overflow.locales object exposes the country directory programmatically. Use it when composing your own UI (chips, popovers, custom pickers) alongside the SDK elements.

Member	Returns
`getCountries()`	Frozen array of every country entry, alphabetical by `name`.
`getCountry(iso2)`	`Country \| undefined` lookup by ISO-3166-1 alpha-2 code.
`hasCountry(iso2)`	`boolean` membership test.
`filterCountries(iso2List?)`	The directory restricted to the requested codes. Omitting the argument returns the full list.
`getCountryFlagUrl(iso2, format?)`	Flag CDN URL. `format` is `'svg'` (default), `'webp'`, or `'png'`.
`resolveDefaultCountry(requested, supportedCountries?)`	Returns the resolved code or `''` when the seed misses the directory or filter. Logs a single warning per resolution.

overflow.locales.getCountry('US');
// { iso2: 'US', name: 'United States', languages: ['en-US'] }

overflow.locales.getCountryFlagUrl('US', 'webp');
// 'https://flagcdn.com/w80/us.webp'

overflow.locales is the only supported surface for the country directory. There is no separate static class or module export; access the helpers through an Overflow instance.

Country flag display

fields.country.flagDisplay opts the country atom into rendering the resolved country’s flag inside the combobox trigger and on each row of the open listbox:

type CountryFlagDisplay = {
  side?: 'start' | 'end'; // logical positioning, RTL-safe. Defaults to 'end'.
};

Set side: 'start' to render the flag before the country name.

Locale attribute

Every element accepts an optional locale?: string shared option. It is forwarded to the input’s lang DOM attribute for downstream consumers (screen readers, autofill matchers). The SDK itself renders labels in English today; broader label localization ships in a later release.

Get started

Elements

Options

Events

Theming

Guides

Filter the country list

Preselect a country

`overflow.locales`

Country flag display

Locale attribute

See also

​Filter the country list

​Preselect a country

​overflow.locales

​Country flag display

​Locale attribute

​See also

Filter the country list

Preselect a country

`overflow.locales`

Country flag display

Locale attribute

See also