# AddressInput

Page: /docs/components/address-input

{/* Figma: Meridian → AddressInput (docs 39:1814, component set 21:10426). Spec: docs/design-system/meridian/address-input.md */}

A postal address in one layout for every country. Start typing in line 1 and pick a suggestion, or fill the fields by hand. Nothing moves when the country changes. Every field is 40 high with a 16 value and a 14 label. On the site it appears on partner and event forms that ship something.

```tsx
import { AddressInput } from "@commenda/meridian/ui/address-input";
import type { ReactNode } from "react";

function Fields({ children, cols = 2 }: { children: ReactNode; cols?: 2 | 3 }) {
	return (
		<div
			className={`not-prose my-4 grid gap-6 rounded-xl border border-fd-border bg-white p-8 ${
				cols === 3 ? "md:grid-cols-3" : "md:grid-cols-2"
			}`}
		>
			{children}
		</div>
	);
}

const EMPTY_ADDRESS = {
	country: "US",
	addressLine1: "",
	addressLine2: "",
	city: "",
	region: "",
	postalCode: "",
};

const FILLED_ADDRESS = {
	country: "US",
	addressLine1: "350 Fifth Avenue",
	addressLine2: "Suite 4100",
	city: "New York",
	region: "NY",
	postalCode: "10118",
};

export function AddressLayout() {
	return (
		<Fields>
			<AddressInput label="Mailing address" defaultValue={EMPTY_ADDRESS} />
			<AddressInput label="Mailing address" defaultValue={FILLED_ADDRESS} />
		</Fields>
	);
}
```

## Usage [#usage]

```tsx
import { AddressInput } from "@commenda/meridian/ui/address-input";

<AddressInput label="Mailing address" value={address} onValueChange={setAddress} />;
```

## One layout for every country [#one-layout-for-every-country]

Country, two address lines, then City beside Postal code, and State or region on its own row, wide enough for long region names. The same fields in the same places whatever the country; only the examples and the validation follow it. Line 2 is optional.

```tsx
import { AddressInput } from "@commenda/meridian/ui/address-input";
import type { ReactNode } from "react";

function Fields({ children, cols = 2 }: { children: ReactNode; cols?: 2 | 3 }) {
	return (
		<div
			className={`not-prose my-4 grid gap-6 rounded-xl border border-fd-border bg-white p-8 ${
				cols === 3 ? "md:grid-cols-3" : "md:grid-cols-2"
			}`}
		>
			{children}
		</div>
	);
}

const EMPTY_ADDRESS = {
	country: "US",
	addressLine1: "",
	addressLine2: "",
	city: "",
	region: "",
	postalCode: "",
};

const FILLED_ADDRESS = {
	country: "US",
	addressLine1: "350 Fifth Avenue",
	addressLine2: "Suite 4100",
	city: "New York",
	region: "NY",
	postalCode: "10118",
};

export function AddressLayout() {
	return (
		<Fields>
			<AddressInput label="Mailing address" defaultValue={EMPTY_ADDRESS} />
			<AddressInput label="Mailing address" defaultValue={FILLED_ADDRESS} />
		</Fields>
	);
}
```

## Suggestions [#suggestions]

Typing in line 1 opens suggestions over the fields below it, so nothing is pushed down: the street as the label, then city, region, code and country, a pin before each. Picking one fills every field in place for review. Wire it with `suggestionsConfig` to your address lookup.

## Errors [#errors]

Each field shows its own error under it, after the person leaves the field. The postal code error uses the country’s word for it.

```tsx
import { AddressInput } from "@commenda/meridian/ui/address-input";
import type { ReactNode } from "react";

function Fields({ children, cols = 2 }: { children: ReactNode; cols?: 2 | 3 }) {
	return (
		<div
			className={`not-prose my-4 grid gap-6 rounded-xl border border-fd-border bg-white p-8 ${
				cols === 3 ? "md:grid-cols-3" : "md:grid-cols-2"
			}`}
		>
			{children}
		</div>
	);
}

const FILLED_ADDRESS = {
	country: "US",
	addressLine1: "350 Fifth Avenue",
	addressLine2: "Suite 4100",
	city: "New York",
	region: "NY",
	postalCode: "10118",
};

export function AddressErrors() {
	return (
		<Fields>
			<AddressInput
				label="Mailing address"
				defaultValue={{ ...FILLED_ADDRESS, postalCode: "1011" }}
				fieldErrors={{ postalCode: "Use 5 digits." }}
			/>
		</Fields>
	);
}
```

## Anatomy [#anatomy]

Every field is an Input: 40 high, radius 8, 16 value, 14 label, 16 between rows and 12 between the two columns.

## API reference [#api-reference]

