---
title: Migrate to the Polaris map component
description: >-
  Learn how to migrate the Map 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'
  md: >-
    https://shopify.dev/docs/apps/build/checkout/migrate-to-web-components/map.md
---

# Migrate to the Polaris map component

The Polaris map component displays a map on a page. It replaces the previous [`Map`](https://shopify.dev/docs/api/checkout-ui-extensions/2025-07/ui-components/media-and-visuals/map) component and is available as [`<s-map>`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/media-and-visuals/map) in API versions 2025-10 and newer.

***

## Updated properties

The following properties are different in the Polaris map component.

### on​Press

The previous `Map` `onPress` prop is now called [`onClick`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/media-and-visuals/map#events-propertydetail-click). The handler now receives a `MapClickEvent` instead of a `MapLocation`.

## Migrating onPress to onClick

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

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

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

### on​Double​Press

The previous `Map` `onDoublePress` prop is now called [`onDblClick`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/media-and-visuals/map#events-propertydetail-dblclick). The handler now receives a `MapDblClickEvent` instead of a `MapLocation`.

## Migrating onDoublePress to onDblClick

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

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

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

### on​Bounds​Change

The previous `Map` [`onBoundsChange`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/media-and-visuals/map#events-propertydetail-boundschange) prop still uses `onBoundsChange` in Preact, but the handler now receives a `MapBoundsChangeEvent` instead of a `MapBounds` value.

## Migrating onBoundsChange handler arguments

##### 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"
      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>
  );
}
```

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

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

### Sizes

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

| Property | Previous values | New values | Migration notes |
| - | - | - | - |
| [`maxInlineSize`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/media-and-visuals/map#properties-propertydetail-maxinlinesize) | `number` \| `` `${number}%` `` \| `'fill'` | `` `${number}px` `` \| `` `${number}%` `` \| `'0'` \| `'none'` | `fill` is removed. Use `100%` instead. |
| [`minInlineSize`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/media-and-visuals/map#properties-propertydetail-mininlinesize) | `number` \| `` `${number}%` `` \| `'fill'` | `` `${number}px` `` \| `` `${number}%` `` \| `'0'` | `fill` is removed. Use `100%` instead. |
| [`maxBlockSize`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/media-and-visuals/map#properties-propertydetail-maxblocksize) | `number` \| `` `${number}%` `` \| `'fill'` | `` `${number}px` `` \| `` `${number}%` `` \| `'0'` \| `'none'` | `fill` is removed. Use `100%` instead. |
| [`minBlockSize`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/media-and-visuals/map#properties-propertydetail-minblocksize) | `number` \| `` `${number}%` `` \| `'fill'` | `` `${number}px` `` \| `` `${number}%` `` \| `'0'` | `fill` is removed. Use `100%` instead. |

**Responsive values:**

If you used `Style.default().when()` to make this property responsive, container queries replace the `Style` helper. Wrap your content in `<s-query-container>` and use `@container` syntax in the property value. Learn more in [Migrate StyleHelper to container queries](https://shopify.dev/docs/apps/build/checkout/migrate-to-web-components/style-helper).

***

## New properties

The Polaris map component introduces the following new properties:

| New prop | Type | Description |
| - | - | - |
| [`blockSize`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/media-and-visuals/map#properties-propertydetail-blocksize) | `` `${number}px` `` \| `` `${number}%` `` \| `'0'` \| `'auto'` | Adjusts the block size of the map. |
| [`inlineSize`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/media-and-visuals/map#properties-propertydetail-inlinesize) | `` `${number}px` `` \| `` `${number}%` `` \| `'0'` \| `'auto'` | Adjusts the inline size of the map. |
| [`onViewChange`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/media-and-visuals/map#events-propertydetail-viewchange) | `(event: MapViewChangeEvent) => void` | Fires when the map's center or zoom changes. Replaces `onCenterChange` and `onZoomChange`. |

***

## Removed properties

### on​Center​Change and on​Zoom​Change

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

## Migrating onCenterChange and onZoomChange to onViewChange

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

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

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

***