react-bootstrap-country-select
TypeScript icon, indicating that this package has built-in type declarations

1.0.0 • Public • Published

React Bootstrap Country Select   Tweet

License: MIT NPM version Required react version Issues npm bundle size

A country select component with flag icons for React Bootstrap.

Go to the demos page to see it in action.

React Bootstrap Country Select screenshot showing country select component when focused

React Bootstrap Country Select screenshot showing country select component with entered text and auto suggestions in dropdown below input

React Bootstrap Country Select screenshot showing selected country

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

Package Sidebar

Install

npm i react-bootstrap-country-select

Weekly Downloads

263

Version

1.0.0

License

MIT

Unpacked Size

950 kB

Total Files

23

Last publish

Collaborators

  • jaywilz