## Usage

The `<AddressInput />` component allows the user to enter an address as text, while also providing address autocomplete options using the [Google Maps Places API](https://developers.google.com/maps/documentation/places/web-service).

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

```tsx live
const [address, setAddress] = useState('');

return <AddressInput apiKey="your-google-api-key" value={address} onChange={setAddress} />;
```

## onSelectAddress

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](https://developers.google.com/maps/documentation/javascript/reference/places-autocomplete-service#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`](#onselectaddressdetails) callback.

```json
{
  "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"]
  }
}
```

## onSelectAddressDetails

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:

```json
{
  "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](https://developers.google.com/maps/documentation/javascript/geocoding#GeocodingAddressTypes) format:

```json
[
  {
    "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"]
  }
]
```

## Region

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

<Notice>
  <Text>
    This value must be consistent for all address inputs on a page, and can not be changed after the component has first
    mounted.
  </Text>
</Notice>

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."

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

## API throttling

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.

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

## User Location Detection

The `showUserLocation` prop enables automatic detection of the user's current location and displays it as the first option in the address dropdown. When enabled, the component will request the browser's geolocation permission on focus and use the Google Maps Geocoder API to convert the coordinates into a formatted address.

```jsx
<AddressInput apiKey="your-google-api-key" showUserLocation />
```

<Notice type="info">
  <Text>
    This feature requires the user to grant browser geolocation permissions. If the user denies permission or if
    geolocation is unavailable, the component will gracefully continue to function with standard address search.
  </Text>
</Notice>

The user's location is fetched only once per session and cached to avoid repeated API calls and permission requests. The detected location appears with a "Current location:" prefix to distinguish it from search results.

```tsx live
const [address, setAddress] = useState('');

return (
  <AddressInput
    apiKey="your-google-api-key"
    value={address}
    onChange={setAddress}
    showUserLocation
    onSelectAddress={(prediction) => console.log('Selected:', prediction)}
  />
);
```

## Size

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

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

## Placeholder

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

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

## Disabled

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

```jsx
<AddressInput disabled placeholder="Disabled" />
```

## Invalid

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

```jsx
<AddressInput invalid placeholder="Invalid" />
```

An autocomplete street address input powered by the Google Maps Places API.

AddressInput

Accessibility

Responsive layouts

Tokens

Foundations

a11y

Accordion

Actions

AppLayout

Avatar

Badge

Blanket

Breadcrumbs

BulkActionBar

Button

Card

Checkbox

Core

DateDropdown

DateInput

Divider

EmptyState

Field

Fieldset

FileInput

Filtering

Flex

Grid

Heading

Icon

Illustration

Link

List

Loading

Modal

Notice

PageHeader

Pagination

PhoneInput

Popover

Radio

RailTrack

RichTextEditor

ScrollWrap

SearchInput

SelectDropdown

SelectInput

ShowMore

Table

Tabs

Text

TextAreaInput

TextInput

Toast

Toggle

Tooltip

Utils

Utils - NextJS

Components

Forms

Search

Tables

Patterns

Introduction

Product tone and voice

Capitalisation

Date and time

Inclusive design

Content

Welcome to EDS

Start designing

Start developing

Contributing

Releases

The EDS way

Coding style guide

Guide to Pendo

Setting up the EDS repo

Creating a new component

Automated testing

PR and changeset process

Publishing snapshots

Publishing packages

Monorepo tools

Team resources