| Prop | Type | Description |
| --- | --- | --- |
| `label` (conditional) | `string` |  |
| `hideLabel` | `boolean` |  |
| `aria-label` (conditional) | `string` |  |
| `value` (conditional) | `AddressValue` |  |
| `onValueChange` (conditional) | `(value: AddressValue) => void` |  |
| `defaultValue` | `AddressValue` |  |
| `id` | `string` |  |
| `name` | `string` |  |
| `form` | `string` |  |
| `className` | `string` |  |
| `description` | `string` |  |
| `aria-describedby` | `string` |  |
| `readOnly` | `boolean` |  |
| `disableConfig` | `{ isDisabled: boolean; reason?: string; }` |  |
| `countryConfig` | `AddressCountryConfig` |  |
| `regionConfig` | `{ options: readonly ChoiceOption[]; }` |  |
| `requiredFields` | `readonly ("country" \| "addressLine1" \| "city" \| "region" \| "postalCode")[]` |  |
| `fieldErrors` | `Partial<Record<keyof AddressValue, string>>` |  |
| `suggestionsConfig` | `AddressSuggestionsConfig` |  |

**`value` fields**

| Field | Type | Description |
| --- | --- | --- |
| `country` (required) | `string` |  |
| `addressLine1` (required) | `string` |  |
| `addressLine2` (required) | `string` |  |
| `city` (required) | `string` |  |
| `region` (required) | `string` |  |
| `postalCode` (required) | `string` |  |

**`defaultValue` fields**

| Field | Type | Description |
| --- | --- | --- |
| `country` (required) | `string` |  |
| `addressLine1` (required) | `string` |  |
| `addressLine2` (required) | `string` |  |
| `city` (required) | `string` |  |
| `region` (required) | `string` |  |
| `postalCode` (required) | `string` |  |

**`disableConfig` fields**

| Field | Type | Description |
| --- | --- | --- |
| `isDisabled` (required) | `boolean` |  |
| `reason` | `string` |  |

**`countryConfig` fields**

