A simple jQuery plugin for picking provinces, cities and districts of China.

Usage no npm install needed!

<script type="module">
  import distpicker from 'https://cdn.skypack.dev/distpicker';



Downloads Version Gzip Size

A simple jQuery plugin for picking provinces, cities and districts of China.


Table of contents


├── distpicker.js        (UMD)
├── distpicker.min.js    (UMD, compressed)
├── distpicker.common.js (CommonJS, default)
└── distpicker.esm.js    (ES Module)

Getting started


npm install distpicker

Include files:

<script src="/path/to/jquery.js"></script><!-- jQuery is required -->
<script src="/path/to/distpicker.js"></script>

Create HTML elements:

<div><!-- container -->
  <select></select><!-- province -->
  <select></select><!-- city -->
  <select></select><!-- district -->


Initialize with data-toggle="distpicker" attribute


<div data-toggle="distpicker">

Custom placeholders

<div data-toggle="distpicker">
  <select data-province="---- 选择省 ----"></select>
  <select data-city="---- 选择市 ----"></select>
  <select data-district="---- 选择区 ----"></select>

Custom districts

<div data-toggle="distpicker">
  <select data-province="浙江省"></select>
  <select data-city="杭州市"></select>
  <select data-district="西湖区"></select>

Initialize with $.fn.distpicker method



Custom placeholders

  province: '---- 所在省 ----',
  city: '---- 所在市 ----',
  district: '---- 所在区 ----'

Custom districts

  province: '浙江省',
  city: '杭州市',
  district: '西湖区'

⬆ back to top


  • Change the default options with $().distpicker(options).
  • Change the global default options with $.fn.distpicker.setDefaults(options).

Also supports to set the options by data-* attributes:

<div data-toggle="distpicker" data-autoselect="3" data-province="浙江省">...</div>


  • Type: Number
  • Options:
    • 0: Disable autoselect.
    • 1: Autoselect province only.
    • 2: Autoselect province and city only.
    • 3: Autoselect all (province, city and district).
  • Default: 0

Selects the districts automatically.


  • Type: Boolean
  • Default: true

Show placeholder (with an <option> element).


  • Type: String
  • Options:
    • 'name': administrative division name.
    • 'code': administrative division code.
  • Default: 'name'

Defines the value type of the <select> element.

Note that this option in data-* attribute should be data-value-type:

<div data-toggle="distpicker" data-value-type="code">...</div>


  • Type: String
  • Default: —— 省 ——

Defines the initial value of province <select>. If it is a valid province, it will be selected. If not, it will be used as a placeholder.


  • Type: String
  • Default: —— 市 ——

Defines the initial value of city <select>. If it is a valid city under the selected province, it will be selected. If not, it will be used as a placeholder.


  • Type: String
  • Default: —— 区 ——

Defines the initial value of district <select>. If it is a valid district under the selected city, it will be selected. If not, it will be used as a placeholder.

⬆ back to top



  • districtCode (optional):

    • Type: Number
    • The district code of target country, province or city.
    • If not present, will return all the districts.
  • (return value):

    • Type: Object

Get districts data.

$().distpicker('getDistricts'); // 中国
$().distpicker('getDistricts', 330000); // 浙江省
$().distpicker('getDistricts', 330100); // 杭州市


  • deep (optional):
    • Type: Boolean
    • Default: false
    • Reset the selects to default states (Undo selected).

Reset the selects to the initial states (Undo changed).

$().distpicker('reset', true);


Destroy the distpicker instance, but keep the selected districts.

If you want to remove the selected districts, you can call reset method first and then call this method.

⬆ back to top

No conflict

If you have to use other plugin with the same namespace, just call the $.fn.distpicker.noConflict method to revert to it.

<script src="other-plugin.js"></script>
<script src="distpicker.js"></script>
  // Code that uses other plugin's "$().distpicker" can follow here.

Browser support

  • Chrome (latest)
  • Firefox (latest)
  • Safari (latest)
  • Opera (latest)
  • Edge (latest)
  • Internet Explorer 9+

As a jQuery plugin, you also need to see the jQuery Browser Support.


MIT © Chen Fengyuan

⬆ back to top