AddressField

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

SourcePackage @kerf-js/veneer

Preview

tsx

import { AddressField } from '@kerf-js/veneer'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 @kerf-js/veneer

Usage

tsx

import { AddressField } from '@kerf-js/veneer'<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 '@kerf-js/veneer'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) => {    const query = q.toLowerCase()    const matches = STREETS.filter(({ label }) =>      label.toLowerCase().includes(query),    )    return Promise.resolve(matches)  },  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 '@kerf-js/veneer'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 '@kerf-js/veneer'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="kerf 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`. Veneer 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.