City Selector

A ready-made province and city picker for Iran. Built on Combobox, and bundled with all 31 provinces and 1,119 cities — the city field stays disabled until a province is chosen, and both are searchable.

Last updated January 1, 1980

Overview

Installation

$ pnpm dlx shadcn@latest add @persianlabsui/city-selector

Usage

import { CitySelector } from "@/components/ui/city-selector"
 
export function Example() {
  return <CitySelector />
}

Or compose the parts yourself for full control over layout, labels, and placeholders:

import { Label } from "@/components/ui/label"
 
import {
 
  CitySelector,
  CitySelectorCity,
  CitySelectorProvince,
} from "@/components/ui/city-selector"
 
export function Example() {
  return (
    <CitySelector locale="en" className="flex-col gap-4 sm:flex-col">
      <div className="flex flex-col gap-1.5">
        <Label>Province</Label>
        <CitySelectorProvince placeholder="Choose a province…" />
      </div>
      <div className="flex flex-col gap-1.5">
        <Label>City</Label>
        <CitySelectorCity placeholder="Choose a city…" />
      </div>
    </CitySelector>
  )
}

Examples

Controlled (English)

Controlled (Persian)

Locale

By default, labels follow the document's text direction — Persian in RTL, English in LTR. Pass locale to force one regardless of direction — it flips the text direction of the picker too.

Custom layout

Compose CitySelectorProvince and CitySelectorCity yourself as children of CitySelector for full control over layout, labels, and placeholders.

Form

CitySelector is a plain controlled component — its value / onValueChange pair binds directly into any state or validator, no adapter needed. Here it's validated with Zod alongside a plain text field.

API Reference