---
title: Migrate to the Polaris map marker component
description: >-
  Learn how to migrate the MapMarker component to Polaris web components in
  checkout and customer account UI extensions.
source_url:
  html: >-
    https://shopify.dev/docs/apps/build/checkout/migrate-to-web-components/map-marker
  md: >-
    https://shopify.dev/docs/apps/build/checkout/migrate-to-web-components/map-marker.md
---

# Migrate to the Polaris map marker component

The Polaris map marker component displays a marker on a map. It replaces the previous [`MapMarker`](https://shopify.dev/docs/api/checkout-ui-extensions/2025-07/ui-components/media-and-visuals/mapmarker) component and is available as [`<s-map-marker>`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/media-and-visuals/map#map%20marker) in API versions 2025-10 and newer. Use it as a child of [`<s-map>`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/media-and-visuals/map).

***

## Updated properties

The following properties are different in the Polaris map marker component.

### on​Press

The previous `MapMarker` `onPress` prop is now called [`onClick`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/media-and-visuals/map#mapmarker-events-propertydetail-click). The handler now receives an `Event` instead of being called with no arguments.

### block​Size and inline​Size

The [`blockSize`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/media-and-visuals/map#mapmarker-propertydetail-blocksize) and [`inlineSize`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/media-and-visuals/map#mapmarker-propertydetail-inlinesize) props now take string units with a unit suffix instead of a plain number.

| Previous value | New value |
| - | - |
| `32` | `"32px"` |

***

## New properties

The Polaris map marker component introduces the following new properties:

| New prop | Type | Description |
| - | - | - |
| [`command`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/media-and-visuals/map#mapmarker-propertydetail-command) | `'--auto'`, `'--show'`, `'--hide'`, `'--toggle'` | Sets the action to run on the target component when the marker is activated. |
| [`commandFor`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/media-and-visuals/map#mapmarker-propertydetail-commandfor) | `string` | Sets the ID of the target component for the command. |

***

## Removed properties

### icon

The previous `MapMarker` `icon` prop (a URL to an image) has been replaced by a `graphic` slot. Place any `HTMLElement` inside the marker with `slot="graphic"` — for example, an [`<s-image>`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/media-and-visuals/image) to render an image from a URL.

## Migrating icon to the graphic slot

##### Latest (Preact)

```tsx
import '@shopify/ui-extensions/preact';
import {render} from 'preact';

export default function extension() {
  render(<Extension />, document.body);
}

function Extension() {
  return (
    <s-map
      apiKey="YOUR_API_KEY"
      latitude={43.6532}
      longitude={-79.3832}
      accessibilityLabel="Store location"
    >
      <s-map-marker
        latitude={43.6532}
        longitude={-79.3832}
        accessibilityLabel="Flagship store"
      >
        <s-image
          slot="graphic"
          src="https://cdn.shopify.com/YOUR_IMAGE_HERE"
        ></s-image>
      </s-map-marker>
    </s-map>
  );
}
```

##### Pre-Polaris (2025-07)

```tsx
import {
  reactExtension,
  Map,
  MapMarker,
} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(
  'purchase.checkout.block.render',
  () => <Extension />,
);

function Extension() {
  return (
    <Map
      apiKey="YOUR_API_KEY"
      latitude={43.6532}
      longitude={-79.3832}
      accessibilityLabel="Store location"
    >
      <MapMarker
        latitude={43.6532}
        longitude={-79.3832}
        accessibilityLabel="Flagship store"
        icon="https://cdn.shopify.com/YOUR_IMAGE_HERE"
      />
    </Map>
  );
}
```

### overlay

The previous `MapMarker` `overlay` prop has been replaced with the [`command`](#new-properties) and [`commandFor`](#new-properties) pattern. To open a popover when the marker is activated, target a sibling [`<s-popover>`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/overlays/popover) by ID.

## Migrating overlay to command and commandFor

##### Latest (Preact)

```tsx
import '@shopify/ui-extensions/preact';
import {render} from 'preact';

export default function extension() {
  render(<Extension />, document.body);
}

function Extension() {
  return (
    <s-map
      apiKey="YOUR_API_KEY"
      latitude={43.6532}
      longitude={-79.3832}
      accessibilityLabel="Store location"
    >
      <s-map-marker
        latitude={43.6532}
        longitude={-79.3832}
        accessibilityLabel="Flagship store"
        command="--toggle"
        commandFor="store-details"
      ></s-map-marker>
      <s-popover id="store-details">
        <s-text>620 King Street West, Toronto</s-text>
      </s-popover>
    </s-map>
  );
}
```

##### Pre-Polaris (2025-07)

```tsx
import {
  reactExtension,
  Map,
  MapMarker,
  MapPopover,
  Text,
} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(
  'purchase.checkout.block.render',
  () => <Extension />,
);

function Extension() {
  return (
    <Map
      apiKey="YOUR_API_KEY"
      latitude={43.6532}
      longitude={-79.3832}
      accessibilityLabel="Store location"
    >
      <MapMarker
        latitude={43.6532}
        longitude={-79.3832}
        accessibilityLabel="Flagship store"
        overlay={
          <MapPopover>
            <Text>620 King Street West, Toronto</Text>
          </MapPopover>
        }
      />
    </Map>
  );
}
```

***