Migrate to the Polaris map marker component

The Polaris map marker component displays a marker on a map. It replaces the previous MapMarker component and is available as <s-map-marker> in API versions 2025-10 and newer. Use it as a child of <s-map>.

Anchor to Updated propertiesUpdated properties

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

Anchor to onPressonPress

The previous MapMarker onPress prop is now called onClick. The handler now receives an Event instead of being called with no arguments.

Anchor to blockSize and inlineSizeblockSize and inlineSize

The blockSize and inlineSize props now take string units with a unit suffix instead of a plain number.

Anchor to New propertiesNew properties

The Polaris map marker component introduces the following new properties:

Anchor to Removed propertiesRemoved properties

Anchor to iconicon

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> to render an image from a URL.

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>
  );
}

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>
  );
}

Anchor to overlayoverlay

The previous MapMarker overlay prop has been replaced with the command and commandFor pattern. To open a popover when the marker is activated, target a sibling <s-popover> by ID.

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>
  );
}

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>
  );
}