A simple, configurable JS script that lets you add a country dropdown that automatically updates a corresponding region dropdown in your forms.
npm install country-region-dropdownsA feature you often need in forms is a connected country and region dropdown, where once the user selects a country,
the region field gets updated to show the appropriate list of regions (provinces/states/counties etc). It's very easy
to code all this, but it's kind of pain having to track down all the raw country-region data.
That's what this script does. 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.
The script comes in two flavours, both about 60KB.
- standalone script (no dependencies, just plain JS)
- a jQuery-dependent version (ever-so slightly smaller)
The reason the files are so large 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 can 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 on that.
- 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.
Check out the following page for an example of the various ways it can be configured and used.
http://benkeen.github.io/country-region-selector/
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/benkeen/country-region-data
It's very easy.
1. Include the crs.min.js file in your webpage.
2. Add two 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 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.
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/benkeen/country-region-selector/blob/master/source/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/benkeen/country-region-selector/blob/master/source/data.json
##### region fields
- data-blank-option - before the user selects a country, there's a single
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).
``javascript`
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