So baust du in React ein Adressformular, das in jedem Land funktioniert

Zuerst das Land, dann das Layout

Das Land entscheidet, welche Felder es gibt, wie sie heißen, welche Pflicht sind und in welcher Reihenfolge sie stehen. Frag also zuerst nach dem Land, vorausgewählt anhand von Locale oder IP der Kundin, und bau den Rest aus Daten auf.

Ein paar Beispiele dafür, wie viel sich ändert:

Du musst nicht jedes Land von Hand recherchieren. Google veröffentlicht die Adress-Metadaten hinter seiner Bibliothek libaddressinput, mit Feldreihenfolge, Labels, Pflichtfeldern und Postleitzahlmustern für den Großteil der Welt. Nimm die Länder, in die du am meisten lieferst, und gib ihnen ein exaktes Format, und gib jedem anderen Land einen schlichten Fallback: zwei Adresszeilen, Stadt, Region und Postleitzahl, keine davon streng validiert.

type Field = "address1" | "address2" | "city" | "region" | "postalCode"

type CountryFormat = {
  rows: Field[][]
  labels: Partial<Record<Field, string>>
  required: Field[]
  postalCode?: { pattern: RegExp; example: string }
  regions?: { code: string; name: string }[]
}

const countryFormats: Record<string, CountryFormat> = {
  US: {
    rows: [["address1"], ["address2"], ["city", "region", "postalCode"]],
    labels: { region: "State", postalCode: "ZIP code" },
    required: ["address1", "city", "region", "postalCode"],
    postalCode: { pattern: /^\d{5}(-\d{4})?$/, example: "94110" },
  },
  GB: {
    rows: [["address1"], ["address2"], ["city"], ["postalCode"]],
    labels: { city: "Town or city", postalCode: "Postcode" },
    required: ["address1", "city", "postalCode"],
    postalCode: {
      pattern: /^[A-Z]{1,2}\d[A-Z\d]? ?\d[A-Z]{2}$/i,
      example: "SW1A 1AA",
    },
  },
}

Die Formular-Komponente rendert dann format.rows und erwähnt nie ein Land beim Namen.

Weniger Felder

Jedes Feld, das du zeigst, ist eine Sache mehr zum Ausfüllen und eine Sache mehr, die schiefgehen kann.

• Ein Namensfeld. „Vollständiger Name“, nicht Vor- und Nachname. Viele Namen lassen sich nicht in zwei Teile zerlegen, und die Reihenfolge ist von Land zu Land unterschiedlich.
• Zeile 2 hinter einem Link. „Wohnung, Etage usw. hinzufügen“ öffnet sie. Die meisten brauchen sie nicht. Wenn Autofill oder die Adresssuche sie ausfüllt, zeig sie an.
• Firma ebenfalls hinter einem Link, für die wenigen B2B-Bestellungen.
• Telefon optional, mit Begründung. „Nur für Rückfragen zur Lieferung“ unter dem Feld bringt mehr Nummern ein, als ein Pflichtfeld echte Nummern einbringt.

Autofill erledigt das meiste

Browser-Autofill kann das ganze Formular mit einem Tippen ausfüllen, aber nur, wenn jedes Input einen name und das richtige autocomplete-Token hat. Stell den Tokens shipping oder billing voran, damit der Browser weiß, welche gespeicherte Adresse wohin gehört:

<Input name="name" autoComplete="shipping name" />
<Input name="address1" autoComplete="shipping address-line1" />
<Input name="address2" autoComplete="shipping address-line2" />
<Input name="city" autoComplete="shipping address-level2" />
<Input name="region" autoComplete="shipping address-level1" />
<Input
  name="postalCode"
  autoComplete="shipping postal-code"
  inputMode={country === "US" ? "numeric" : "text"}
/>
<Input name="phone" type="tel" autoComplete="shipping tel" />

address-level1 ist der Bundesstaat, die Provinz oder die Präfektur, und address-level2 ist die Stadt. Weicht die Rechnungsadresse von der Lieferadresse ab, rendere ein zweites Formular mit billing-Tokens, damit der Browser das Rechnungsformular nicht mit der Lieferadresse ausfüllt.

Nutz kein type="number" für Postleitzahlen. ZIP-Codes beginnen mit Nullen, britische und kanadische Codes enthalten Buchstaben, und Number-Inputs bringen Spinner und Änderungen per Scrollrad mit. Nutz einen Text-Input mit inputMode="numeric" nur dort, wo Codes rein aus Ziffern bestehen.

Postleitzahl-Abfrage

In manchen Ländern verrät die Postleitzahl schon Stadt und Region. Japan ist das klassische Beispiel: Adressen beginnen mit der Postleitzahl, und der Code allein bestimmt Präfektur und Stadt. Wenn die Kundin die Postleitzahl fertig eingegeben hat, schlag sie nach und fülle Stadt und Region aus, aber überschreib nie etwas, das sie schon getippt hat. Ihre Eingabe hat Vorrang vor deinen Daten.

Adresssuche

Die Adresssuche, also den Anfang einer Adresse tippen und einen Vorschlag auswählen, ist auf dem Smartphone schneller als jedes Formular. Google Places und Mapbox bieten sie beide als zwei Aufrufe an: einer, der Adressen zum Getippten vorschlägt, und einer, der den gewählten Vorschlag in strukturierte Felder umwandelt.

Ein paar Regeln für die Anbindung:

