Countries API - CountriesDB

How to Add a Country Dropdown to Your Website Form

Add country and state/province dropdowns to your form with the free CountriesDB widget. Paste the HTML snippet; you do not need to write backend code.

Back to Blog

How to Add a Country Dropdown to Your Website Form

Hard-coded country lists in forms get out of date. ISO codes change, regions get renamed, and state lists are easy to mess up. The CountriesDB widget fills your dropdowns from our maintained dataset. You add a small HTML snippet and sign up for a free account.

Who this is for

You want country fields (and maybe state or province) on:

  • Contact or lead forms
  • Checkout or shipping addresses
  • Sign-up flows

You do not need your own backend API for the basics. If you can paste HTML into a page, or use a Custom HTML block in WordPress or Webflow, you are fine.

What you need

  • A site on a domain you control (the free plan uses a domain allowlist)
  • Somewhere to paste HTML (theme, template, or page builder)
  • About ten minutes

Setup

1. Account and project

Sign up for free, open the dashboard, and create a project. The project holds your keys, allowed domains, and plan.

2. Public key

In the project, go to Credentials and create a credential. Copy the public key and put it in the widget script URL.

The private key is only for server-side checks. Do not paste it into your page HTML.

3. Allowed domain

Under Domains, add the host where the form lives (e.g. www.example.com). Subdomains of that host are allowed too. The widget will not run on other sites, which keeps usage under your plan.

Test on the real domain when you can. Local preview may behave differently from production.

4. Script and selects

Drop in the script plus two empty <select> tags. Swap YOUR_PUBLIC_KEY for the key from step 2. The full block is below.

5. Check it works

Publish, load the page on your allowed domain, and make sure both dropdowns fill. Change the country and confirm the region list updates.

Copy-paste example

<!-- CountriesDB widget: replace YOUR_PUBLIC_KEY -->
<script src="https://unpkg.com/@countriesdb/widget@latest/dist/index.js?public_key=YOUR_PUBLIC_KEY"></script>

<label for="country">Country</label>
<select id="country" class="country-selection" name="country">
  <option value="">Select country</option>
</select>

<label for="region">State / province</label>
<select id="region" class="subdivision-selection" name="state">
  <option value="">Select state or province</option>
</select>

More options and CSS classes are in the widget docs.

Country and region together

The second select uses ISO 3166-2 subdivisions for whatever country is picked. When the country changes, the widget reloads the region list.

See subdivision setup.

Geolocation

By default the widget may guess the visitor’s country. To turn that off, see disable geolocation.

FAQ

Do I need a developer?
Probably not if you can paste HTML yourself. Tricky themes might need a dev for five minutes, or ask us via the contact form on a paid plan.

Is there a free plan?
Yes: 1,000 requests per month and one widget domain. See pricing or the free plan post.

What about states and provinces?
Use both classes from the example: country-selection and subdivision-selection.

WordPress or Webflow?
Paste the snippet into a Custom HTML block or embed field. Platform-specific guides are listed below.

Is the public key secret?
It is fine in the browser (like a publishable key). Keep the private validation key on the server. See the Backend Validation API when you want to verify submissions there.

Why not copy a country list from a blog post?
Those lists go stale and rarely include regions. The widget uses the same data as our API.

Stuck?
On a paid plan you can request free setup via the contact form.

Links

More setup guides

We are publishing step-by-step guides for specific setups. Each links back to this page for the core snippet:

  • Country and state/province fields for address and checkout forms (coming soon)
  • Add a country dropdown to a WordPress contact form (coming soon)
  • Embed country selects in Webflow or Squarespace (coming soon)
  • Country dropdown in React in 5 minutes (coming soon)

Server-side validation

For production apps you should verify country and region codes on the server. Use the Backend Validation API with your private key. The widget is for the form; the API is for checking what people submit.

How to Add a Country Dropdown to Your Website Form | CountriesDB