Country and region pickers

A ready-to-use, complete country list with real aliases, flags and codes — so a signup form stops shipping its own copy-pasted array.

The data shape

A flat list of countries, each carrying a canonical display name, an ISO 3166-1 alpha-2 and alpha-3 code, and a flag. Alpha-2 and alpha-3 codes compile in as aliases, so typing "US", "USA" or "United" all resolve to the same canonical item.

A worked example

{
  "displayValue": "United States",
  "value": "US",
  "metadata": {
    "alpha3": "USA",
    "flag": "🇺🇸",
    "numericCode": "840"
  },
  "aliases": [
    "US",
    "USA",
    "United States of America"
  ]
}

Fields

Every field this shape carries and what it means
Field	Type	Meaning
displayValue	string	The CLDR display name shown to the user.
value	string	The ISO 3166-1 alpha-2 code — what your form actually stores.
metadata.alpha3	string	The ISO 3166-1 alpha-3 code, for systems that key on three letters.
metadata.flag	string	The flag emoji, computed from the alpha-2 code.

Provenance

This shape ships as a real platform dataset in this build: 249 ISO 3166-1 entries, owned by the AutoSugges platform tenant (supabase/seed-countries.sql). Names come from Unicode CLDR through Node’s own Intl.DisplayNames — nothing downloaded or scraped. Codes are ISO 3166-1, which is factual reference data rather than a licensed corpus. Flags are computed from the alpha-2 code, so a flag can never disagree with the country next to it. The generator is scripts/generate-countries-dataset.mjs, and re-running it reproduces the file byte for byte.

Integration steps

Subscribe your tenant to the platform Countries list, or publish your own if you need a subset.
Mount <Autocomplete> with a publishable key scoped to that list.
Store item.value (the alpha-2 code) — it is what every other system already expects for a country field.

Code

import { Autocomplete } from '@autosugges/client/react';
import { createAutosuggesClient } from '@autosugges/client';

const client = createAutosuggesClient({
  baseUrl: 'https://your-runtime.example.com',
  publishableKey: 'pk_live_YOUR_KEY',
});

<Autocomplete
  source={client}
  label="Country"
  onSelect={(item) => setCountry(item.value)}
/>

The publishable key above is a public, browser-safe identifier — never a secret.