| Name | Description | Default | Type |
|---|---|---|---|
additionalInfo | Button when clicked will show additional information for the location input | | { content: string | Element; heading: string;} |
bias | Biasing query results towards user location/preference. | | Bias |
centerMapOnChange | Set to true to always center the map when the selected location changes. Toggling this from false to true will re-center map on the last pinned location. | false | boolean |
className | Additional CSS classes. | | string |
defaultToCurrentLocation | Get user current location on component first render. | false | boolean |
defaultValue | If you wish to use an uncontrolled input, pass a defaultValue prop and a ref to access the input's native value prop or by other DOM ref means. | | string |
disabled | Flag to control 'disabled' state for input. | false | boolean |
height | Height of the map container. | '25rem' | string |
id | Sets DOM id for the control and associates label element via 'for' attribute. If an id is not pass, a random id will be generated for any render. | | string |
info | It is recommended to pass a simple string to offer guidance. Text will be styled based on status prop. | | ReactNode |
label | Pass a string or a fragment with an Icon and string. | | ReactNode |
labelHidden | Visually hides the label region. | | boolean |
location | Location coordinates used for the map view. | | string |LatLng |
name | Sets html name attribute for the underlying control. Useful for mapping to a data field. | | string |
onBlur | | (value: string) => void | |
onChange | | (value: string) => void | |
onClick | | (coords: { address: string; latitude: number; longitude: number; name: string;}) => void | |
onError | | (error: Error) => void | |
onResolveSuggestion | | (accepted: boolean) => void | |
onSelect | | (value: { address: string; latitude: number; longitude: number; name: string;}) => void | |
placeholder | Placeholder text. The browser defaults to an empty string. | | string |
readOnly | Makes the input non editable and non clickable. The browser defaults to false. | | boolean |
required | Indicate if the field is required. The browser defaults to false. | | boolean |
showMap | Set to true renders the map view below input. | false | boolean |
status | Set visual state based on a validation state. | | 'error' |'pending' |'success' |'warning' |
value | The value of the location field. | | string |
zoomLevel | How much the map should zoom. | 13 | number |
LocationInput
core package3.2.2
Note: All components shown on this site are supported by the Constellation design system. To learn how to configure Theme Cosmos, visit Pega Community.
The LocationInput component takes a user's entered location and adds in the Google Maps utility. This utility will assist in filtering a menu of locations to choose from if a user is manually entering a location in the ComboBox input. It also supplies a map region that users can interact with to move and select any location.
Note: For security reasons, the following demos features a development version of the Google Maps API that does not require an API key. Add protection to your API key by following the Google API key restriction guidelines. You can insert your own API key into the demos to see the full capabilities of this component.
Usage
You will need a Google API Key to work with the LocationInput component. Any LocationInput component or LocationDisplay component must be wrapped with a <MapsContext.Provider> component that take a configuration object that includes the name of the map provider and the necessary API key.
<MapsContext.Provider value={{ name: 'google', apiKey: 'your_unique_api_key' }}>
LocationInput uses Google's auto-complete to capture the address, latitude, longitude, and name of the chosen location. These attributes are returned from the component as parameters for the onSelect callback function. The LocationInput component also provides a current location Button which allows a user to quickly geolocalize their current location. You can also configure the LocationInput component to set the deafult value to the user's location by passing the defaultToCurrentLocation prop. The current location functionality will only work if the user gives appropriate permissions to their browser. A Tooltip will explain to the user that current location is not enabled if the component is unable to detect their location when the Button is clicked.
The LocationInput component also allows for standard Form Field structures such as being set required, disabled, or readOnly, as well as including a label, status, or info.
If there is a label and the Field is not disabled, passing an object to the additionalInfo prop that includes a heading and content will provide the user with more useful information on the Field when they click on the associated information Icon.