Address entry

Problem Context

• The address may be used for delivery, billing, correspondence, jurisdiction, eligibility, tax, identity proofing, emergency routing, or service availability.
• Users may have flats, suites, rural routes, military addresses, new builds, international addresses, post-office boxes, care-of details, organization names, or addresses not present in lookup data.
• Address lookup, autocomplete, geocoding, and validation services can be incomplete, region-limited, stale, or capable of suggesting corrections that still need user confirmation.
• Downstream systems often need address components for shipping labels, postal validation, fraud checks, official notices, matching, and customer support.

Selection Rules

• Choose address entry when the product needs a complete postal, delivery, billing, contact, or official address rather than one short freeform value.
• Use address lookup as an accelerator for covered regions, not as the only valid path.
• Use multiple text inputs when the product needs separate address parts for validation, delivery, reporting, or integration.
• Use a textarea only when the system genuinely stores an address block and does not need separate parts.
• Use autocomplete as a lookup mechanism only when users still choose a suggestion and can edit the populated address parts.
• Use dependent fields for country-to-state or country-to-postal-code rules inside address entry, not as a replacement for the complete address flow.
• Accept common postal-code spacing, casing, and punctuation variations before showing an error.
• Make optional county, province, state, organization, and line 2 fields truly optional unless the selected country or delivery method requires them.
• Do not force UK, U.S., or domestic address structure on international users.
• Preserve secondary unit, flat, suite, room, floor, care-of, and organization information through lookup, validation, edit, and review.
• Show validation corrections as proposed changes that users can accept, edit, or override when their real address cannot be verified.
• Treat an address change as consequential when it affects delivery, eligibility, taxes, payment, identity, or official correspondence, and route it through review before submit.

Required States

• Initial state with country or domestic coverage explained and lookup or manual entry available.
• Lookup query state accepting postal-code spacing, casing, and common punctuation variations.
• Lookup results state showing multiple distinguishable addresses and requiring user selection.
• Address not found state with manual entry and support guidance instead of a dead end.
• Selected address state expanded into editable structured fields.
• Manual entry state with address line, town or city, region when needed, postal code, and country fields.
• Country changed state where labels, required fields, and validation rules adapt and stale region values are cleared or reviewed.
• Secondary unit present state preserving apartment, flat, suite, room, or organization details.
• Field-specific error state for missing line, locality, postal code, or unsupported country.
• Validation correction state showing suggested normalized address and original user entry.
• Override or unverified state that records user confirmation when validation data cannot prove a real address.
• Submitted structured payload state with address parts ready for review or downstream integration.

Interaction Contract

• Users can start with lookup or choose manual entry before providing a postal code.
• Lookup results are not committed until the user chooses a specific address.
• Selecting a suggestion populates editable fields rather than locking the address.
• Manual entry preserves any previously entered lookup query and address parts where they still apply.
• Changing country updates labels, required fields, postal-code rules, autocomplete tokens, and stale region values together.
• Validation errors identify the exact address part that needs correction and preserve all other typed fields.
• Verification suggestions are shown as review choices, not silent replacements.
• Submitting the address stores structured parts and any verification status needed for review, fulfillment, or support.

Implementation Checklist

• Define which address parts are required for each supported country, delivery method, and downstream integration before designing the form.
• Use stable names and browser autocomplete tokens such as address-line1, address-line2, address-level2, postal-code, and country-name for structured fields.
• Provide an address lookup only for regions where its data is suitable, and state that coverage near the lookup control.
• Add a visible Enter manually option before and after failed lookup results.
• Do not store only the display label returned by a lookup provider; map selected or typed values into canonical address parts.
• Keep apartment, suite, flat, unit, floor, building, organization, and care-of details editable after lookup and validation.
• Normalize casing, spacing, and postal-code punctuation only when the user can still see and correct the result.
• Validate line, locality, postal code, region, and country according to the selected country and server-side rules.
• Record validation confidence, correction choice, override reason, and original user entry when address verification can affect fulfillment.
• Test keyboard use, screen reader labels, browser autofill, mobile address keyboards, long addresses, international addresses, address-not-found paths, saved drafts, browser Back, and review-before-submit flows.

Common Generated-UI Mistakes

• Forcing every address through a domestic postcode or ZIP lookup.
• Using one single-line text input when the business process needs city, postal code, country, or delivery line separately.
• Discarding apartment, suite, flat, unit, room, floor, or organization details after lookup selection.
• Automatically choosing the first lookup result without explicit selection.
• Treating autocomplete as proof that an address is valid or deliverable.
• Silently replacing user-entered address parts with a geocoded or validated suggestion.
• Making county, state, or region required even when the selected country or postal authority does not require it.
• Rejecting valid postal-code spacing, casing, punctuation, rural route, military, or new-build addresses without override.
• Hiding manual entry until after several failed lookup attempts.
• Using placeholder text as the only field label for address lines.

Critique Questions

• Which downstream system needs each captured address part, and which parts are required by country?
• Can users complete the task if the lookup service is unavailable or their address is missing?
• Does the UI preserve apartment, suite, organization, rural route, or care-of details through every state?
• Are lookup suggestions distinguishable enough that users can choose the correct property?
• What happens when validation proposes a correction that conflicts with the user's real address?
• Does changing country update labels, autocomplete tokens, required fields, and validation together?
• Will the captured address be reviewed before a consequential submit action?