react-bootstrap-country-select

React Bootstrap Country Select  

A country select component with flag icons for React Bootstrap.

Go to the demos page to see it in action.

Installation

yarn add react-bootstrap-country-select

or

npm install react-bootstrap-country-select

Prerequisites

React Bootstrap must be installed and the Bootstrap CSS imported (or included).

Usage

In your index.js or similar:

import 'bootstrap/dist/css/bootstrap.css'; // or include from a CDN
import 'react-bootstrap-country-select/dist/react-bootstrap-country-select.css';

Your component:

import React, { useState } from 'react';
import CountrySelect from 'react-bootstrap-country-select';

const MyComponent = () => {

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

  return (
    <CountrySelect
      value={value}
      onChange={setValue}
    />
  );

};

Features

• Compatible with React Bootstrap v1.0.0+ and Bootstrap 4;
• Implemented using standard React Bootstrap components;
• Autosuggest: a list of matching countries is displayed when the input text changes;
• Country data is provided;
• Specific countries can be excluded and additional countries added;
• Country flag icons;
• onChange and onTextChange callbacks;
• Custom sort and country list formatter functions;
• Bootstrap small (sm) and large (lg) sizes are supported
• Aligns horizontally with Bootstrap form controls;

Options (as React props)

Property	Type	Default	Description
value	object | string		The current value: a country object, country ID or null. See valueAs.
onChange	function		A callback fired when a country is selected or unselected. The argument is the country object, country ID or null.
onTextChange	function		A callback fired when the input text changes. The first argument is the text value and the second argument is the input's change event object.
countries	array		An array of country objects used to populate the country list. Provide this if you'd like to use your own countries data. A country object has the properties: id, name, flag, alpha2, alpha3 and ioc.
exclusions	array		An array of country IDs that defines the countries to be excluded from the country list.
additions	array		Additional countries in the same format as countries.
valueAs	object | id	object	Determines if value is a country object or an ID string.
flags	boolean	true	Flags are displayed when true and not displayed when false.
flush	boolean	true	When true the selected country flag appears in the input. When false it is rendered using <InputGroup.Text/>.
disabled	boolean	false	Disables the country select.
placeholder	string	"Type or select country..."	Placeholder text displayed in empty input.
noMatchesText	string	"No matches"	The text displayed when no countries match the entered input text.
size	'sm' | 'lg'		Input size variants, for compatibility with other Bootstrap form components.
listMaxHeight	number		Maximum pixel height of the list overlay.
sort	function		A custom sort function that determines the order of the country list. The function's two arguments country objects.
matchNameFromStart	boolean	true	If true autosuggest matches country names from the start of the string.
matchAbbreviations	boolean	false	If true autosuggest matches against alpha2, alpha3 and IOC abbreviations in addition to country names.
countryLabelFormatter	function		A custom country list item formatter. The argument is a country object.
throwInvalidValueError	boolean	false	If true an error is thrown if the provided value does not match a country.

| formControlProps | object | | Properties applied to the <FormControl/> input. | | overlayProps | object | | Properties applied to the overlay <div> element that contains the country list. | | classPrefix | string | 'country-select' | Change the underlying component CSS base class name and modifier class names prefix. This is an escape hatch for working with heavily customized CSS. |

For further documentation and live examples visit the website.

If you have a usage query or feature request please create an issue.

License

Copyright (c) 2020 Jason Wilson

MIT License