---
title: Map
description: Use Map to display a map on a page. This component is useful for displaying a map of a location, such as a store or a customer’s address.
api_version: 2026-01
api_name: checkout-ui-extensions
source_url:
  html: https://shopify.dev/docs/api/checkout-ui-extensions/latest/polaris-web-components/interactive/map
  md: https://shopify.dev/docs/api/checkout-ui-extensions/latest/polaris-web-components/interactive/map.md
---

# Map

Use Map to display a map on a page. This component is useful for displaying a map of a location, such as a store or a customer’s address.

## Properties

* **accessibilityLabel**

  **string**

  A label that describes the purpose or contents of the map.

  When set, it will be announced to users using assistive technologies and will provide them with more context.

* **apiKey**

  **string**

  A valid API key for the map service provider.

  The map service provider may require an API key. Without an API key the map could be hidden or render in a limited developer mode.

* **blockSize**

  **MaybeResponsive\<SizeUnitsOrAuto>**

  **Default: 'auto'**

  Adjust the block size.

* **id**

  **string**

  A unique identifier for the element.

* **inlineSize**

  **MaybeResponsive\<SizeUnitsOrAuto>**

  **Default: 'auto'**

  Adjust the inline size.

* **latitude**

  **number**

  **Default: 0**

  Map center’s latitude in degrees.

* **longitude**

  **number**

  **Default: 0**

  Map center’s longitude in degrees.

* **maxBlockSize**

  **MaybeResponsive\<SizeUnitsOrNone>**

  **Default: 'none'**

  Adjust the maximum block size.

* **maxInlineSize**

  **MaybeResponsive\<SizeUnitsOrNone>**

  **Default: 'none'**

  Adjust the maximum inline size.

* **maxZoom**

  **number**

  **Default: 18**

  The maximum zoom level which will be displayed on the map.

  Valid zoom values are numbers from zero up to 18.

* **minBlockSize**

  **MaybeResponsive\<SizeUnits>**

  **Default: '0'**

  Adjust the minimum block size.

* **minInlineSize**

  **MaybeResponsive\<SizeUnits>**

  **Default: '0'**

  Adjust the minimum inline size.

* **minZoom**

  **number**

  **Default: 0**

  The minimum zoom level which will be displayed on the map.

  Valid zoom values are numbers from zero up to 18.

* **zoom**

  **number**

  **Default: 4**

  The initial Map zoom level.

  Valid zoom values are numbers from zero up to 18. Larger zoom values correspond to a higher resolution.

### MaybeResponsive

```ts
T | `@container${string}`
```

### SizeUnitsOrAuto

```ts
SizeUnits | "auto"
```

### SizeUnits

```ts
`${number}px` | `${number}%` | `0`
```

### SizeUnitsOrNone

```ts
SizeUnits | "none"
```

## Events

