Country Select React component for Tailwind CSS v4

Add to a project

Requirements: React 19 and Tailwind CSS v4, in Next.js (App Router or Pages), Vite or React Router. Installation guide · Next.js setup · Vite setup

Country Select is part of Pro, with 298 more Pro items: $8 a month or $150 once. 14-day refund before you download any Pro item. See plans

Usage

Import CountrySelect from @/components/ui/country-select.

import { useState } from "react"
import { CountrySelect } from "@/components/ui/country-select"

export function ShippingCountry() {
  const [country, setCountry] = useState("US")
  const [markets, setMarkets] = useState<string[]>(["US", "CA"])
  return (
    <div className="flex flex-col gap-4">
      <CountrySelect
        label="Country"
        description="Where we ship your order."
        value={country}
        onValueChange={setCountry}
        priority={["US", "CA", "MX"]}
        required
        name="country"
      />
      <CountrySelect
        multiple
        label="Markets"
        value={markets}
        onValueChange={setMarkets}
        showDialCode
        maxSelected={5}
        clearable
      />
    </div>
  )
}

Props

• labeldefault ""
  ReactNode

  The label above the field; plain text also titles the phone sheet.

• descriptiondefault ""
  ReactNode

  Helper text under the field, linked with aria-describedby.

• errordefault ""
  ReactNode

  Replaces the description with an error and marks the field invalid.

• requireddefault false
  boolean

  Adds the asterisk to the label and blocks an empty native form submit.

• multipledefault false
  boolean

  Pick several countries: value becomes a string[] of codes, shown as chips with flags.

• value
  string | string[]

  The chosen ISO 3166-1 alpha-2 code ("US"), or codes with multiple, when you control it. "" is nothing. Lowercase codes are read as uppercase.

• defaultValuedefault ""
  string | string[]

  The starting value while uncontrolled ([] with multiple). A form reset returns to it.

• onValueChange
  (value: string) => void | (value: string[]) => void

  Called with the new code (or the list of codes with multiple) after a pick, a chip removal, a clear or browser autofill.

• showFlagdefault true
  boolean

  The emoji flag in each row, in the field and in chips. Windows has no flag emoji, so it shows a small code chip there.

• showDialCodedefault false
  boolean

  The calling code ("+1") at the end of each row and after the chosen name. Dial codes are searchable either way.

• priority
  string[]

  Codes listed first under labels.suggested, in this order. Default: the locale's country ("en-US" suggests US). [] removes the group.

• countries
  string[]

  The codes to offer, e.g. the countries you ship to. Default: every country libphonenumber-js knows (about 245).

• exclude
  string[]

  Codes to leave out of the list.

• localedefault ""
  string

  The language of the names and their sort order, through Intl.DisplayNames ("de-DE" lists Deutschland). Default: the UIProvider's locale, else the browser's. English names stay searchable in other locales.

• renderFlag
  (code: CountryCode) => ReactNode

  Your own flag for a code (an svg flag set). Default: the CountryFlag emoji.

• placeholderdefault ""
  string

  Shown while nothing is chosen. Default "Select a country", or "Select countries" with multiple.

• labels
  Partial<CountrySelectLabels>

  Strings: search ("Search by name or code"), empty ("No country found"), suggested ("Suggested"), allCountries ("All countries"), plus the multi-select strings (selectAll, clearAll, done, selected, limit, more, remove) and the screen reader result count.

• searchdefault "auto"
  "auto" | "always" | "never"

  The search row. auto shows it above 8 countries and, on touch, waits for a tap so the keyboard does not cover the list; always focuses it on open everywhere.

• clearabledefault false
  boolean

  An x in the field while a value is set; it clears the value (all countries with multiple).

• clearLabeldefault "Clear"
  string

  The accessible name of the clear button.

• highlightMatchesdefault true
  boolean

  Bold letters where a search matches a country name.

• leftIcon
  ReactNode

  An icon at the start of the field: while nothing is chosen (or with showFlag off) in single mode, always in front of the chips with multiple.

• sizedefault "md"
  "sm" | "md" | "lg"

  32, 40 (44 on touch) or 48px, like every field and button.

• variantdefault "soft"
  "soft" | "outline" | "underline" | "ghost"

  The field box look.

• radiusdefault "md"
  "none" | "sm" | "md" | "lg" | "full"

  The corner radius, scaled per size like the button.

• invaliddefault false
  boolean

  The invalid look without a message.

• disableddefault false
  boolean

  Dims the field and blocks it.

• readOnlydefault false
  boolean

  Shows the country without letting anyone change it.

• displaydefault "chips"
  "chips" | "count" | "text"

  With multiple: chips with flags, "3 selected", or the names joined.

• maxSelecteddefault 0
  number

  With multiple: the most countries someone can pick (0 is no limit).

• maxVisibleChipsdefault 0
  number

  With multiple: chips shown before "+N" (0 fits as many as one line holds).

• wrapdefault false
  boolean

  With multiple: chips wrap onto more lines and the field grows.

• closeOnSelectdefault false
  boolean

  With multiple: close the desktop list after each pick (the phone sheet waits for Done).

• namedefault ""
  string

  Renders a hidden native select (hidden inputs with multiple) so forms submit the codes.

• autoCompletedefault "country"
  string

  The hidden select's autocomplete token, so browser autofill picks the country from the saved address.

• id
  string

  The trigger's id; the label points to it.

• fieldProps
  Partial<FieldProps>

  Extra props for the Field wrapper (orientation, labelAction...).

• defaultOpendefault false
  boolean

  Starts with the list open.

• open
  boolean

  Controls the list's open state.

• onOpenChange
  (open: boolean) => void

  Called when the list opens or closes.

• responsivedefault true
  boolean

  A bottom sheet below 768px instead of the popover.

• sheetTitledefault ""
  string

  The phone sheet title. Default: the label text, else "Country" ("Countries" with multiple).

• sidedefault "bottom"
  "top" | "right" | "bottom" | "left"

  Where the popover opens; it flips when there is no room.

• aligndefault "start"
  "start" | "center" | "end"

  How the popover lines up with the field.

• maxHeightdefault 360
  number

  The popover's tallest height in px (it also stops at the screen edge).

• virtualThresholddefault 100
  number

  Above this many rows only the rows in view render, so the full list scrolls smoothly.

• container
  HTMLElement | null

  Where the popover and sheet portal to. Default: document.body.

• classNames
  Partial<Record<"field" | "label" | "description" | "error" | "counter" | "box" | "trigger" | "value" | "placeholder" | "icon" | "chevron" | "clear" | "content" | "search" | "list" | "item" | "group" | "empty" | "chips" | "chip" | "overflow" | "summary" | "footer" | "flag" | "dialCode", string>>

  Extra classes for the inner parts: the Select (or MultiSelect) slots plus flag and dialCode.

• className
  string

  Merged onto the Field root when there is a label, description or error, otherwise onto the box.

• ref
  RefObject<HTMLButtonElement | null> or (node) => void

  The trigger button; other button props (onBlur, aria-*, data-*, form) land there too.

Parts

FAQ

More React input components