country-regions / country-region-selector

Dynamic country and region dropdowns for your forms.

Country-Region-Selector

A feature you often need in forms is a connected country and region dropdown, where the region field gets automatically updated when the user selects a country. It's very easy to code this of course, but it's a pain having to track down all the raw country-region data.

This script does all the legwork for you. It lets you add this feature to your form without having to write any code or spend mind-numbing hours on Wikipedia downloading and formatting the data. I did that. It wasn't pretty.

Pick your version:

• standalone script (no dependencies, just plain JS)
• jQuery-dependent version
• React component (separate repo).

The reason the files are so large (60K or more) is that they contain all the country and region strings. If you know you're only going to need a small subset of all countries, you may want to generate a custom build containing only that info. That will substantially reduce the file size. See the Custom Builds section at the bottom of this page for more info.

Features

• Lets you customize the default "Please select" field for each country/region with whatever language you want.
• Lets you specify a default value for each field.
• Lets you customize the appearance and value of the country field ("Canada" or "CA") - they can be different, if desired (e.g. 2 char code for saving to database; full name for displaying purposes).
• Lets you have as many country-region-mapped fields as you need in your page.
• The standalone version has no dependencies on other any libs (jQuery etc) and you can include the JS file anywhere you want (head/foot).
• Works with dynamically inserted DOM content.

Example

Check out the following page for an example of the various ways it can be configured and used. http://country-regions.github.io/country-region-selector/

Who maintains the list?

Me, you - everyone! If you spot anything wonky for a particular country - out of date, incorrect or missing regions, a pull request is very welcome. As of 0.3.0 the source data is found in a separate repo so it can be used by anyone: https://github.com/country-regions/country-region-data

How to Use

It's very easy.

1. Include the crs.min.js file in your webpage.
2. Add two <select> fields in the appropriate locations in your form.
3. Give the country field a class of crs-country.
4. Now we need to map each country field to its corresponding region field so the script knows what to update when a country is selected. Add an attribute to the country dropdown: data-region-id="ABC" where ABC is any string. Now Give the region dropdown an id of "ABC".
5. That's it! You're done.

But here's a few more tips for further configuration.

Default "Please select" Values

If you want to add default "Please select" options to either the country or region fields, just go ahead and add it directly in the markup. The script will append the country and region <option> fields - not overwrite them.

Adding default values for each field

If your form is used for people returning to it (e.g. "Edit Contact Info" or whatever), you'll need the country and region fields to be prefilled with the appropriate value on page load. To do that, just add a data-default-value="" attribute to each element containing the country / region value last saved. Note: the region value will only ever be populated if the country field is as well.

List of data-* attributes

This lists all the available data-* attributes that you can add to the country/region fields to customize the appearance and behaviour.

country fields

