search

country-regions / react-country-region-selector

Country-region dropdowns for your React forms
http://country-regions.github.io/react-country-region-selector/
325 stars 131 forks source link
country-codes country-list country-selection react react-component region-selector regions

readme

react-country-region-selector

Build Status

About

This library provides a pair of React components to display connected country and region dropdowns (pick a country, it shows the relevant regions). If you're not using React, check out the plain vanilla JS version instead. The list of countries and regions is maintained separately and found in the country-region-data repo.

Features

It's pretty versatile.

Gotchas

Demo

Check out the github pages section for some examples + example JSX code.

Installation

Using npm or yarn:

npm i react-country-region-selector
yarn add react-country-region-selector

Usage

It's very easy to use, but note that you will need to track the country and region value somewhere - either in your component state or in a store somewhere. Here's a simple example that uses state:

import React, { useState } from 'react';

// note that you can also export the source data via CountryRegionData. It's in a deliberately concise format to 
// keep file size down
import { CountryDropdown, RegionDropdown, CountryRegionData } from 'react-country-region-selector';

const Example = () => {
  const [country, setCountry] = useState('');
  const [region, setRegion] = useState('');

  return (
    <div>
      <CountryDropdown
        value={country}
        onChange={(val) => setCountry(val)} />
      <RegionDropdown
        country={country}
        value={region}
        onChange={(val) => setRegion(val)} />
    </div>
  );
}

Generally you don't need CountryRegionData, but if you should need it, the raw data is accessible like in the above example.

Options

These are the attributes that can be passed to the two components. Note: any other attributes that aren't specified here will be added directly to the <select> DOM element.

<CountryDropdown />

Parameter Required? Default Type Description
value Yes "" string The currently selected country. This should either be the shortcode, or the full country name depending on what you're using for your value attribute (see the valueType option). By default it's the full country name.
onChange Yes - function Callback that gets called when the user selects a country. Use this to store the value in whatever store you're using (or just the parent component state).
onBlur No - function Callback that gets called when the user blurs off the country field.
name No "rcrs-country" string The name attribute of the generated select box.
id No "" string The ID of the generated select box. Not added by default.
classes No "" string Any additional space-separated classes you want to add.
showDefaultOption No true boolean Whether you want to show a default option.
priorityOptions No array [] Lets you target countries that should appear at the top of the dropdown. Should also be an array of country shortcodes.
defaultOptionLabel No "Select Country" string The default option label.
labelType No "full" string Either "full" or "short". This governs whether you see country names or country short codes in the dropdown.
valueType No "full" string Either "full" or "short". This controls the actual value attribute of each <option> in the dropdown. Please note, if you set this to "short" you will need to let the corresponding <RegionDropdown /> component know as well, by passing a countryValueType="short" attribute.
whitelist No [] array This setting lets you target specific countries to appear in the dropdown. Only those specified here will appear. This should be an array of country shortcodes. See the country-region-data repo for the data and the shortcodes.
blacklist No [] array Lets you target countries that should not appear in the dropdown. Should also be an array of country shortcodes.
disabled No false boolean Disables the country field.

<RegionDropdown />

Parameter Required? Default Type Description
country Yes "" string The currently selected country.
value Yes "" string The currently selected region.
onChange Yes - function Callback that gets called when the user selects a region. Use this to store the value in whatever store you're using (or just the parent component state).
onBlur No - function Callback that gets called when the user blurs off the region field.
name No "rcrs-region" string The name attribute of the generated select box.
id No "" string The ID of the generated select box. Not added by default.
classes No "" string Any additional space-separated classes you want to add.
blankOptionLabel No - string The label that appears in the region dropdown when the user hasn't selected a country yet.
showDefaultOption No true boolean Whether you want to show a default option. This is what the user sees in the region dropdown after selecting a country. It defaults to the defaultOptionLabel setting (see next).
defaultOptionLabel No Select Region string The default region option.
onChange No - function Called when the user selects a region. Use this to store the region value.
countryValueType No full string If you've changed the country dropdown valueType to short you will need to set this value to short as well, so the component knows what's being passed in the country property.
labelType No "full" string Either "full" or "short". This governs whether you see region names or region short codes in the dropdown.
valueType No "full" string Either "full" or "short". This controls the actual value attribute of each <option> in the dropdown.
disableWhenEmpty No false boolean Disables the region field when the user hasn't selected a country.
disabled No false boolean Disables the region field. If set to true, it overrides disableWhenEmpty
customOptions No [] Array<string> Appends a list of string to the every region dropdown, regardless of the country selected.
whitelist No { CountryCode: [] } object This setting lets you target specific regions to appear in the dropdown. Only those specified here will appear. This should be an array of region codes keyed by the country code.
blacklist No { CountryCode: [] } object This setting lets you target specific regions that should not appear in the dropdown. This should be an array of region codes keyed by the country code. disableWhenEmpty No false boolean Disables the region field when the user hasn't selected a country.
disabled No false boolean Disables the region field. If set to true, it overrides disableWhenEmpty

Command-line

Check out the scripts section of the package.json file to see them all, but these are the highlights:

Changelog

Tests

The Jest/Enzyme unit tests are found in the src/tests folder. The repo is hooked up to Travis CI to automatically run the tests for each commit.

Local Dev

This is pretty dated, I'm afraid. But to run this locally, do the following:

Thanks!

Big thanks to a whole boatload of people:

License

MIT.