Address input

InstallationCopy Anchor Link

Import the component in your screen:

import {
  AddressInput,
  type AddressValue,
} from '@commenda/pathfinder/address-input';

Load the stylesheet once in your app root, after host styles:

import '@commenda/pathfinder/styles.css';

Pathfinder ships precompiled CSS; no Tailwind setup is required. In Next.js App Router, put interactive state and callbacks in a client component. See installation for the workspace setup.

API referenceCopy Anchor Link

AddressValue contains six strings: country (ISO code), addressLine1, addressLine2, city, region, and postalCode. A name="address" produces fields named address.country, address.addressLine1, and so on. Uncontrolled values restore their defaults on form reset.

CountriesCopy Anchor Link

Pathfinder's available country codes and labels are bundled at build time. United States, Canada, India, United Kingdom, Singapore, United Arab Emirates, and Ireland appear first, followed by other countries sorted alphabetically by label. None, Other, and entries without a label are omitted. Empty allowedCountries means all available countries; exclusions always apply. Filtering preserves the canonical order.

Pathfinder owns the supported countries, labels, priority order, and region exclusions in packages/pathfinder/data/address-countries.json. Run pnpm --filter @commenda/pathfinder generate:address-countries after changing this file. Regional metadata comes from Pathfinder's pinned country-state-city build dependency. Generation does not read another workspace package.

Address suggestionsCopy Anchor Link

The example uses local demonstration data. Production applications supply suggestionsConfig with items, isLoading, resultsQuery, onQueryChange, and optional error. Each suggestion is { id, label, description?, address: AddressValue }.

The application owns requests, debouncing, cancellation, and credentials. Set resultsQuery to the query that produced the current items, not the latest input before its request finishes. Stale results are hidden until their query matches the typed street address. Selecting a suggestion fills all six fields. Suggestions outside the allowed country list cannot be selected. Search failure never prevents manual entry.

ValidationCopy Anchor Link

Country changes preserve all entered fields for review. State and region options default to the pinned country-state-city metadata, including Pathfinder's US territory exclusions. Countries with no metadata allow free-text entry. Applications can override the options with regionConfig; country-specific validation remains application-owned. Changing a country does not silently erase an address or select a region.

Design and implementation rulesCopy Anchor Link

• ADDRESS-001: Figma 292:9094 and 293:3032 establish the compact field treatment. Keep the approved stable order: country, street, optional line 2, city, region, postal code. Narrow layouts stack the fields.
• ADDRESS-002: Suggestions overlay the street field without moving the form. Manual editing remains available when search fails.
• ADDRESS-003: Preserve Pathfinder country availability, labels, and priority/alphabetical ordering. There is no private runtime dependency.
• ADDRESS-004: Preserve drafts on country changes; default regions follow the bundled metadata and application options override them. The application owns validation and requests.
• ADDRESS-005: Line 2 cannot be required. Preserve native autocomplete and form association for each field.
• ADDRESS-006: Only results matching the current street query can be selected.

These rules also live alongside the component implementation and are available through the Markdown endpoint, llms.txt, and llms-full.txt.

Shared rulesCopy Anchor Link

Labels activate the first input. Descriptions, disabled reasons, and validation messages stay associated with the field. Error icons center on the first 18px text line, including wrapped messages. Controlled values require callbacks; uncontrolled form resets restore defaults. Public props expose application values, never private primitive or calendar objects. Styles ship precompiled for React 18/19 and Next.js consumers.