The place picker component is a text input that allows end users to search Google Maps’ global database for a specific address or place using autocomplete.
When loading the library with a <script> tag (referencing the CDN bundle), please refer to the instructions in the root-level Readme. You do not need to take additional steps to use this component.
When bundling your dependencies and you want to include <gmpx-place-picker> on a page:
import '@googlemaps/extended-component-library/place_picker.js';
When bundling your dependencies and you need to access the class PlacePicker directly (less common):
import { PlacePicker } from '@googlemaps/extended-component-library/place_picker.js';
| Attribute | Property | Property type | Description | Default | Reflects? |
|---|---|---|---|---|---|
country |
country |
string[] | undefined |
Restricts predictions to up to five countries identified by their ISO 3166-1 Alpha-2 country codes, case insensitive ('us', 'br', 'au', etc.). Multiple country codes can be specified in the attribute as a set of space-separated tokens (for example, "us ca"). |
✅ | |
for-map |
forMap |
string | undefined |
The HTML id of a <gmp-map> element on the page that Place Autocomplete should bind to for location biasing. Note that the map need not be a parent of the current element. |
✅ | |
location-bias |
locationBias |
google.maps.LatLngLiteral | undefined |
Location of the region to bias predictions towards (or restrict if strict-bounds is set), in "lat,lng" format.This attribute must be used in conjunction with radius. |
✅ | |
placeholder |
placeholder |
string | undefined |
Placeholder text to display before the user has entered any input. | ✅ | |
radius |
radius |
number | undefined |
Radius of the region, in meters, to bias predictions towards. This attribute must be used in conjunction with location-bias. |
✅ | |
strict-bounds |
strictBounds |
boolean |
If true, only predictions that are within the specified location/radius or map viewport will be returned. Setting this property to false (which is the default) will make the results biased towards, but not restricted to, places contained within the bounds. |
false |
✅ |
type |
type |
string | undefined |
The type of predictions to return. Some examples include “restaurant”, “country” and “address”. This property supports any one type found in Tables 1~3 of Place Types. If no type is specified, predictions of all types will be returned. |
✅ | |
value |
google.maps.places.Place|null|undefined |
This readonly property contains data about the user-selected place. If the user selects a valid place, then the object is guaranteed to contain at minimum its Place ID, along with all available Basic Data fields. This property is undefined when user input is empty, and null when no results are found based on user input. |
❌ |
Binds Place Autocomplete to the specified map so that its results are biased towards the map’s viewport.
Parameters:
| Name | Optional? | Type | Description |
|---|---|---|---|
map |
google.maps.Map |
| Name | Type | Description |
|---|---|---|
gmpx-placechange |
Event |
This event is fired when a Place object is made available for a Place the user has selected, when user clears the input after selection, or when no Place result is found based on the input query. |
gmpx-requesterror |
RequestErrorEvent |
Indicates an error condition in an underlying Google Maps JavaScript API call. |
You can use most built-in CSS properties to control the positioning or display of this component, similar to a <span> element. The component also supports the following styling inputs for more customization:
| Name | Default | Description |
|---|---|---|
--gmpx-color-surface |
#fff |
Background color of the input. 🌎 |
--gmpx-color-on-surface |
#212121 |
Main text color. 🌎 |
--gmpx-color-primary |
#1e88e5 |
Color of the input focus ring. 🌎 |
--gmpx-font-family-base |
'Google Sans Text', sans-serif |
Font family. 🌎 |
--gmpx-font-size-base |
0.875rem |
Font size, used to scale the component. 🌎 |
🌎 indicates a global style token shared by multiple components. Please see the library Readme for more information.
You can use Place Picker to produce a well formatted address for any user-entered location. This example shows how to add that address to a hidden form field.
<gmpx-place-picker placeholder="Enter a place" id="place-picker" style="width: 100%">
</gmpx-place-picker>
<input name="address" type="hidden" id="selected-address"/>The Place Picker component maintains a Place instance corresponding to the selected location. When the end user has made a selection, this example updates the input field with the Place's address:
const picker = document.getElementById('place-picker');
const addressInput = document.getElementById('selected-address');
picker.addEventListener('gmpx-placechange', () => {
addressInput.value = picker.value.formattedAddress;
});Combine a Place Picker with a Place Overview to show details about a user-entered location.
<gmpx-place-picker placeholder="Enter a place" id="place-picker" style="width: 100%">
</gmpx-place-picker>
<gmpx-place-overview id="place-overview"></gmpx-place-overview>Some basic JavaScript is required to connect the two components:
const picker = document.getElementById('place-picker');
const overview = document.getElementById('place-overview');
// When the Place Picker fires a placechange event, update the Place Overview
// component to use the new Place.
picker.addEventListener('gmpx-placechange', () => {
overview.place = picker.value;
});In addition to the Maps JavaScript API, this component relies on the following Google Maps Platform APIs which may incur cost and must be enabled.
Used when fetching Places data based on user input.
Places API Autocomplete documentation. Please be sure to check this documentation for additional requirements and recommendations regarding your use.