React Bootstrap Country Select

Getting Started

Prerequisites

React Bootstrap Country Select depends on react-bootstrap version 1.0.0+. This and React version 16.8+ must be installed for the country select to work.

Installation

yarn add react-bootstrap-country-select

or

npm install react-bootstrap-country-select

Adding the stylesheet

Include the CSS, typically in your application's index.js or the same place you include bootstrap.css:

import 'bootstrap/dist/css/bootstrap.css';
import 'react-bootstrap-country-select/dist/react-bootstrap-country-select.css';

Simplest Usage

React Bootstrap Country Select requires two props to work: value, which is a country object* and onChange, a handler that will be invoked when a country is selected.

const [ value, setValue ] = React.useState(null);

<CountrySelect
  value={value}
  onChange={setValue}
/>

* By default the valueAs prop is set to object. Optionally, you could use a ID string value instead.

Country object

The country object has the following properties:

id

A unique identifier, for example fr for France. For the provided data id is equal to alpha2 for all countries. If you use you own data you must ensure that each id is unique.

name

The English name of the country, for example France.

flag

The country flag emoji, for example 🇫🇷

alpha2

The lower case ISO 3166-1 alpha-2 code for the country, for example de in the case of Germany. For the provided data each alpha2 is unqiue, but this may not necessarily be true if you add you own data that included, for example reserved or deleted codes.

alpha3

The lower case ISO 3166-1 alpha-3 code for the country, for example deu in the case of Germany.

ioc

The lower case International Olympic Commimittee (IOC) three-letter abbreviation country code, which can be different from alpha2, for example ger for Germany.

Value as object or ID string

The valueAs prop determines whether the value is treated as an object representating a country or as a string that is a valid country ID. If set to object the value prop's value should be an object that has an id property, that is a valid country ID. If set to id the value prop's value should be a string that is valid country ID. In either case the ID must correspond to one of the countries in the countries data. The onChange handler's first argument will be an object or ID string respectively. By default the valueAs prop is set to 'object'.

In the following example valueAs is set to id and the value set as 'fr'.

const [ value, setValue ] = React.useState('fr');

<CountrySelect
  value={value}
  onChange={setValue}
  valueAs='id'
/>

Countries Data

Use the countries prop if you would like to use your own custom data. This should be an array of country objects. The only properties that are required for the country select to work are id and name. Of course, flags and autosuggest based on alpha2, alpha3 and IOC abbreviations will only work if provided. If the countries prop is left unset the default provided data will be used.

If the provided data almost suits your needs but you would like to append it with additional countries, you can use the additions prop, which like the countries prop expects an array of country objects. Additional countries that have id properties matching those in the provided data will replace those in the provided data.

To exclude one or more countries, for example Antarticta, provide an array of country ID strings with the exclusions prop. Exclusions are applied after additions.

Country flag icons

A flag icon is displayed for each country in the list and for the selected country. By default the flags prop is true. Set to false to hide flags. By default the selected country's flag is displayed within the input at the start. When the flush prop is set to false the selected country's flag is displayed using React Bootstrap's <InputGroup.Text>, as in this example:

const [ value, setValue ] = React.useState('fr');

<CountrySelect
  value={value}
  onChange={setValue}
  valueAs='id'
  flush={false}
/>

Sorting

By default the list of countries is sorted alphabetically by name in ascending order. If a different sort order is required a compare function can be provided using the sort prop.

const [ value, setValue ] = React.useState(null);

<CountrySelect
  value={value}
  onChange={setValue}
  sort={(c1, c2) => {
    if (c1.name.length > c2.name.length) return 1;
    else if (c1.name.length < c2.name.length) return -1;
    else return 0;
  }}
/>

The compare function is invoked with a pair of country objects as its arguments and should be implemented according to the Array.sort() method's description.

List item formatter

The format of the text label for each item in the country list can be customised using the countryLabelFormatter prop. It accepts a formatter function where the argument is a country object. The function should return a string or node.

const [ value, setValue ] = React.useState(null);

<CountrySelect
  value={value}
  onChange={setValue}
  countryLabelFormatter={country => `${country.name} (${country.alpha2})`}
/>

In this example each country's name and alpha2 code are rendered as the list item labels.

Search as you type

The list of countries appears when the input is focused and is filtered according to the entered text. The props matchNameFromStart and matchAbbreviations affect the filtering behaviour. The default is that matchNameFromStart is set to true, so entered input text matches from the start of each country name, and that matchAbbreviations is set to false, so matching is done only against country names, not their ISO codes or IOC abbreviations.

In the following example matchNameFromStart is set to false so that inputted text will be matched against country names for all string character positions. And matchAbbreviations is set to true so that matching is done against countrys' ISO codes and IOC abbreviations in addition to their names.

const [ value, setValue ] = React.useState(null);

<CountrySelect
  value={value}
  onChange={setValue}
  matchNameFromStart={false}
  matchAbbreviations
/>