salla-map
A location picker built on Google Maps.
A location picker built on Google Maps. It shows a button that opens a modal with a map where the customer taps a point (and can optionally search for a place or use their current location), then confirms it. Use it in forms that need a delivery or pickup location. The Google Maps script is only loaded the first time the modal opens.
The chosen point is stored in a hidden form input named by name, with the value "lat, lng", so it is submitted with the
surrounding form. The Google Maps API key is taken from the store settings unless api-key is set.
Use it
In HTML or JSX, use the tag <salla-map> with the Attribute names below. In React, the wrapper takes the Property names (camelCase).
import { SallaMap } from '@salla.sa/twilight-components-react/map';Client-only. On the server this wrapper renders a placeholder (a skeleton, or nothing), and the real component mounts in the browser. Do not rely on it for content that search engines must see.
Example
import { useEffect } from 'react';
import { SallaMap } from '@salla.sa/twilight-components-react/map';
export function Example() {
useEffect(() => {
document.querySelector('salla-map').addEventListener('selected', e => console.log(e.detail.lat, e.detail.lng, e.detail.address));
}, []);
return (
<SallaMap name="location" searchable required modalTitle="Choose your location" zoom={12} />
);
}Properties
| Property | Attribute | Description | Type | Default |
|---|---|---|---|---|
apiKey | api-key | The Google Maps API key. Defaults to the store's maps key (store.settings.keys.maps). | string | |
lat | lat | Latitude of the selected point. When neither lat nor lng is set, the map tries the visitor's current location. It is updated as the customer picks a point. | number | |
lng | lng | Longitude of the selected point. When neither lat nor lng is set, the map tries the visitor's current location. It is updated as the customer picks a point. | number | |
modalTitle | modal-title | Title shown at the top of the map modal. Defaults to the translated "select your address from map" text. | string | |
name | name | Name of the hidden input that holds the selected location as "lat, lng", so it is included in the form data. Defaults to location. | string | 'location' |
readonly | readonly | When true the map is view only: the customer cannot click the map, search, or confirm a new location. Defaults to false. | boolean | false |
required | required | Makes the hidden location input required, so a form with no selected location fails validation. Defaults to false. | boolean | false |
searchable | searchable | Shows a place search box in the modal. Ignored when readonly is true. Defaults to false. | boolean | false |
theme | theme | The map color style. light (default) uses the light style; any other value uses the dark style. | string | 'light' |
zoom | zoom | The starting zoom level of the map, a Google Maps zoom number (higher is closer). Defaults to 10. | number | 10 |
Events
Listen with addEventListener, or the on prop of the React wrapper (for example onModalBack).
| Event | Description | Detail |
|---|---|---|
currentLocationChanged | Fires when the browser's current location is detected, either automatically on open or from the locate button. event.detail is { lat, lng, address }. | any |
invalidInput | Fires when the hidden location input fails validation, for example when required is set and no location is selected. event.detail is the native invalid event. | any |
mapClicked | Fires when the customer clicks the map to move the marker. event.detail is { lat, lng, address } where address is the last known address string or null. | any |
selected | Fires when the customer confirms a location. event.detail is { lat, lng, address } where address is a string or null. The same payload is also dispatched on the SDK as salla-map::selected. | any |
Methods
Call these on the element or a React ref.
open() => Promise<HTMLElement>
Opens the map modal. The Google Maps script is loaded on the first call.
Returns Promise<HTMLElement>: A Promise that resolves once the modal is opened, with the result of the modal's own open().
reportValidity() => Promise<boolean>
Checks that a location is selected when the field is required. When none is selected, the
visible location button gets focus and the invalidInput event fires.
Returns Promise<boolean>: A Promise that resolves to true when the field is valid (or not required, or readonly), and false when a required location is missing.
Slots
| Slot | Description |
|---|---|
button | Replaces the default button that opens the map modal. Call the open() method from your own element to open the modal. |
Related
Renders: <salla-button>, <salla-modal>.
Used inside: <salla-order-details-options>, <salla-product-options>.