Region Selector

Overview

The region selector is a searchable combobox for picking a country or region. A trigger pill shows the current selection as a circular flag plus its name; opening it reveals an anchored popover with a search field and a keyboard-navigable list of every region. It ships with the full ISO 3166-1 set of 245 regions out of the box.

Type to filter by name or two-letter code, arrow through the results, and press Enter to choose. Use it anywhere a form needs a country or region field: billing, shipping, account settings, or onboarding.

Installation

Import the pattern from loosethreads:

import { RegionSelector } from "@pulp/loosethreads/patterns"

Usage

Hold the selected code in state and pass it as value, then update it from onChange. The value is the region's lowercase ISO alpha-2 code, e.g. "us":

import { RegionSelector } from "@pulp/loosethreads/patterns"
import { useState } from "react"

function RegionField() {
  const [region, setRegion] = useState("us")

  return (
    <RegionSelector
      value={region}
      onChange={setRegion}
      placeholder="Search by country or region"
    />
  )
}

Props

Anatomy

The control has two parts. The trigger is a pill holding the selected flag, the region name, and a chevron that rotates when the popover opens. The popover, anchored directly beneath the trigger, stacks a search field over a scrollable list; each row shows a flag and name, and the current selection is marked with an iris-magenta label and a check.

Flags load lazily from a remote source. Each flag is a plain lazily-loaded img from flagcdn.com, so first paint does not wait on the full set. Make sure your content policy allows that origin, or swap in your own flag assets.

Accessibility

• Combobox semantics. The trigger is a role="combobox" with aria-haspopup="listbox", an aria-expanded that tracks the open state, and an aria-label that announces the current selection.
• Listbox and options. The results render as a role="listbox"; each row is a role="option" and the chosen region carries aria-selected. The search field is labelled and wired to the list with aria-controls.
• Keyboard. Opening the popover moves focus to the search field. Arrow Down and Arrow Up move a highlighted active row, keeping it scrolled into view; Enter selects it; Escape closes the popover. A click outside also closes it.
• Selected state. The active selection is exposed through aria-selected and reinforced visually with an iris-magenta name and a check mark.