Nefariously Programmed Mecha
Miss any of our Open RFC calls?Watch the recordings here! »

react-india-state-region-selector

6.1.0 • Public • Published

react-indian-state-region-selector

A feature you often need in forms is a connected State and region dropdown, where the region field gets automatically updated when the user selects a State. Coding this is easy of course, but it's a royal pain having to track down all the raw State-region data. This script contains a pair of components to let you add this feature quickly and easily to your forms. It's the React version of this script.

It's pretty versatile:

  • Has two separate components (<StateDropdown />, <RegionDropdown>) that you can embed in your DOM wherever you need. That sounded like a vulgar euphemism, but it wasn't, honest.
  • Let's you customize the list of countries that appears via a whitelist, blacklist, or even custom build to keep file size down.
  • Works as ES6 module, commonJS, AMD, whatever you fancy.
  • Lots of options for the most common use-cases, allowing you style is as you need (via classes/IDs), change name attributes, add you own custom onChange handlers to do whatever you want etc.

Examples

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

Requirements

  • React (tested with 15.1.0, but should work on earlier versions).
  • If you want to run the repo locally (e.g. generated

Installation

Ah, modern web development: so many choices! Here's how to install it with the most common build tools:

npm

npm install react-indian-state-region-selector --save

Bower

bower install react-indian-state-region-selector 

UMD (Universal Module Definition)

Just use the dist/rcrs.min.js file.

Usage

Here are a few examples in a few different formats.

ES6 with JSX example

I figure people not using JSX will know how to remove the JSX from the code below, if not open a ticket and I'll write up a non-JSX example too.

import React from 'react';
import { StateDropdown, RegionDropdown } from 'react-indian-state-region-selector';
 
 
class Example extends React.Component {
  constructor (props) {
    super(props);
    this.state = { State: '', region: '' };
  }
 
  selectState (val) {
    this.setState({ State: val });
  }
 
  selectRegion (val) {
    this.setState({ region: val });
  }
 
  render () {
    const { State, region } = this.state;
    return (
      <div>
        <StateDropdown
          value={State}
          onChange={(val) => this.selectState(val)} />
        <RegionDropdown
          State={State}
          value={region}
          onChange={(val) => this.selectRegion(val)} />
      </div>
    );
  }
}

ES5 with JSX

// Up to you to include React + the react-indian-state-region-selector (script tags, commonJS, whatever). 
// That's a choice you need to make with your build setup.
 
var Example = React.createClass({
  getInitialState: function () {
    return {
      region: '',
      State: '',
    };
  },
 
  selectState: function (val) {
    this.setState({ State: val });
  },
 
  selectRegion: function (val) {
    this.setState({ region: val });
  },
 
  render () {
    return (
      <div>
        <StateDropdown
          value={this.state.State}
          onChange={this.selectState} />
        <RegionDropdown
          State={this.state.State}
          value={this.state.region}
          onChange={this.selectRegion} />
      </div>
    );
  }
}

AMD

define([
  'react',
  'react-indian-state-region-selector'
], function (React, rcrs) {
 
  var StateDropdown = rcrs.StateDropdown;
  var RegionDropdown = rcrs.StateDropdown;
 
  var Example = React.createClass({
    getInitialState: function () {
      return {
        region: '',
        State: '',
      };
    },
 
    selectState: function (val) {
      this.setState({ State: val });
    },
 
    selectRegion: function (val) {
      this.setState({ region: val });
    },
 
    render () {
      return (
        <div>
          <StateDropdown
            value={this.state.State}
            onChange={this.selectState} />
          <RegionDropdown
            State={this.state.State}
            value={this.state.region}
            onChange={this.selectRegion} />
        </div>
      );
    }
  }
 
  return Example;
});

Options

<StateDropdown />

Parameter Required? Default Type Description
value Yes "" string The currently selected State. This should either be the shortcode, or the full State name depending on what you're using for your value attribute (see the valueType option). By default it's the full State name.
onChange Yes - function Callback that gets called when the user selects a State. 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 State field.
name No "rcrs-State" 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.
defaultOptionLabel No "Select State" string The default option label.
labelType No "full" string Either "full" or "short". This governs whether you see State names or State 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 StateValueType="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 State shortcodes. See the State-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 State shortcodes.
disabled No false boolean Disables the State field.

<RegionDropdown />

Parameter Required? Default Type Description
State Yes "" string The currently selected State.
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 State 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 State. 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.
StateValueType No full string If you've changed the State 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 State 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 State.
disabled No false boolean Disables the region field. If set to true, it overrides disableWhenEmpty

Other Stuff

  • Page charset: your page will need an appropriate charset to handle UTF-8 chars used in some State names. So if you see some invalid characters appearing in the dropdown, make sure you have UTF-8 specified in your page <head>, like so: <meta charset="UTF-8">
  • Data source: the list of countries and regions is maintained separately and pulled from the State-region-data repo.
  • Return values: on an onChange event event.target.value is returned as the first value and the full event as the second.

Gulp commands

  • gulp - regenerate everything.
  • gulp --countries="UK,US" - generate a custom build of the script in the /lib and /dist folder containing only those countries you specify here. This seriously reduces file size (60KB down to as small as 16KB), so if you can do it, do it.

Other

This repo uses the extremely handy react-component-gulp-tasks script for doing most of the gulp tasks (ES6, JSX conversion, UMD file creation, minifications, watchers, etc.). Big thanks to Jed Watson there.

Changelog

  • 1.3.0 - Mar 20, 2018. Bug fix for invalid State, @n-david! onBlur event added.
  • 1.2.3 - Nov 7, 2017. State data updates. React moved to peer dependency, thanks @iamdey!
  • 1.2.2 - Oct 4, 2017 - Update to pass event on change. Thanks @robertnealan!
  • 1.2.1 - Sept 6, 2017 - IE11 bug fix.
  • 1.2.0 - Aug 7, 2017 - updated State-region-data; dependency updates.
  • 1.1.0 - May 18, 2017 - dependency updates. disabled option added to <StateDropdown /> and <RegionDropdown />.
  • 1.0.4 - April 12, 2017 - bug fix. Thanks @bebbi and @tchaffee!
  • 1.0.3 - Jan 2, 2016 - updated State-region-data, repo link fix.
  • 1.0.2 - October 16, 2016 - Fix issue where source-data.js in lib had no State data.
  • 1.0.0 - July 1, 2016 - initial version.

License

MIT.

Install

npm i react-india-state-region-selector

DownloadsWeekly Downloads

8

Version

6.1.0

License

MIT

Unpacked Size

3.32 MB

Total Files

31

Last publish

Collaborators

  • avatar