Address Form
A shipping or billing address form that changes with the country. Handles address search, postal codes, saved addresses and error summaries.
Address Form asks for an address the way the shopper’s country writes it. A US address gets City, State and ZIP code on one row, the UK gets Town or city and Postcode with no state, Germany puts the postal code before the city, and Japan starts with the postal code and prefecture. Sixteen countries have their own format with labels, required fields, region lists and postal rules, and every other country gets a plain fallback.
Fewer fields come first. Full name is one field, Company and Apartment sit behind small links, and the phone is optional with the reason under it. Every input has the right autocomplete token with a shipping or billing prefix, the right keyboard on phones and a name, so browser autofill fills the whole form at once, including the hidden apartment field.
Errors show when you leave a field, then update as you type until it’s fixed, and they say what’s wrong: “Enter a 5-digit ZIP code”, “Enter a postcode like SW1A 1AA”. validate() lists every problem in a summary at the top with links to the fields and moves focus there. Switching country keeps what still fits, clears regions that don’t, and re-checks only fields you’ve already visited, while the form’s height animates to the new layout.
Pass onSearchAddress and onResolveAddress to suggest addresses as the shopper types, with Enter address manually always at the end of the list. onLookupPostalCode fills city and region from a postal code without overwriting anything typed. SavedAddresses lists a signed-in shopper’s addresses with a Default badge, and AddressSummary is the one-line Ship to row for a finished checkout step.
Obtenha o HextaUI Pro
Um único pagamento libera todos os blocos, incluindo os futuros. Ver preços.
Adicione o registro Pro ao components.json
components.json Adicione seu token
Crie um token na sua página de conta e coloque-o em
.env.localcomoHEXTAUI_PRO_TOKEN.Adicione o bloco
pnpm dlx shadcn@latest add @hextaui-pro/address-form
Address search with Google Places
onSearchAddress returns suggestions for what’s typed and onResolveAddress turns the picked one into an Address. The same two calls map onto Mapbox Search Box’s /suggest and /retrieve. Both get an AbortSignal, so stale requests are cancelled.
Save to a Shopify customer account
validate() returns the errors and focuses the summary, so saving only runs on a complete address. The Address maps to customerAddressCreate field by field, and a userError from Shopify shows under the form.
A billing section
Billing defaults to the shipping address and shows it as one line. Unticking the box opens a second form with section="billing", so browsers autofill billing tokens there instead of shipping ones.
Anatomia
As partes que você compõe, de fora para dentro.
| Parte | Descrição |
|---|---|
AddressForm | The country-aware fields, the error summary and the address search. |
SavedAddresses | Saved addresses as radio cards, with Use a new address revealing the form. |
AddressSummary | The completed-step row: Ship to, the address on one line and Change. |
getCountryFormat, validateAddress, formatAddressLines | Country rules, validation and formatting that also work on the server. |
AddressForm
Also takes div props.
| Prop | Tipo | Padrão |
|---|---|---|
valueThe address when controlled. | Address | – |
defaultValueThe starting address when uncontrolled. | Partial<Address> | – |
onValueChangeCalled on every change. Regions are codes for countries with a list, such as CA or JP-13. | (address: Address) => void | – |
sectionPrefix for autocomplete tokens and field names. | "shipping" | "billing" | "shipping" |
countriesISO codes shoppers can pick, sorted by name. Defaults to every country. | string[] | – |
defaultCountryThe starting country when the value has none. | string | "US" |
phoneWhether to ask for a phone number. | "optional" | "required" | "hidden" | "optional" |
companyOffer Add company. | boolean | true |
onSearchAddressSuggest addresses as the shopper types three or more characters. Throwing shows that search isn’t available. | (query, { country, signal }) => Promise<AddressSuggestion[]> | – |
onResolveAddressTurn a picked suggestion into an address. A different country switches the form. Throw to show your message under the field. | (id, { signal }) => Promise<Partial<Address>> | – |
onLookupPostalCodeFill empty city and region fields from a valid postal code. | (postalCode, { country, signal }) => Promise<{ city?; region? } | null> | – |
actionsRefvalidate() returns { field, message }[] and shows the summary, focus(field), setCountry(code) and reset(address). | Ref<AddressFormActions> | – |
labelsEvery word the form shows or announces. | Partial<AddressFormLabels> | – |
localeLocale for country names and sorting. | Intl.LocalesArgument | "en-US" |
disabledDisable every field. | boolean | – |
SavedAddresses
Also takes div props.
| Prop | Tipo | Padrão |
|---|---|---|
addressesSaved addresses in display order. | (Address & { id: string; isDefault?: boolean })[] | – |
valueThe chosen id, or "new". | string | – |
defaultValueStarts on the default address, the first one, or "new" when there are none. | string | – |
onValueChangeCalled when the choice changes. | (value: string, address?: SavedAddress) => void | – |
onEditShows an Edit button on each card. | (address: SavedAddress) => void | – |
allowNewShow Use a new address. | boolean | true |
childrenShown under the list while Use a new address is chosen, usually an AddressForm. | ReactNode | – |
labelsGroup name, Default, new address and edit wording. | Partial<SavedAddressesLabels> | – |
AddressSummary
Also takes div props.
| Prop | Tipo | Padrão |
|---|---|---|
addressThe address to show on one line. | Address | – |
labelThe row label. | string | "Ship to" |
onChangeShows Change. | () => void | – |
countryAdd the country name. | boolean | false |
| Prop | Tipo | Padrão |
|---|---|---|
idPassed to onResolveAddress. | string | – |
titleThe street line, shown first and put in the field when picked. | string | – |
descriptionThe rest, such as San Francisco, CA 94105. | string | – |
addressUsed directly when there’s no onResolveAddress. | Partial<Address> | – |
| Tecla | Ação |
|---|---|
| ArrowDownArrowUp | Moves through country or address suggestions. |
| Enter | Picks the highlighted country or address. |
| Escape | Closes the suggestions and keeps what you typed. |
| Tab | Moves through the fields in the country’s order. Hidden company and apartment fields are skipped until opened. |
- Every field has a visible label, and optional fields say Optional. Errors are linked with aria-invalid and aria-describedby and use text next to the red outline, never color alone.
- validate() moves focus to a summary titled There is a problem. Each item is a link worded like the inline error that focuses its field.
- Address search is an ARIA combobox. A polite live region says how many addresses were found, when the address was filled in, when a postal code filled the city and when the fields changed for a new country.
- Reveals and the country reflow animate height and fade, and turn off under reduced motion. Text fields use 16px text and a 48px height on touch screens.
Construído com
Os componentes gratuitos do HextaUI de que Address Form é feito. Cada um é instalado separadamente.
Código
11 arquivos, adicionados a components/blocks/address-form.