Form design
International Address Form Design
A form that works for one country can fail for another. International address forms need flexible labels, field lengths, character handling, and validation rules that do not assume every address is written like a U.S. address.
Avoid hard-coded assumptions
- Do not require a state field for every country.
- Do not store postal codes as numbers.
- Do not remove spaces or hyphens from every postcode.
- Do not limit names and localities to ASCII characters.
- Do not assume every address has exactly three lines.
Use country-specific labels
A field called State may make sense for the United States, but Japan uses prefectures and the UK may use county, post town, and postcode. Labels should adapt to the selected country when possible.
Test display, not only submission
Address data appears in account pages, receipts, labels, admin screens, CSV exports, and emails. Test long fields, wrapped lines, mobile layouts, and copy behavior across all these surfaces.
Generate practical samples
Start with U.S., Japanese, and UK samples to test different postal code and address-line patterns.
A flexible field model
| Field | Storage guidance | Country behavior |
|---|---|---|
| Country | ISO country code plus localized display name | Controls labels, choices, and validation |
| Administrative area | Text or country-scoped code | State, province, prefecture, region, or absent |
| Postal code | Text, never a number | May contain leading zeros, spaces, letters, or hyphens |
| Address lines | At least two flexible text lines | Building and unit placement varies |
| Locality | Unicode text | City, town, district, ward, or municipality |
Country switch state machine
When a user changes country, update labels and choices immediately, but do not silently reshape free text. Clear incompatible coded values, such as a US state code, and preserve compatible fields, such as recipient and address lines. Revalidate only after the new country rules are loaded. This avoids the common bug where a hidden state value from the previous country is submitted.
Release evidence
For each supported market, keep one minimal case, one long case, one local-script case, one optional-field case, and one postal-code edge case. Record the rendered address, stored JSON, exported CSV row, and mobile screenshot. This creates evidence that the same value survives the complete product flow.
See the data and testing methodology for the site's coverage and limitations.