Learn more about [registering events](https://shopify.dev/docs/api/checkout-ui-extensions/2026-01/using-polaris-components#event-handling).

* **boundschange**

  **CallbackEventListener\<typeof tagName, MapBoundsEvent>**

  Callback when the viewport bounds have changed or the map is resized.

* **click**

  **CallbackEventListener\<typeof tagName, MapLocationEvent>**

  Callback when the user clicks on the map.

* **dblclick**

  **CallbackEventListener\<typeof tagName, MapLocationEvent>**

  Callback when the user double-clicks on the map.

* **viewchange**

  **CallbackEventListener\<typeof tagName, MapViewChangeEvent>**

  Callback when the map view changes.

### CallbackEventListener

```ts
(EventListener & {
    (event: CallbackEvent<TTagName, Event> & TData): void;
}) | null
```

### CallbackEvent

```ts
TEvent & {
    currentTarget: HTMLElementTagNameMap[TTagName];
}
```

### MapBoundsEvent

* bounds

  ```ts
  { northEast?: MapLocation; southWest?: MapLocation; }
  ```

```ts
export interface MapBoundsEvent {
    bounds?: {
        northEast?: MapLocation;
        southWest?: MapLocation;
    };
}
```

### MapLocation

* latitude

  ```ts
  number
  ```

* longitude

  ```ts
  number
  ```

```ts
export interface MapLocation {
    latitude?: number;
    longitude?: number;
}
```

### MapLocationEvent

* location

  ```ts
  MapLocation
  ```

```ts
export interface MapLocationEvent {
    location?: MapLocation;
}
```

### MapViewChangeEvent

* location

  ```ts
  MapLocation
  ```

* zoom

  ```ts
  number
  ```

```ts
export interface MapViewChangeEvent extends MapLocationEvent {
    zoom?: number;
}
```

## MapMarker

Use MapMarker to display a marker on a map. Use only as a child of `s-map` component.

* **accessibilityLabel**

  **string**

  A label that describes the purpose of the marker. When set, it will be announced to users using assistive technologies and will provide them with more context.

* **blockSize**

  **MaybeResponsive\<SizeUnitsOrAuto>**

  **Default: 'auto'**

  Adjust the block size.

* **clusterable**

  **boolean**

  **Default: false**

  Allows grouping the marker in clusters when zoomed out.

* **command**

  **'--auto' | '--show' | '--hide' | '--toggle'**

  **Default: '--auto'**

  Sets the action the `commandFor` should take when this clickable is activated.

  See the documentation of particular components for the actions they support.

  * `--auto`: a default action for the target component.
  * `--show`: shows the target component.
  * `--hide`: hides the target component.
  * `--toggle`: toggles the target component.
  * `--copy`: copies the target ClipboardItem.

* **commandFor**

  **string**

  ID of a component that should respond to activations (e.g. clicks) on this component.

  See `command` for how to control the behavior of the target.

* **inlineSize**

  **MaybeResponsive\<SizeUnitsOrAuto>**

  **Default: 'auto'**

  Adjust the inline size.

* **latitude**

  **number**

  **Default: 0**

  Marker’s location latitude in degrees.

* **longitude**

  **number**

  **Default: 0**

  Marker’s longitude latitude in degrees.

### MaybeResponsive

```ts
T | `@container${string}`
```

### SizeUnitsOrAuto

```ts
SizeUnits | "auto"
```

### SizeUnits

```ts
`${number}px` | `${number}%` | `0`
```

## Events

Learn more about [registering events](https://shopify.dev/docs/api/checkout-ui-extensions/2026-01/using-polaris-components#event-handling).

* **click**

  **CallbackEventListener\<typeof tagName>**

  Callback when a marker is clicked.

  It does not trigger a click event on the map itself.

### CallbackEventListener

```ts
(EventListener & {
    (event: CallbackEvent<TTagName, Event> & TData): void;
}) | null
```

### CallbackEvent

```ts
TEvent & {
    currentTarget: HTMLElementTagNameMap[TTagName];
}
```

## Slots

Learn more about [component slots](https://shopify.dev/docs/api/checkout-ui-extensions/2026-01/using-polaris-components#slots).

* **graphic**

  **HTMLElement**

  The graphic to use as the marker.

  If unset, it will default to the provider’s default marker.

Examples

## Preview

![](https://cdn.shopify.com/shopifycloud/shopify-dev/production/assets/assets/images/templated-apis-screenshots/checkout-ui-extensions/2025-10/map-default-i6aQsCgC.png)

### Examples

* #### Code

  ##### Default

  ```html
  <s-map apiKey="YOUR_API_KEY" latitude={51.5074} longitude={-0.1278}>
    <s-map-marker latitude={51.5074} longitude={-0.1278}></s-map-marker>
  </s-map>
  ```

* #### Popover with map marker

  ##### Description

  Use the \`Popover\` component to display content when a map marker is clicked.

  ##### Default

  ```html
  <s-map
    apiKey="YOUR_API_KEY"
    blockSize="400px"
    inlineSize="400px"
    latitude={37.7749}
    longitude={-122.4194}
  >
    <s-map-marker
      latitude={37.7749}
      longitude={-122.4194}
      commandFor="popover-san-francisco"
    ></s-map-marker>
    <s-popover id="popover-san-francisco">San Francisco</s-popover>
  </s-map>
  ```

* #### Map with graphic as map marker

  ##### Description

  Use the \`graphic\` slot to display a graphic as a map marker. Find more about slots \[here]\(/docs/api/checkout-ui-extensions/2026-01/using-polaris-components#slots).

  ##### Default

  ```html
  <s-map
    apiKey="YOUR_API_KEY"
    blockSize="400px"
    inlineSize="400px"
    latitude={37.7749}
    longitude={-122.4194}
  >
    <s-map-marker
      latitude={37.7749}
      longitude={-122.4194}
    >
      <s-image src="https://cdn.shopify.com/YOUR_IMAGE_HERE" slot="graphic"></s-image>
    </s-map-marker>
  </s-map>
  ```