# Country Search

> A cartographic country-search combobox that live-filters twenty states by name, capital, region, or ISO code into a grouped listbox with flag stamp wells, mark highlighting, relevance ranking, recent routes, skeleton loading, and full keyboard control — token-driven and design-system agnostic.

- Category: Filter
- Frameworks: Vanilla, React + CSS, React + Tailwind
- Design system: Vector
- Dark mode: yes
- Access: premium (Atheros AI Pass)
- Tags: search, combobox, typeahead
- Page: https://builder.atheros.ai/components/country-search
- Preview: https://d17nmjscumqk5d.cloudfront.net/builder/templates/tpl_builder_country_search/preview-b845416bc945.webp

## Features

- WAI-ARIA combobox/listbox pattern with `aria-expanded`, `aria-controls`, `aria-autocomplete`, and `aria-activedescendant`
- Debounced multi-field filtering over name, capital, region, and ISO 3166 alpha-2/alpha-3 codes with relevance ranking — name prefix beats substring, codes beat capital, capital beats region
- Matched-substring highlighting built with safe DOM nodes and a `<mark>` element across every searchable field
- Region-grouped browse mode with meridian group headers (dashed rule + tabular count) when the query is empty
- Flag stamp wells that flip to a solid accent check stamp on selection — a passport-stamp micro-interaction
- Dashed mono ISO chips and tabular-nums population meta on every row
- Recent routes persisted to `localStorage` (max 5) with a Clear control
- Skeleton shimmer rows while the async data source resolves
- Empty state with a Tabler icon and a search-hint caption when nothing matches
- Full keyboard support: ArrowUp/ArrowDown with wrap, Home/End, Enter, Escape close-then-clear
- `/` and Cmd/Ctrl+K focus shortcuts with a visible `/` hint chip
- Focus scan-line under the field, globe icon tilt, and a soft cascade row entrance
- Polite live region announcing result counts and selection
- Full dark-mode token set driven by a host-shell `body.dark` class — no built-in toggle

## Accessibility

- **Combobox** — `role="combobox"` with `aria-expanded`, `aria-controls`, `aria-autocomplete`
- **Active option** — `aria-activedescendant` references the active option id
- **Listbox** — `role="listbox"` with `role="option"` items and `aria-selected`
- **Group headers** — `role="presentation"` rows excluded from option navigation
- **Keyboard nav** — Arrow keys with wrap, Home/End, Enter, Escape
- **Focus indicators** — `:focus-visible` with `--ring` outline on all elements
- **Reduced motion** — `prefers-reduced-motion: reduce` disables all animations
- **Live regions** — `aria-live="polite"` announcing result counts and selection

## Keyboard shortcuts

- `/` — Focus the search input
- `Cmd/Ctrl + K` — Focus and select the search input
- `ArrowDown` — Move to next option (wraps)
- `ArrowUp` — Move to previous option (wraps)
- `Home` — Move to first option
- `End` — Move to last option
- `Enter` — Select the active option
- `Escape` — Close the panel, then clear the input

## Common questions

**Which frameworks is Country Search available in?**

Country Search ships as Vanilla, React + CSS and React + Tailwind — HTML, CSS, JS and React source you can copy, download or clone into Atheros AI Builder.

**Is the Country Search filter component free?**

Country Search is a premium component. Anyone can preview it; the source, downloads and AI customisation are included with Atheros AI Pass.

**Does Country Search support dark mode?**

Yes. Country Search ships light and dark themes, both drawn from the Vector design system's tokens. Switch the preview to dark mode to compare them.

## Get the code

Preview Country Search live, then sign in to copy or download the source, apply another design system, or ask the AI assistant to change it: https://builder.atheros.ai/components/country-search

Every component on https://builder.atheros.ai is also reachable from Claude Code, Cursor and Codex through the Atheros MCP server (paid plans). Component index: https://builder.atheros.ai/llms-components.txt