Skip to main content
Migrate to Polaris

Version 2025-07 is the last API version to support React-based UI components. Later versions use web components, native UI elements with built-in accessibility, better performance, and consistent styling with Shopify's design system. Check out the migration guide to upgrade your extension.

Map

Use the Map component to provide visual representation of geographic data such as verifying address, package or pickup locations.

Please note that the merchant or partner has to provide an API key and a set of allowed domains where the map would render.

The 3 necessary domains needed are:

  • https://*.[MERCHANT-DOMAIN].com

  • https://shop.app

  • https://shopify.com

Where * is a wildcard. Learn more about match patterns.

Please refer to the Google Maps Platform documentation for more details on how to get an API key.

Support
Targets (50)

Supported targets

Anchor to MapPropsMapProps

Anchor to accessibilityLabel
accessibilityLabel
string
required

A label that describes the purpose or contents of the map. It will be announced to users using assistive technologies and will provide them with more context.

Anchor to apiKey
apiKey
string
required

The Google Maps API key used to authenticate requests. You can obtain a key from the Google Maps Platform.

Anchor to latitude
latitude
number
required

The latitude of the center of the map, in degrees. Valid values range from -90 (south pole) to 90 (north pole).

Anchor to longitude
longitude
number
required

The longitude of the center of the map, in degrees. Valid values range from -180 (west) to 180 (east).

Anchor to id
id
string

A unique identifier for the map. Used to set a unique map ID for the Google Maps API. If omitted, the map component automatically generates a unique identifier. If you provide one, you must ensure it is unique across all maps in the extension.

Anchor to maxBlockSize
maxBlockSize
< number | `${number}%` | 'fill' >

The maximum block size (maximum height in horizontal writing modes). The element won't grow taller than this value even if its content is longer.

  • number: The size in pixels.
  • `${number}%`: The size as a percentage of the parent container's block size.
  • 'fill': Takes all the available space.

Learn more about the max-block-size property.

Anchor to maxInlineSize
maxInlineSize
< number | `${number}%` | 'fill' >

The maximum inline size (maximum width in horizontal writing modes). The element won't grow wider than this value.

  • number: The size in pixels.
  • `${number}%`: The size as a percentage of the parent container's inline size.
  • 'fill': Takes all the available space.

Learn more about the max-inline-size property.

Anchor to maxZoom
maxZoom
number

The maximum zoom level the user can zoom in to. Prevents the map from being zoomed in beyond this level.

Anchor to minBlockSize
minBlockSize
< number | `${number}%` | 'fill' >

The minimum block size (minimum height in horizontal writing modes). The element won't shrink smaller than this value even if its content is shorter.

  • number: The size in pixels.
  • `${number}%`: The size as a percentage of the parent container's block size.
  • 'fill': Takes all the available space.

Learn more about the min-block-size property.

Anchor to minInlineSize
minInlineSize
< number | `${number}%` | 'fill' >

The minimum inline size (minimum width in horizontal writing modes). The element won't shrink narrower than this value.

  • number: The size in pixels.
  • `${number}%`: The size as a percentage of the parent container's inline size.
  • 'fill': Takes all the available space.

Learn more about the min-inline-size property.

Anchor to minZoom
minZoom
number

The minimum zoom level the user can zoom out to. Prevents the map from being zoomed out beyond this level.

Anchor to onBoundsChange
onBoundsChange
(bounds: ) => void

A callback that fires when the visible area of the map changes (for example, after the user pans the map). Receives the new bounding box as a MapBounds object with northEast and southWest corners.

Anchor to onCenterChange
onCenterChange
(location: ) => void

A callback that fires when the center point of the map changes (for example, after the user pans the map). Receives the new center as a MapLocation coordinate pair.

Anchor to onDoublePress
onDoublePress
(location: ) => void

A callback that fires when the user double-presses (double-clicks) the map. Receives the geographic MapLocation coordinate pair of the double-press point.

Anchor to onPress
onPress
(location: ) => void

A callback that fires when the user presses (clicks or taps) the map. Receives the geographic MapLocation coordinate pair of the press point.

Anchor to onZoomChange
onZoomChange
(zoom: ) => void

A callback that fires when the map's zoom level changes (for example, after the user pinches to zoom or uses the zoom controls). Receives the new zoom level as a MapZoom value (1–18).

Anchor to zoom
zoom
number

The initial zoom level of the map. Must be an integer between 0 and 18, where lower values show a wider area and higher values show more detail.

Anchor to ExamplesExamples

Anchor to Basic MapBasic Map

Basic Map

Example

Basic Map

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

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

function Extension() {
return (
<Map
apiKey="YOUR_GOOGLE_MAPS_API_KEY"
latitude={-28.024}
longitude={140.887}
zoom={4}
accessibilityLabel="Map showing pickup locations"
/>
);
}
import {extension, Map} from '@shopify/ui-extensions/checkout';

export default extension('purchase.checkout.block.render', (root) => {
const map = root.createComponent(Map, {
apiKey: 'YOUR_API_KEY',
accessibilityLabel: 'Map showing pickup locations',
latitude: -28.024,
longitude: 140.887,
zoom: 4,
});

root.appendChild(map);
});

Anchor to Best practicesBest practices

  • Use a relevant default view: Set the initial map center and zoom levels to frame the most relevant area for the buyer and ensure that relevant markers are visible without having to pan or zoom.
  • Use markers sparingly: Limit the number of markers to avoid cluttering the map. For many locations, consider setting the markers to clusterable or showing a list alongside the map.
  • Use distinct markers to illustrate state: If your markers are interactive, make sure the selected marker's icon is visually different from non-selected markers so buyers can identify their selection.
  • Provide fallback text: Ensure that address information is also displayed as text for buyers who can't interact with the map or in case the map can't load.

Anchor to LimitationsLimitations

  • The map requires a Google Maps API key and a set of allowed domains where the map renders. Refer to the Google Maps Platform documentation for details on obtaining an API key.
  • Map rendering depends on the buyer's network connection and Google Maps availability. Offline map rendering isn't supported and the Map component doesn't provide a built-in fallback for offline scenarios.

Anchor to RelatedRelated

ComponentMapMarker
ComponentMapPopover
Was this page helpful?