| Field | Type | Description |
| --- | --- | --- |
| `allowedCountries` | `readonly ("AD" \| "AE" \| "AF" \| "AG" \| "AL" \| "AM" \| "AO" \| "AR" \| "AT" \| "AU" \| "AZ" \| "BA" \| "BB" \| "BD" \| "BE" \| "BF" \| "BG" \| "BH" \| "BI" \| "BJ" \| "BN" \| "BO" \| "BR" \| "BS" \| "BT" \| "BW" \| "BY" \| "BZ" \| "CA" \| "CD" \| "CF" \| "CG" \| "CH" \| "CI" \| "CK" \| "CL" \| "CM" \| "CN" \| "CO" \| "CR" \| "CU" \| "CV" \| "CY" \| "CZ" \| "DE" \| "DJ" \| "DK" \| "DM" \| "DO" \| "DZ" \| "EC" \| "EE" \| "EG" \| "ER" \| "ES" \| "ET" \| "FI" \| "FJ" \| "FM" \| "FR" \| "GA" \| "GB" \| "GD" \| "GE" \| "GH" \| "GM" \| "GN" \| "GQ" \| "GR" \| "GT" \| "GW" \| "GY" \| "HN" \| "HR" \| "HT" \| "HU" \| "ID" \| "IE" \| "IL" \| "IN" \| "IQ" \| "IR" \| "IS" \| "IT" \| "JE" \| "JM" \| "JO" \| "JP" \| "KE" \| "KG" \| "KH" \| "KI" \| "KM" \| "KN" \| "KR" \| "KW" \| "KY" \| "KZ" \| "LA" \| "LB" \| "LC" \| "LI" \| "LK" \| "LR" \| "LS" \| "LT" \| "LU" \| "LV" \| "LY" \| "MA" \| "MC" \| "MD" \| "ME" \| "MG" \| "MH" \| "MK" \| "ML" \| "MM" \| "MN" \| "MR" \| "MT" \| "MU" \| "MV" \| "MW" \| "MX" \| "MY" \| "MZ" \| "NA" \| "NE" \| "NG" \| "NI" \| "NL" \| "NO" \| "NP" \| "NR" \| "NZ" \| "OM" \| "PA" \| "PE" \| "PG" \| "PH" \| "PK" \| "PL" \| "PR" \| "PT" \| "PW" \| "PY" \| "QA" \| "RO" \| "RS" \| "RU" \| "RW" \| "SA" \| "SB" \| "SC" \| "SD" \| "SE" \| "SG" \| "SI" \| "SK" \| "SL" \| "SM" \| "SN" \| "SO" \| "SR" \| "SS" \| "ST" \| "SV" \| "SY" \| "SZ" \| "TD" \| "TG" \| "TH" \| "TJ" \| "TL" \| "TM" \| "TN" \| "TO" \| "TR" \| "TT" \| "TV" \| "TW" \| "TZ" \| "UA" \| "UG" \| "US" \| "UY" \| "UZ" \| "VA" \| "VC" \| "VE" \| "VG" \| "VN" \| "VU" \| "WS" \| "YE" \| "ZA" \| "ZM" \| "ZW")[]` |  |
| `excludedCountries` | `readonly ("AD" \| "AE" \| "AF" \| "AG" \| "AL" \| "AM" \| "AO" \| "AR" \| "AT" \| "AU" \| "AZ" \| "BA" \| "BB" \| "BD" \| "BE" \| "BF" \| "BG" \| "BH" \| "BI" \| "BJ" \| "BN" \| "BO" \| "BR" \| "BS" \| "BT" \| "BW" \| "BY" \| "BZ" \| "CA" \| "CD" \| "CF" \| "CG" \| "CH" \| "CI" \| "CK" \| "CL" \| "CM" \| "CN" \| "CO" \| "CR" \| "CU" \| "CV" \| "CY" \| "CZ" \| "DE" \| "DJ" \| "DK" \| "DM" \| "DO" \| "DZ" \| "EC" \| "EE" \| "EG" \| "ER" \| "ES" \| "ET" \| "FI" \| "FJ" \| "FM" \| "FR" \| "GA" \| "GB" \| "GD" \| "GE" \| "GH" \| "GM" \| "GN" \| "GQ" \| "GR" \| "GT" \| "GW" \| "GY" \| "HN" \| "HR" \| "HT" \| "HU" \| "ID" \| "IE" \| "IL" \| "IN" \| "IQ" \| "IR" \| "IS" \| "IT" \| "JE" \| "JM" \| "JO" \| "JP" \| "KE" \| "KG" \| "KH" \| "KI" \| "KM" \| "KN" \| "KR" \| "KW" \| "KY" \| "KZ" \| "LA" \| "LB" \| "LC" \| "LI" \| "LK" \| "LR" \| "LS" \| "LT" \| "LU" \| "LV" \| "LY" \| "MA" \| "MC" \| "MD" \| "ME" \| "MG" \| "MH" \| "MK" \| "ML" \| "MM" \| "MN" \| "MR" \| "MT" \| "MU" \| "MV" \| "MW" \| "MX" \| "MY" \| "MZ" \| "NA" \| "NE" \| "NG" \| "NI" \| "NL" \| "NO" \| "NP" \| "NR" \| "NZ" \| "OM" \| "PA" \| "PE" \| "PG" \| "PH" \| "PK" \| "PL" \| "PR" \| "PT" \| "PW" \| "PY" \| "QA" \| "RO" \| "RS" \| "RU" \| "RW" \| "SA" \| "SB" \| "SC" \| "SD" \| "SE" \| "SG" \| "SI" \| "SK" \| "SL" \| "SM" \| "SN" \| "SO" \| "SR" \| "SS" \| "ST" \| "SV" \| "SY" \| "SZ" \| "TD" \| "TG" \| "TH" \| "TJ" \| "TL" \| "TM" \| "TN" \| "TO" \| "TR" \| "TT" \| "TV" \| "TW" \| "TZ" \| "UA" \| "UG" \| "US" \| "UY" \| "UZ" \| "VA" \| "VC" \| "VE" \| "VG" \| "VN" \| "VU" \| "WS" \| "YE" \| "ZA" \| "ZM" \| "ZW")[]` |  |

**`regionConfig` fields**

| Field | Type | Description |
| --- | --- | --- |
| `options` (required) | `readonly ChoiceOption[]` |  |

**`suggestionsConfig` fields**

| Field | Type | Description |
| --- | --- | --- |
| `items` (required) | `readonly AddressSuggestion[]` |  |
| `isLoading` (required) | `boolean` |  |
| `error` | `string` |  |
| `resultsQuery` (required) | `string` | Query that produced the supplied items; stale results cannot be selected. |
| `onQueryChange` (required) | `(query: string) => void` |  |

## Best practices [#best-practices]

- Keep the layout fixed: changing the country never adds, removes or moves fields.
- Default the country to the visitor’s location and let people change it. Countries lead with their flag.
- Offer suggestions in line 1, and let people ignore them and type every field.
- Open suggestions over the form, never between fields.
- Make line 2 optional. Never split house number, street and unit into separate fields.
- Validate postal codes for the chosen country and say so in its words ("Enter a valid PIN code").
- In code, each field carries its autocomplete attribute: country, address-line1, address-line2, address-level2, address-level1, postal-code. Map each to its HubSpot property.
- Source: Pathfinder AddressInput. Meridian makes every field 40 tall with a 16 value and a 14 label.
