AddressInput

The <AddressInput /> component allows the user to enter an address as text, while also providing address autocomplete options using the Google Maps Places API.

If no valid API key is provided, the control alerts the user to the issue, but still functions similar to the <TextInput />.

Show codeCopy code

To get notified when the user selects an address, use the onSelectAddress callback.

The callback returns an AutocompleteOption type which contains a label of the selected address, e.g. 10/191 Clarence St, Sydney NSW 2000, and the value returned from the Google's API as a AutocompletePrediction type.

While the AutocompletePrediction object contains some useful information, to get the address broken down into logical parts such as street number, street, suburb etc, use the onSelectAddressDetails callback.

{
  "label": "10/191 Clarence St, Sydney NSW 2000",
  "value": {
    "description": "10/191 Clarence St, Sydney NSW 2000",
    "matched_substrings": [
      {
        "length": 11,
        "offset": 7
      },
      {
        "length": 6,
        "offset": 20
      },
      {
        "length": 3,
        "offset": 27
      },
      {
        "length": 4,
        "offset": 31
      }
    ],
    "place_id": "EiMxMC8xOTEgQ2xhcmVuY2UgU3QsIFN5ZG5leSBOU1cgMjAwMCI5GjcKMRIvChQKEgmbmj8kP64SaxG3aJUc1kIgoBC_ASoUChIJ582MVj-uEmsReUNCgzzYFioSAjEw",
    "reference": "EiMxMC8xOTEgQ2xhcmVuY2UgU3QsIFN5ZG5leSBOU1cgMjAwMCI5GjcKMRIvChQKEgmbmj8kP64SaxG3aJUc1kIgoBC_ASoUChIJ582MVj-uEmsReUNCgzzYFioSAjEw",
    "structured_formatting": {
      "main_text": "191 Clarence St",
      "main_text_matched_substrings": [
        {
          "length": 11,
          "offset": 4
        }
      ],
      "secondary_text": "10, Sydney NSW 2000",
      "secondary_text_matched_substrings": [
        {
          "length": 6,
          "offset": 4
        },
        {
          "length": 3,
          "offset": 11
        },
        {
          "length": 4,
          "offset": 15
        }
      ]
    },
    "terms": [
      {
        "offset": 0,
        "value": "10"
      },
      {
        "offset": 3,
        "value": "191"
      },
      {
        "offset": 7,
        "value": "Clarence St"
      },
      {
        "offset": 20,
        "value": "Sydney"
      },
      {
        "offset": 27,
        "value": "NSW"
      },
      {
        "offset": 31,
        "value": "2000"
      }
    ],
    "types": ["subpremise", "geocode"]
  }
}

The onSelectAddressDetails callback provides the selected address in a structured street address format. This is useful if you wish to break up the selected address into components like street, suburb, state etc.

It provides the addressDetailParts in the following format:

{
  "streetAddress": "10, 191 Clarence Street",
  "suburb": "Sydney",
  "state": "NSW",
  "postcode": "2000",
  "country": "Australia"
}

The above format has been tested for Australia, New Zealand and United Kingdom addresses, however other countries may split their addresses differently.

In those cases the raw response from the Google Maps Placement API is also available in the GeocoderAddressComponent format:

[
  {
    "long_name": "10",
    "short_name": "10",
    "types": ["subpremise"]
  },
  {
    "long_name": "191",
    "short_name": "191",
    "types": ["street_number"]
  },
  {
    "long_name": "Clarence Street",
    "short_name": "Clarence St",
    "types": ["route"]
  },
  {
    "long_name": "Sydney",
    "short_name": "Sydney",
    "types": ["locality", "political"]
  },
  {
    "long_name": "City of Sydney",
    "short_name": "City of Sydney",
    "types": ["administrative_area_level_2", "political"]
  },
  {
    "long_name": "New South Wales",
    "short_name": "NSW",
    "types": ["administrative_area_level_1", "political"]
  },
  {
    "long_name": "Australia",
    "short_name": "AU",
    "types": ["country", "political"]
  },
  {
    "long_name": "2000",
    "short_name": "2000",
    "types": ["postal_code"]
  }
]

The region prop is used to give priority to a geographical area when returning search results. By default this is set to Australia.

It accepts Unicode region subtag identifiers which generally have a one-to-one mapping to country code Top-Level Domains (ccTLDs). Most Unicode region identifiers are identical to ISO 3166-1 codes, with some notable exceptions. For example, Great Britain's ccTLD is "uk" (corresponding to the domain .co.uk) while its region identifier is "GB."

// New Zealand search-priority
<AddressInput apiKey="your-google-api-key" region="NZ" />
// Great Britain search-priority
<AddressInput apiKey="your-google-api-key" region="GB" />

To prevent too many costly Google Maps API calls, the address input adds a minimum text length of three characters, and a debounce timeout which will wait for a pause in the user's typing for 300ms before making any API calls.

These default values can be changed with the debounceTimeout and minLengthAutocomplete props.

<AddressInput apiKey="your-google-api-key" debounceTimeout="500" minLengthAutocomplete="5" />

The input supports two sizes, small and medium (default). Prefer using size consistently with other form controls that support the same sizes.

<AddressInput apiKey="your-api-key" size="small" />
<AddressInput apiKey="your-api-key" size="medium" />

Use the placeholder prop to provide a hint or example of what the user can enter.

<AddressInput placeholder="Search addresses..." />

Use the disabled prop when the user shouldn't be able to manipulate the value of the input.

<AddressInput disabled placeholder="Disabled" />

Use the invalid prop to communicate that validation has failed for this particular search input.

<AddressInput invalid placeholder="Invalid" />