AddressField

A postal address whose fields, order and labels follow the country.

SourcePackage @weft-js/warp

Preview

tsx

import { AddressField } from '@weft-js/warp'export function Basic() {  return (    <AddressField label="Billing address" defaultValue={OFFICE} />  )}const OFFICE = { country: 'DE', lines: ['Torstraße 140'], locality: 'Berlin', postalCode: '10119' }

Installation

npm install @weft-js/warp

Usage

tsx

import { AddressField } from '@weft-js/warp'<AddressField label="Billing address" defaultValue={OFFICE} />

With suggestions

Type market in the street field. A provider adds suggestions, and people can always type it by hand.

tsx

import { AddressField } from '@weft-js/warp'export function Lookup() {  return (    <AddressField label="Shipping address" provider={streetProvider} countries={['US', 'CA']} />  )}const STREETS = [  { id: 'a', label: '548 Market Street', secondary: 'San Francisco, CA 94104', address: { country: 'US', lines: ['548 Market Street'], locality: 'San Francisco', region: 'CA', postalCode: '94104' } },  { id: 'b', label: '1 Infinite Loop', secondary: 'Cupertino, CA 95014', address: { country: 'US', lines: ['1 Infinite Loop'], locality: 'Cupertino', region: 'CA', postalCode: '95014' } },  { id: 'c', label: '350 Fifth Avenue', secondary: 'New York, NY 10118', address: { country: 'US', lines: ['350 Fifth Avenue'], locality: 'New York', region: 'NY', postalCode: '10118' } },]const streetProvider = {  suggest: (q: string) => Promise.resolve(STREETS.filter(s => s.label.toLowerCase().includes(q.toLowerCase()))),  resolve: (id: string) => Promise.resolve(STREETS.find(s => s.id === id)!.address),}

An error on one line

errors is keyed by line. Its value posts as JSON through name.

tsx

import { AddressField } from '@weft-js/warp'export function Errors() {  return (    <AddressField label="Billing address" defaultValue={OFFICE} errors={{ postalCode: 'This postal code doesn\'t match Berlin.' }} />  )}const OFFICE = { country: 'DE', lines: ['Torstraße 140'], locality: 'Berlin', postalCode: '10119' }

Billing details form

Use AddressField, PhoneField and CurrencySelect together in one form for billing details.

tsx

import { AddressField, Button, CurrencySelect, Grid, Input, PhoneField, Row, Stack, Text, Toaster, toast } from '@weft-js/warp'export function FormBilling() {  const pay = (e: Event) => {    e.preventDefault()    toast.show({ title: 'Billing details saved' })  }  return (    <>      <Stack as="form" gap="group" onSubmit={pay}>        <Text role="heading">Billing details</Text>        <Input label="Company" autocomplete="organization" defaultValue="weft GmbH" />        <AddressField label="Billing address" name="address" defaultValue={OFFICE} />        <Grid cols={2} gap="group">          <PhoneField label="Phone" name="phone" defaultCountry="DE" countries={TEAM_COUNTRIES} />          <CurrencySelect label="Currency" name="currency" preferred={NEAR_CURRENCIES} defaultValue="EUR" />        </Grid>        <Row justify="end"><Button type="submit">Save details</Button></Row>      </Stack>      <Toaster />    </>  )}const TEAM_COUNTRIES = ['US', 'GB', 'DE', 'FR', 'SE', 'JP', 'IN', 'BR']const NEAR_CURRENCIES = ['EUR', 'USD', 'GBP']const OFFICE = { country: 'DE', lines: ['Torstraße 140'], locality: 'Berlin', postalCode: '10119' }

When to use

Use it for

Billing and shipping addresses

Reach for something else

PlaceLookupInput, when you want a place on a map, not a postal address

Accessibility

Each line is a labelled input with the right autocomplete, so browsers can fill it.
If the provider fails or takes over 1.5 seconds, it falls back to typing by hand.

API Reference

Prop	Type	Default	Description
`value`	`Address \| State<Address \| null> \| null`	—	The address, or a `State` to bind.
`defaultValue`	`Address \| null`	—	The first address.
`label`	`string`	`'Address'`	The name of the whole group, for screen readers.
`provider`	`AddressProvider`	—	Where suggestions come from: `suggest` and `resolve`. warp ships none.
`countries`	`string[]`	—	Limits the country list.
`defaultCountry`	`string`	`'US'`	The country to start on.
`locale`	`string`	—	The language and region used to format values.
`name`	`string`	—	Posts the address as JSON.
`errors`	`Partial<Record<AddressPart, string>>`	—	A message per line, keyed `line1`, `postalCode` and so on.

Event	Type	Default	Description
`onValueChange`	`((v: Address \| null, reason: ChangeReason) => void)`	—	Hears the new address and why it changed.