Migrate to the Polaris map component

The Polaris map component displays a map on a page. It replaces the previous Map component and is available as <s-map> in API versions 2025-10 and newer.

Anchor to Updated propertiesUpdated properties

The following properties are different in the Polaris map component.

Anchor to onPressonPress

The previous Map onPress prop is now called onClick. The handler now receives a MapClickEvent instead of a MapLocation.

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"
      onClick={(event) => {
        console.log('Clicked:', event.location.latitude, event.location.longitude);
      }}
    ></s-map>
  );
}

import {
  reactExtension,
  Map,
} 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"
      onPress={(location) => {
        console.log('Clicked:', location.latitude, location.longitude);
      }}
    />
  );
}

Anchor to onDoublePressonDoublePress

The previous Map onDoublePress prop is now called onDblClick. The handler now receives a MapDblClickEvent instead of a MapLocation.

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"
      onDblClick={(event) => {
        console.log('Double-clicked:', event.location.latitude, event.location.longitude);
      }}
    ></s-map>
  );
}

import {
  reactExtension,
  Map,
} 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"
      onDoublePress={(location) => {
        console.log('Double-clicked:', location.latitude, location.longitude);
      }}
    />
  );
}

Anchor to onBoundsChangeonBoundsChange

The previous Map onBoundsChange prop still uses onBoundsChange in Preact, but the handler now receives a MapBoundsChangeEvent instead of a MapBounds value.

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"
      onBoundsChange={(event) => {
        console.log('NE:', event.bounds.northEast?.latitude, event.bounds.northEast?.longitude);
        console.log('SW:', event.bounds.southWest?.latitude, event.bounds.southWest?.longitude);
      }}
    ></s-map>
  );
}

import {
  reactExtension,
  Map,
} 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"
      onBoundsChange={(bounds) => {
        console.log('NE:', bounds.northEast.latitude, bounds.northEast.longitude);
        console.log('SW:', bounds.southWest.latitude, bounds.southWest.longitude);
      }}
    />
  );
}

Anchor to SizesSizes

The size properties accept updated values in the Polaris map component. Previous unitless number values map to pixels. For example, 300 is now '300px'.

Anchor to New propertiesNew properties

The Polaris map component introduces the following new properties:

Anchor to Removed propertiesRemoved properties

Anchor to onCenterChange and onZoomChangeonCenterChange and onZoomChange

The previous Map onCenterChange and onZoomChange props have been merged into a single onViewChange prop. The handler receives a MapViewChangeEvent with the new center (location.latitude, location.longitude) and zoom.

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"
      onViewChange={(event) => {
        console.log('Center:', event.location.latitude, event.location.longitude);
        console.log('Zoom:', event.zoom);
      }}
    ></s-map>
  );
}

import {
  reactExtension,
  Map,
} 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"
      onCenterChange={(location) => {
        console.log('Center:', location.latitude, location.longitude);
      }}
      onZoomChange={(zoom) => {
        console.log('Zoom:', zoom);
      }}
    />
  );
}