• data-region-id - required. This should contain the ID of the region field that it's being mapped to.
• data-default-option - optional. Default: "Select country". This determines the default, blank option display value.
• data-show-default-option - optional. True by default. This shows the "Select Country" default option (or whatever string you've set). Set it to "false" to turn it off.
• data-default-value - optional. The default selected value in the country dropdown (e.g. "Canada")
• data-value="shortcode" - optional. The default behaviour is for the value attributes of the country dropdown options to be the full country name. If you'd rather use a 2-char code, add this attribute. Note: the 2-char codes are mostly ISO standard 2-char country codes, but not all. They are, however, unique across the dataset. N.B. This setting used to be named 2-char, but was renamed for consistency with the new region option. For backward compatibility 2-char still works.
• data-whitelist - optional. A comma-delimited lists of country shortcodes that you want to appear in the dropdown. Anything not specified here will be omitted. Take look here for the country list: https://github.com/country-regions/country-region-data/blob/master/data.json - you'll want to use the second index of the array, e.g. "AF" for Afghanistan, or "DE" for Germany. Note: if you're worried about file sizes, you can also choose to generate a custom build of the script that only contains those countries you need. This would replace the need for this option. See the Custom Builds section below.
• data-blacklist - optional. Like the data-whitelist, only a blacklist! This lets you display all countries except the countries that you specify here. If you supply both white and blacklists, the blacklist setting is ignored. Just enter a comma delimited list of country shortcodes. Again, take look here for the country list + their shortcodes: https://github.com/country-regions/country-region-data/blob/master/data.json
• data-preferred - optional. Lets you target specific countries to get listed at the top of the country dropdown. This should contain a comma-delimited list of the country short codes you want moved, e.g. data-preferred="CA,US,MX".
• data-preferred-delim - optional. If you use the data-preferred option, you may want a line separating them from the other countries in the list. This setting lets you provide a string that will act as separator.

region fields

• data-blank-option - before the user selects a country, there's a single displayed which by default is the "-" character.
• data-default-option - optional. Default: "Select region". This determines the default, blank option display value that shows up after a user has selected a country.
• data-show-default-option - optional. True by default. This shows the "Select Region" default option (or whatever string you've set). Set it to "false" to turn it off.
• data-default-value - optional. The default selected value in the region dropdown (e.g. "British Columbia", or "BC" if using the data-value="shortcode" option)
• data-value="shortcode" - optional. By default, region dropdowns will display the full region name. This option lets you show a 2-code abbreviation instead. Please note that all the abbreviations have not yet been added. See this thread that explains how the structure works. If a region field is set to 2-char and a user user selects a country that doesn't have a region, it will show the full country name instead.

Working with dynamic HTML

In case your page is being generated on the fly, you'll need to manually re-initialize the script after the new DOM content is inserted.

AMD example

With AMD (requireJS), just include the lib as you usually would. If you inspect the return value, you'll see it has a single init function. Just call that method whenever you need it (i.e. after new DOM content is inserted into your page).

define(['/path/to/crs.min'], function(crs) {
    // when you're ready... 
    crs.init();
});

Plain vanilla JS example

If you're just including the crs.min.js in a <script> tag in your page, it'll automatically expose a crs property on your global window object. Then you can call window.crs.init() whenever your new page content has been dynamically inserted. That will initialize the newly inserted country-region fields.

Custom Builds

As of 0.2.4, you can generate a custom version of the library that contains only those countries you need. This can substantially reduce the overall file size, if that's important to you.

To do this, follow the instructions in the following section to get your dev environment set up, then instead of the last step, run: grunt customBuild --countries="Canada,United States"

Just add whatever countries you want to include. To find the exact country names, take a look at the data in https://github.com/country-regions/country-region-data/blob/master/data.json.

This will generate new files in the /dist folder that you can use.

If the country name you're targeting contains a comma, just escape with with a single backslash, like so: grunt customBuild --countries="Côte d'Ivoire\, Republic of, Congo\, Republic of the (Brazzaville)"

Notes for Developers

If you want to edit the source code, go right ahead (pull requests welcome, of course!). The unminified source is found in the /source folder. To re-generate the minified version, just run the Grunt task. In case you're not familiar with Grunt, here's how you get that hooked up.

1. Install Node on your computer.
2. Clone this repository to your local computer.
3. In the command line, navigate to to the root of the cloned repo (i.e. the folder with this README file in it).
4. Type npm install to download all necessary require modules.
5. Type npm install -g grunt-cli to install the Grunt command line tool to run properly.
6. Type grunt generate

That will then re-generate the minified files in your ./dist folder.

Changelog

• 1.0.0 - Jan 17, 2023. Removing invalid console.log.
• 0.5.1 - Nov 22, 2018. Fix for regions not being sorted alphabetically. Thanks, @VincentHokie!
• 0.5.0 - July 8, 2018. Option to list preferred countries at top of countries dropdown added; country data updated.
• 0.4.1 - Nov 7, 2017. Country data updated.
• 0.4.0 - Jul 25, 2017. Bug fix for blacklist/whitelisted fields in page with multiple other country-region-selectors not listing the correct regions.
• 0.3.6 - Oct 31, 2016. Country data updated.
• 0.3.5 - July 4, 2016. Bug fix #40. Country data updated.
• 0.3.4 - July 4, 2016. Bug fix #37. Country data updated.
• 0.3.3 - June 7, 2016. Updated country-region-data set.
• 0.3.2 - May 15, 2016. More country shortcodes added - thanks Ellen Hutchings! Bug fixes
• 0.3.1 - Apr 30, 2016. Loads of new country shortcodes added - thanks Ellen Hutchings!
• 0.3.0 - Apr 28, 2016. Turkey region fix; source data moved to separate repo: https://github.com/country-regions/country-region-data
• 0.2.4 - Feb 11, 2016. South Africa data updated. Custom build option added to let you generate smaller JS files containing only the country data you need.
• 0.2.3 - Feb 11, 2016. Indonesia, Mexico data updated.
• 0.2.2 - Oct 22, 2015. Update regions of Spain to match postal regions.
• 0.2.1 - Oct 20, 2015. Bug fix with Norwegian JS data.
• 0.2.0 - Oct 18, 2015. data-whitelist and data-blacklist options added to Country dropdowns. Support for data-value="shortcode" option for Regions dropdowns.
• 0.1.9 - Aug 27, 2015. Option added to let you omit default option; NZ regions updated.
• 0.1.8 - June 19, 2015. Fix for Norway regions.
• 0.1.7 - May 2, 2015. Updated UK counties.
• 0.1.6 - Apr 10, 2015. Russian regions updated by @Konair0s
• 0.1.5 - Apr 5, 2015. Bug fix.
• 0.1.4 - Apr 4, 2015. Lib now wrapped in UMD (accessible with RequireJS, CommonJS, Node); custom init() function exposed
• 0.1.3 - Feb 10, 2015. Updated Ukraine regions.
• 0.1.2 - Nov 1, 2014. Fix for typo in UK counties list.
• 0.1.1 - April 24, 2014. Updated country list for ISO 3166 countries and short codes
• 0.1.0 - March 27, 2014. Initial version

License

MIT.

country-region-selector's Issues

Sporadic issue - jquery.crs.js not running 80% of the time in a large project

I am making some modification on a large website which downloads a lot of JS file. This may have resulted in sporadic failure. To be explicit, the failure is the "select" tag with class "crs-country" is not populated at all. Digging into the issue, I found that the "_init" function is not being called every time.

I have found a workaround myself, namely to do the following:
1. Comment out: Line 9 to 21 and Line 469 to Line 474.
2. Comment out: Line 467 ==> "$(_init)" and replace it with "$( document ).ready(_init);"

This seems to have resolved my issue.

Country, Region, City and zip code

How can I add city and zip code...

So let say you choose United States > New York > Brooklyn 10000

Request: Prioritize certain countries at top of dropdown

If I rearrange the country select to have Canada and United States at the top of the list and then select Canada, the region select is populated with Afghanistan regions. This likely means the region select is populated based on selected country index instead of value.

let countries = document.getElementById('country');
let canada = countries.options[40];
let united_states = countries.options[235];
countries.remove(40);
countries.remove(235);
countries.add(canada, 1);
countries.add(united_states, 2);

Pre built javascript file Error

WARNING in .//react-country-region-selector/dist/rcrs.js
Critical dependencies:
1:477-484 This seems to be a pre-built javascript file. Though this is possible, it's not recommended. Try to require the original source to get better results.
@ .//react-country-region-selector/dist/rcrs.js 1:477-484

is there's a way to remove default option? I dont want to show a blank option.

Allow grouping of regions

After fixing the UK counties in another ticket, I found that I wanted to group the regions into <optgroups> for England, Scotland, Wales + Northern Ireland. This would be nice for other countries too, no doubt.

Preselecting the first region when changing country

Hello,
Is it possible to Preselect the first Region in REgions List when changing country list ?

Bad region name for Sor-Trondelag in Norway

I don't see what is wrong, but try to select Norway, then Sor-Trondelag.

It reads Sor- instead of Sor-Trondelag for whatever reason. The source code looks good and I can't spot the culprit, but something caps it. Any idea?

Set default country but not the region

Is there a way to set the default country, but not default region? The default country populates correctly, but the region just shows a "-" as the only selection.
I have tried setting the region select options with no data-default-value tag and also tried the following tags in the region select:
data-default-value="-"
data-default-value=""
I am on the latest version 0.3.6, and I did not see this in the examples. I can determine the default country based on ip address, but I don't know the region.

Solution : window.crs.populateRegionFields(countryElement, regionElement) **FOR "RELOADING" THE REGION SELECT**

Hello

I added 1 line of code in your plugin today and i wanted to "commit" my change here:

File:
jquery.crs.js (0.4.0)

Line 212:
(Added) populateRegionFields: _populateRegionFields

So I can call this specific row of code to update the Region Select after I'm setting the value via jQuery:

EXAMPLE
window.crs.init();
$.getJSON('//freegeoip.net/json/', function(result) {
$('#crs-country').val(result.country_code);
window.crs.populateRegionFields($('#crs-country')[0],$('#crs-region')[0]);
});

This Method will locate the current CountryCode from freegeoip.net and determine from which Country the Visitor is coming from and it will assign the value automatically to the Country Select and "repopulate" the Region Select with the current Country Select Value.

I hope I could help a little for others that run in to the same "issue" of a missing region reload method C:

Kind Regards

Mike of Creative-House.org

Update grunt to allow custom build of subset of countries

There's the option baked in to allow whitelisting/blacklisting of countries, to control exactly what appears in the dropdown. This is handy, but it still means downloading the whole file.

Instead, we could add a grunt command to create a custom build that only bundles the specified countries, e.g.

grunt customBuild --countries=Canada,United States,Mexico

That would result in a WAAAAY smaller file.

United Kingdom regions corrupted

I'm not sure what happened, but the list of regions of the UK/GB is corrupted. Several county names are cut off or mangled in some way. I traced all the way to the first commit, and they are still wrong. I found a few correct versions, but it looks like a find and replace messed it up. If you still have your original source, perhaps you can correct it. Otherwise I'll try to track down the correct values to use.

data-default-value in region

data-default-value in region does not work.
Can you please help.

Country Field

<select class="form-control crs-country" id="cube-wad__adr_country" label="Country" name="wad__adr_country" data-region-id="wad__adr_country" data-default-value="United States" data-default-option="...Choose" data-crs-loaded="true">

this field is pre-populated but not the region.

Region Field

<select class="form-control" id="wad__adr_country" label="State" name="wad__adr_state" required="" data-value="abbr" data-default-value="DC" data-blank-option="...Select Country">

Thank you for this library.

NPM Package

My project uses this through npm, but that's still on version 0.2.0 so I can't take advantage of the bug fixes for data that have come out in the that two builds. Could you update it?

Missing region - Tokyo, Japan

It seems that Tokyo, Japan is missing from the latest version.
|Tochigi09|Tokushima36|Saga41|Totigi09|

Presetting data attribute via jquery

Hello.

Thanks for this fantastic control!

Is there a way I can set the selected country and/or region via jquery?

I have an order form with billing and shipping and would like to provide the user with a checkbox to copy billing as shipping details.

So far I have not been successful with getting any of this to work.

Example (hard-coded/watered down for ease of explanation):
$("#BillingCountry").attr('data-default-value', 'United States');
$("#BillingCountry").attr('default-value', 'United States');
$("#BillingCountry").attr('defaultvalue', 'United States');

etc. etc.

Your "pre-filling" examples work just fine but I'm looking to populate the selection dynamically NOT in the markup prior to page load as my page does not do any server postback between sections.

Thanks!

Ian

can't initialize select

when appending country city selector and trying crs.init() I got

crs.js:70 Uncaught TypeError: Cannot set property '0' of undefined
at _populateCountryFields (crs.js:70)
at Object._init [as init] (crs.js:45)
at addExtraActions (client.js:118)
at Object.success (scripts.js:325)
at i (jquery.min.js:4)
at Object.fireWith [as resolveWith] (jquery.min.js:4)
at z (jquery.min.js:6)
at XMLHttpRequest. (jquery.min.js:6)

``

Way to use short-code on US states only?

I only want short-codes used when United States(US) is selected. Is this possible?

Internationalization

Hi!

Thanks for stepping ahead to fill an obvious gap in the JS environment and building a fast and reliable country-region selector.

I'd need to be able to use the selector in an internationalized web app, and present the user with the country and region names according to their desired locale.

Are you planning to add this to country-region-selector? Any hints to do that myself?

Thanks!

links to minified js on readme are broken

UK not recognized?

If I whitelist UK it does not work. If I use GB instead, then it works.

Why will UK not work?

How can I make it work?

Feature Request: Define "preferred" countries that show up first in dropdown

As a user living in a certain country, I might want that country to be at the top of the dropdown so I don't have to scroll the entire alphabetical list to choose it.

As an ecommerce store manager, this might also help abandoment rates.

Maybe you could specify a list of countries you'd want to show up first?

Ukraine - Kyiv region duplicate

State/Province list for the Ukraine has duplicate Kyiv options - Kiev and Kyїv. Kyiv will be the correct one. Thanks

Enhancement request: Add ISO 3166 support

Feature: Disable first option in dropdowns.

As a feature: allow the first option in the a country/region select to have the disabled attribute set. This would force the user to make a country or region selection, and not allow the user to select the options "Select country" or "Select region". See an example of a select with the first option disabled: http://jsfiddle.net/s5Xy2/5/ to get the behavioural idea.

<select class="crs-country" data-region-id="region" data-value="shortcode"  data-crs-loaded="true">
    <option value="" disabled="disabled">Select country</option>
    <option value="AF">Afghanistan</option>
    <option value="AX">Åland Islands</option>
    <option value="AL">Albania</option>...

<select id="region">
     <option value="" disabled="disabled">Select region</option>...

Added AngluarJS functionality - need some distro changes to make it official though.

This is the most comprehensive list that I have seen. Lets make it better though.

1. I have written an angularJS components for this. But in order for users to only get what they need it would be best to separate the the country/city code list from the main repo. And then allow options for users to just grab updates to city/country codes as they happen. If you can do this I will post all the necessary code for the AngularJS implementation.

2. Another issue for consistency is using two/three letter codes for regions/states - there are about 2 dozen that don't have 2 or 3 letter codes....those countries just have the city name and this is all. That poses a problem for Angular when building the $scopes needed for the select drop down menus. In order to fix this, I had to find all those country regions which didn't have a proper 2/3 letter code and basically make one up. In my app i only store the country or region codes...so if one doesn't exist it will break my implementation.

Aside from how I made up region/state codes, how else can this be addressed?

Viet Nam should be Vietnam

All country names are in English & this is the English form of the country name.

Blacklist Region - Puerto Rico

Puerto Rico is listed as a country and a region under the US. I'm not sure if this should be changed in the data file, or if some users might have a reason to use both variations. We are using this for export purposes, so we only want the country of Puerto Rico listed, and not the state under the US. Would it be possible to add the ability to blacklist a specific region in a country? I have already removed it from my data file, but I am looking at a better solution for when there are updates released in the future.

Bootstrap modal closes automatically

I am using this inside a bootstrap modal. When I select a country the bootstrap modal closes automatically. I don't know whats happening. Please help

Build error occur , when creating customBuild with countries that have comma in their names

See example below:

Not working

I have installed country-region-selector using below command

npm install country-region-selector --save

In my HTML I used it like this

<select  class="crs-country" data-region-id="ABC"></select>
<select id="ABC"></select>

but Countries are not showing in dropdown

South Africa province wrong

In the country data
["South Africa","ZA","Eastern Cape~EC|Free State~FS|Gauteng~GT|KwaZulu-Natal~NL|Limpopo~LP|Mpumalanga~MP|Northern~Cape~NC|North West~NW|Western Cape~WC"],

Northern~Cape~NC should be Northern Cape~NC

Istanbul not delimited

In the list of "states" for Turkey, Istanbul is combined with the following list item, like so:
IstanbKahramanmaras

Is it possible to 5th depth?

dear developer..

i likely interested with this domain. but i want to ask before.

i want at registration form, a country field, a city field, and sub disctrict, and sub-sub district.
is it possible to do that?

i am in indonesia, i want people can choose indonesia country, then it shows all indonesia's province, jakarta for example. then after i choose jakarta it should show all city under it like south-jakarta, west jakarta, east jakarta.

this i want exactly i want:

...

1. Hungary
2. Indonesia (level 1)

• 2,1 Jakarta (level 2)
  ---2.1.1 South Jakarta (level 3)
  ---2.1.1.1 Mampang Prapatan (level 4)
  ---2.1.1.1.1 Kuningan Barat (level 5)

3. India
   ...

that's look 5 depth. and of course it find to database table that we will provide before. in indonesia, it have 82.353 at level 5 (villages). and seems we need add all these villages to a database.

is it possible this plugin support this kind of feature? thank you verymuch :)

Angular 1.6 - select fields not updating model

Hi!
I have a problem updating my project from angular 1.4.x to 1.x (which is 1.6.6 by now). CRS used to work OK, but it stopped updating the model of the fields, while the country selector perfectly updates the state field.
Select boxes works OK when populated manually, populating them with CRS makes this stop working.

<select
    name="countries"
    id="countries"
    class="crs-country"
    data-default-value="{{countryDefault}}"
    data-region-id="states"
    required
    ng-model="forms.card.address.country"
    data-value="shortcode">

<select
    id="states"
    required
    ng-model="forms.card.address.state"
    data-value="shortcode">

Example 6 & 7 show wrong regions for selected country

Was just checking this library out and noticed an issue with the example, not sure if it's a bug in the library or just in the example.

http://benkeen.github.io/country-region-selector/ Example 6 shows the wrong regions for the listed countries.

Feature Request: 'Other' Select Option

Perhaps I'm missing it, but I don't see an option/way to force an 'other' option to lit up, say, a div or something else (with an input field) to allow for custom input.

It flies in the face of what this tool is trying to do, but it would be nice to have the option.

Dropdowns do not update when values are set in backend

If I set my country dropdown's value to "Canada" in the backend, the dropdown shows the selected country as "Canada", but the region dropdown still displays "-" as if a country hasn't been selected.

Update
To get the region dropdown to populate, I had to do this:

document.getElementById('country').dispatchEvent(new Event('change'));

Update grunt to include header comment

The minimized files should contain that info otherwise people won't know what version is running.

Add more cities

How to add more countries ? I'd like to add more cities in Bulgaria.
I try to edit something but without success. Even if i edit the names, the changes not made.

Select 2 compatibility

Hi, Im trying to make this work with select2 jquery plugin, all options get loaded and I even can search, the problem is that the region field doesnt update when changing the option, could you give me some advice? Thanks!

Best way to convert country codes back to full name?

Thanks for this very useful tool. We're storing only country codes and region codes (when available) but for UI purposes want to show users the full names. I was hoping there might already exist a code -> fullName lookup object in the design. I noticed the source data lives in a separate repo, but it appears to be built into this repo rather than an npm dependency. Has anyone else solved this problem already (hopefully without having to duplicate data)?

data-default-value not set

How do I get the country dropdown to display "United States" by default, AND have it's value to match?

I have an on change event attached to the country selector.
When the page loads, however, when, in my $(document).ready, I use $("#myselector").val() the value is empty.

Now, I've set both: data-default-option="United States" and data-default-value="United States" but it seems like, although it sets the default option, it doesn't set the value.

If I don't set the data-default-option then the default item in the selector stays "Select country" even though I've set data-default-value.

In fact, if I click on the select box and choose the default, it still has no value. The only time a value is set is when I select something from the list besides the default at the first position.

Am I missing something?

Dynamic trigger

How would one trigger the initialization function of country-region-selector on dynamically loaded content?

Typo in United Kingdom

In crs.js line 252: It says "ddlesbrough" instead of Middlesbrough.

By the way, what is the source for this data, and does it get updated?

Feature request: State/Province Abbreviations

Thank you for the great script. One feature that would be very useful is to be able to optionally use state/province 2-letter abbreviations as values in the region selector.

Incorrect region code for Hakkaio, JP

My internationalization team alerted me to a region code issue:

Region code for "Hokkaido" is incorrect in Address. "Hokkaido" is one of the prefectures within Japan.
Currently, "Hokkaido" region code defaults to "04". However, the correct "Hokkaido" region code is "01". "04" is Miyagi.

data-default-value option seems not to work properly

The following code still show first region from the list (Alsace), not default value:

        <div class="form-group">
          <label for="country">Country</label>
                  <select name="country" class="form-control crs-country" data-region-id="one" data-value="shortcode" data-default-value="FR" data-show-default-option="false">
                  </select>
        </div>
        <div class="form-group">
          <label for="state">State or region</label>
                  <select name="state" class="form-control" id="one" data-default-value="Franche-Comté"  data-show-default-option="false">
                  </select>
        </div>

Add country whitelist option

It would be helpful in some cases to only show a subset of the list of countries. Add a whitelist option to let users choose exactly which countries should be included in the country dropdown.

Validating input

Given that this is being used on the client side and then data sent to the server, once on the server side, can I use this module in Node to validate the input data? How would I go about doing that?