# salla-map (https://docs.salla.dev/twilight/react/web-components/salla-map)



{/* Generated by scripts/sync-web-components.mjs from the components docs.json. Do not edit by hand. */}

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 [#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).

```tsx
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 [#example]

```tsx
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} />
  );
}
```

```html
<salla-map name="location" searchable required modal-title="Choose your location" zoom="12"></salla-map>
<script>
  document.querySelector('salla-map').addEventListener('selected', e => console.log(e.detail.lat, e.detail.lng, e.detail.address));
</script>
```

## Properties [#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 [#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 [#methods]

Call these on the element or a React ref.

### `open() => Promise<HTMLElement>` [#open--promisehtmlelement]

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>` [#reportvalidity--promiseboolean]

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 [#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 [#related]

Renders: [`<salla-button>`](https://docs.salla.dev/twilight/react/web-components/salla-button), [`<salla-modal>`](https://docs.salla.dev/twilight/react/web-components/salla-modal).

Used inside: [`<salla-order-details-options>`](https://docs.salla.dev/twilight/react/web-components/salla-order-details-options), [`<salla-product-options>`](https://docs.salla.dev/twilight/react/web-components/salla-product-options).