• Warte auf eine Tipp-Pause und brich die vorherige Anfrage ab, wie bei jedem Suchfeld.
• Beende die Liste immer mit „Adresse manuell eingeben“. Die Straße ist vielleicht neu, oder der Vorschlag ist falsch.
• Fülle nach der Auswahl die Felder aus und zeig sie an, damit die Kundin das Ergebnis prüfen und eine Wohnungsnummer ergänzen kann.
• Die Places API von Google nutzt Session-Tokens, um die Vorschlags- und Detail-Aufrufe einer Suche zu bündeln. Nutz sie, sonst werden die Aufrufe womöglich einzeln abgerechnet.

Fehler, die sagen, was falsch ist

Validiere ein Feld, wenn die Kundin es verlässt, und dann live beim Tippen, bis es korrigiert ist. Schreib den Fehler für das jeweilige Land: „Gib einen 5-stelligen ZIP-Code ein“ in den USA, „Gib eine Postleitzahl wie SW1A 1AA ein“ im Vereinigten Königreich. „Ungültige Postleitzahl“ hilft niemandem.

Liste beim Absenden jedes Problem in einer Zusammenfassung oben im Formular auf, verlinke jedes mit seinem Feld und setz den Fokus auf die Zusammenfassung. Verbinde jeden Fehler per aria-describedby mit seinem Input und setz aria-invalid, damit Screenreader die Meldung zusammen mit dem Feld vorlesen.

Normalisiere, bevor du validierst: Leerzeichen entfernen, britische und kanadische Postleitzahlen in Großbuchstaben umwandeln und sie mit oder ohne Leerzeichen akzeptieren. „sw1a1aa“ abzulehnen, obwohl du es korrigieren könntest, ist dein Bug, nicht der der Kundin.

Land wechseln

Leute ändern das Land öfter, nachdem sie schon die halbe Adresse getippt haben, als man denkt. Passiert das, behalte, was noch passt (Name, Straßenzeilen, Telefon), leere die Region, wenn das neue Land eine andere Liste hat, und prüfe nur die Felder erneut, die schon bearbeitet wurden. Neue Fehler an Feldern, zu denen jemand noch gar nicht gekommen ist, fühlen sich an wie ein Tadel für etwas, das man nicht getan hat.

Speichere die Struktur, nicht den String

Speichere die Adresse als Felder plus ISO-Ländercode, nicht als formatierte Zeilen. Du brauchst die Struktur für Steuern, Versandtarife und Versandetiketten, und für die Anzeige formatieren kannst du sie immer. Eine einzeilige Zusammenfassung wie „12 Mission St, San Francisco, CA 94110“ ist eine Ansicht der Daten, nicht die Daten.

Eine Checkliste

• Zuerst das Land, dann Felder, Labels und Reihenfolge aus einem Format pro Land.
• Ein exaktes Format für deine wichtigsten Länder und ein nachsichtiger Fallback für den Rest.
• Ein Namensfeld, Zeile 2 und Firma hinter Links, Telefon optional mit Begründung.
• Ein name und ein shipping- oder billing-Autocomplete-Token an jedem Input.
• Text-Inputs für Postleitzahlen, Zifferntastaturen nur dort, wo Codes aus Ziffern bestehen.
• Postleitzahl-Abfrage, die nie eingegebene Werte überschreibt.
• Adresssuche mit einer Option zur manuellen Eingabe am Ende.
• Länderspezifische Fehlertexte und eine verlinkte Zusammenfassung beim Absenden.

Der passende HextaUI-Block

Der Address Form-Block in HextaUI Pro basiert auf diesen Regeln. Sechzehn Länder haben ihr eigenes Format mit Labels, Pflichtfeldern, Regionslisten und Postleitzahlregeln, und jedes andere Land bekommt einen schlichten Fallback. Jedes Input hat das richtige Autocomplete-Token mit Shipping- oder Billing-Präfix. onSearchAddress und onResolveAddress binden die Adresssuche an, mit einem Beispiel für Google Places, und dieselben zwei Aufrufe lassen sich auf Mapbox abbilden. onLookupPostalCode füllt Stadt und Region aus, ohne Eingetipptes zu überschreiben, und validate() listet jedes Problem in einer verlinkten Zusammenfassung auf. SavedAddresses und AddressSummary decken angemeldete Kunden und die fertige „Lieferung an“-Zeile ab.

Der Checkout-Block nutzt es für die Lieferung. Wenn du den Rest dieser Seite baust, habe ich auch einen One-Page-Checkout in React und Next.js beschrieben.

Häufige Fragen

Sollte das Länderfeld zuerst kommen? Ja. Es entscheidet, welche Felder es gibt und in welcher Reihenfolge, also muss es gewählt sein, bevor der Rest Sinn ergibt.

Sollte ich Felder für Vor- und Nachname verwenden? Nutz ein einziges Feld für den vollständigen Namen, es sei denn, ein Versanddienstleister oder Zahlungsanbieter verlangt die Aufteilung.

Welchen Input-Typ sollte eine Postleitzahl haben? Ein Text-Input, mit inputMode="numeric" nur für Länder, deren Codes ausschließlich aus Ziffern bestehen.

Brauche ich eine Adressvalidierung per API? Sie hilft, aber blockiere die Bestellung nicht damit. Schlag eine Korrektur vor und lass die Kundin behalten, was sie eingegeben hat.