LocationInput

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.

For more information on how to use the features and props for this component, check out the developer documentation.

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 you would like to display a map below the ComboBox input field, enable the showMap prop. This will allow users to visualize the selections they make in the input, or modify their selection by dragging and clicking on the map. If the map is enabled, you can configure certain behaviors such as the default zoomLevel and whether to re-center the map to the selected value whenever it changes, either by manual input or by interaction with the map. The height of the map can also be adjusted, although the width will always span to 100% of the LocationInput.

NameTypeDefaultDescription
biasBiasBiasing query results towards user location/preference.
centerMapOnChangebooleanfalse 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.
classNamestringAdditional CSS classes.
defaultToCurrentLocationbooleanfalse Get user current location on component first render.
defaultValuestringIf 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.
disabledbooleanfalse Flag to control 'disabled' state for input.
heightstring'25rem' Height of the map container.
idstringSets 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.
infoReactNodeIt is recommended to pass a simple string to offer guidance. Text will be styled based on status prop.
labelReactNodePass a string or a fragment with an Icon and string.
labelHiddenbooleanVisually hides the label region.
location
LatLng |string 
Location coordinates used for the map view.
namestringSets html name attribute for the underlying control. Useful for mapping to a data field.
onBlur(value: string) => voidCallback fired when the control's input loses focus. The argument passed back is the component's value prop.
onChange(value: string) => voidCallback fired on every change of the location input. The argument passed back is the component's value prop.
onClick
(coords: {
  address: undefined | string;
  latitude: number;
  longitude: number;
  name: string;
}) => void
Callback fired when user clicks on a location on the map. This function will be passed the coordinates of the location that was clicked.
onError(error: Error) => voidCallback fired when an error occurs. This function gets called with one argument of type Error.
onSelect
(value: {
  address: undefined | string;
  latitude: undefined | number;
  longitude: undefined | number;
  name: string;
}) => void
Callback fired when user chooses location from the dropdown of suggestions or submits input value.
placeholderstringPlaceholder text. The browser defaults to an empty string.
readOnlybooleanMakes the input non editable and non clickable. The browser defaults to false.
requiredbooleanIndicate if the field is required. The browser defaults to false.
showMapbooleanfalse Set to true renders the map view below input.
status
'success' |'warning' |'error' 
Set visual state based on a validation state.
valuestringThe value of the location field.
zoomLevelnumber13 How much the map should zoom.