Map
Use Map to display a map on a page. This component is useful for displaying a map of a location, such as a store or a customer’s address.
Supported targets
- purchase.
checkout. actions. render-before - purchase.
checkout. block. render - purchase.
checkout. cart-line-item. render-after - purchase.
checkout. cart-line-list. render-after - purchase.
checkout. contact. render-after - purchase.
checkout. delivery-address. render-after - purchase.
checkout. delivery-address. render-before - purchase.
checkout. footer. render-after - purchase.
checkout. header. render-after - purchase.
checkout. payment-method-list. render-after - purchase.
checkout. payment-method-list. render-before - purchase.
checkout. pickup-location-list. render-after - purchase.
checkout. pickup-location-list. render-before - purchase.
checkout. pickup-location-option-item. render-after - purchase.
checkout. pickup-point-list. render-after - purchase.
checkout. pickup-point-list. render-before - purchase.
checkout. reductions. render-after - purchase.
checkout. reductions. render-before - purchase.
checkout. shipping-option-item. details. render - purchase.
checkout. shipping-option-item. render-after - purchase.
checkout. shipping-option-list. render-after - purchase.
checkout. shipping-option-list. render-before - purchase.
thank-you. announcement. render - purchase.
thank-you. block. render - purchase.
thank-you. cart-line-item. render-after - purchase.
thank-you. cart-line-list. render-after - purchase.
thank-you. customer-information. render-after - purchase.
thank-you. footer. render-after - purchase.
thank-you. header. render-after
Supported targets
- purchase.
checkout. actions. render-before - purchase.
checkout. block. render - purchase.
checkout. cart-line-item. render-after - purchase.
checkout. cart-line-list. render-after - purchase.
checkout. contact. render-after - purchase.
checkout. delivery-address. render-after - purchase.
checkout. delivery-address. render-before - purchase.
checkout. footer. render-after - purchase.
checkout. header. render-after - purchase.
checkout. payment-method-list. render-after - purchase.
checkout. payment-method-list. render-before - purchase.
checkout. pickup-location-list. render-after - purchase.
checkout. pickup-location-list. render-before - purchase.
checkout. pickup-location-option-item. render-after - purchase.
checkout. pickup-point-list. render-after - purchase.
checkout. pickup-point-list. render-before - purchase.
checkout. reductions. render-after - purchase.
checkout. reductions. render-before - purchase.
checkout. shipping-option-item. details. render - purchase.
checkout. shipping-option-item. render-after - purchase.
checkout. shipping-option-list. render-after - purchase.
checkout. shipping-option-list. render-before - purchase.
thank-you. announcement. render - purchase.
thank-you. block. render - purchase.
thank-you. cart-line-item. render-after - purchase.
thank-you. cart-line-list. render-after - purchase.
thank-you. customer-information. render-after - purchase.
thank-you. footer. render-after - purchase.
thank-you. header. render-after
Anchor to propertiesProperties
- Anchor to accessibilityLabelaccessibilityLabelaccessibilityLabelstringstring
A label that describes the purpose or contents of the map for accessibility. When set, it will be announced to users using assistive technologies such as screen readers, providing context about what the map displays.
- Anchor to apiKeyapiKeyapiKeystringstring
A valid API key for the map service provider. This key is required to load and render the map tiles. Obtain a key from a supported provider such as Google Maps Platform.
- Anchor to blockSizeblockSizeblockSizeMaybeResponsive<SizeUnitsOrAuto>MaybeResponsive<SizeUnitsOrAuto>Default: 'auto'Default: 'auto'
The block size of the element (height in horizontal writing modes). Learn more about the block-size property.
: Specific size values in pixels, percentages, or zero for precise control.auto: Automatically sizes based on content and layout constraints.
- Anchor to idididstringstring
A unique identifier for the element. Use this to reference the element in JavaScript, link labels to form controls, or target specific elements for styling or scripting.
- Anchor to inlineSizeinlineSizeinlineSizeMaybeResponsive<SizeUnitsOrAuto>MaybeResponsive<SizeUnitsOrAuto>Default: 'auto'Default: 'auto'
The inline size of the element (width in horizontal writing modes). Learn more about the inline-size property.
: Specific size values in pixels, percentages, or zero for precise control.auto: Automatically sizes based on content and layout constraints.
- Anchor to latitudelatitudelatitudenumbernumberDefault: 0Default: 0
The latitude of the map's center point, in degrees. Valid values range from -90 (South Pole) to 90 (North Pole).
- Anchor to longitudelongitudelongitudenumbernumberDefault: 0Default: 0
The longitude of the map's center point, in degrees. Valid values range from -180 (west) to 180 (east).
- Anchor to maxBlockSizemaxBlockSizemaxBlockSizeMaybeResponsive<SizeUnitsOrNone>MaybeResponsive<SizeUnitsOrNone>Default: 'none'Default: 'none'
The maximum block size of the element (maximum height in horizontal writing modes). Learn more about the max-block-size property.
- Anchor to maxInlineSizemaxInlineSizemaxInlineSizeMaybeResponsive<SizeUnitsOrNone>MaybeResponsive<SizeUnitsOrNone>Default: 'none'Default: 'none'
The maximum inline size of the element (maximum width in horizontal writing modes). Learn more about the max-inline-size property.
- Anchor to maxZoommaxZoommaxZoomnumbernumberDefault: 18Default: 18
The maximum zoom level the user can reach on the map. Valid values are numbers from 0 (world view) to 18 (street level). Use this to prevent users from zooming in beyond a useful level of detail.
- Anchor to minBlockSizeminBlockSizeminBlockSizeMaybeResponsive<SizeUnits>MaybeResponsive<SizeUnits>Default: '0'Default: '0'
The minimum block size of the element (minimum height in horizontal writing modes). Learn more about the min-block-size property.
- Anchor to minInlineSizeminInlineSizeminInlineSizeMaybeResponsive<SizeUnits>MaybeResponsive<SizeUnits>Default: '0'Default: '0'
The minimum inline size of the element (minimum width in horizontal writing modes). Learn more about the min-inline-size property.
- Anchor to minZoomminZoomminZoomnumbernumberDefault: 0Default: 0
The minimum zoom level the user can reach on the map. Valid values are numbers from 0 (world view) to 18 (street level). Use this to prevent users from zooming out beyond a useful level of context.
- Anchor to zoomzoomzoomnumbernumberDefault: 4Default: 4
The initial zoom level of the map. Valid values are numbers from 0 (fully zoomed out, world view) to 18 (fully zoomed in, street level).
MaybeResponsive
Makes a property responsive by allowing it to be set conditionally based on container query conditions. The value can be either a base value or a container query string. - `T`: Base value that applies in all conditions. - `@container${string}`: Container query string for conditional responsive styling based on container size.
T | `@container${string}`SizeUnitsOrAuto
Represents size values that can also be set to `auto` for automatic sizing. - `SizeUnits`: Specific size values in pixels, percentages, or zero for precise control. - `auto`: Automatically sizes based on content and layout constraints. Learn more about the [auto value](https://developer.mozilla.org/en-US/docs/Web/CSS/width#auto).
SizeUnits | "auto"SizeUnits
Represents size values in pixels, percentages, or zero. - `` `${number}px` ``: Absolute size in pixels for fixed dimensions (such as `100px`, `24px`). - `` `${number}%` ``: Relative size as a percentage of the parent container (such as `50%`, `100%`). - `0`: Zero size, equivalent to no dimension.
`${number}px` | `${number}%` | `0`SizeUnitsOrNone
Represents size values that can also be set to `none` to remove the size constraint. - `SizeUnits`: Specific size values in pixels, percentages, or zero for precise control. - `none`: No size constraint, allowing unlimited growth. Learn more about the [none value](https://developer.mozilla.org/en-US/docs/Web/CSS/max-width#none).
SizeUnits | "none"Anchor to eventsEvents
Learn more about registering events.
- Anchor to boundschangeboundschangeboundschangeCallbackEventListener<typeof tagName, MapBoundsEvent>CallbackEventListener<typeof tagName, MapBoundsEvent>
A callback fired when the visible map boundaries change, such as after a pan or zoom completes.
- Anchor to clickclickclickCallbackEventListener<typeof tagName, MapLocationEvent>CallbackEventListener<typeof tagName, MapLocationEvent>
A callback fired when the user clicks on the map. Provides the geographic location of the click.
- Anchor to dblclickdblclickdblclickCallbackEventListener<typeof tagName, MapLocationEvent>CallbackEventListener<typeof tagName, MapLocationEvent>
A callback fired when the user double-clicks on the map. Provides the geographic location of the double-click.
- Anchor to viewchangeviewchangeviewchangeCallbackEventListener<typeof tagName, MapViewChangeEvent>CallbackEventListener<typeof tagName, MapViewChangeEvent>
A callback fired when the map view changes, such as when the user pans or zooms. Provides the new center location and zoom level.
CallbackEventListener
An event listener typed to a specific HTML element, with a strongly typed `currentTarget`.
(EventListener & {
(event: CallbackEvent<TTagName, Event> & TData): void;
}) | nullCallbackEvent
A callback event typed to a specific HTML element, with a strongly typed `currentTarget`.
TEvent & {
currentTarget: HTMLElementTagNameMap[TTagName];
}MapBoundsEvent
The event data provided when the visible map boundaries change, such as after a pan or zoom completes. Contains the new geographic bounds of the visible area.
- bounds
The geographic boundaries of the currently visible map area, defined by its north-east and south-west corners.
{ northEast?: MapLocation; southWest?: MapLocation; }
MapLocation
A geographic coordinate pair representing a location on the map, defined by latitude and longitude values.
- latitude
The latitude of the location in degrees. Valid values range from -90 (South Pole) to 90 (North Pole).
number - longitude
The longitude of the location in degrees. Valid values range from -180 (west) to 180 (east).
number
MapLocationEvent
The event data provided when a map interaction occurs at a specific geographic location, such as a click or double-click.
- location
The geographic location on the map where the interaction occurred, as a latitude/longitude coordinate pair.
MapLocation
MapViewChangeEvent
The event data provided when the map view changes, such as after the user pans or zooms. Contains the new center location and zoom level.
- location
The geographic location on the map where the interaction occurred, as a latitude/longitude coordinate pair.
MapLocation - zoom
The current zoom level of the map after the view change, as a number from 0 (world view) to 18 (street level).
number
Anchor to map markerMap marker
Use MapMarker to display a marker on a map. Use only as a child of s-map component.
- Anchor to accessibilityLabelaccessibilityLabelaccessibilityLabelstringstring
A label that describes the purpose or location of the marker for accessibility. When set, it will be announced to users using assistive technologies such as screen readers, providing context about what the marker represents.
- Anchor to blockSizeblockSizeblockSizeMaybeResponsive<SizeUnitsOrAuto>MaybeResponsive<SizeUnitsOrAuto>Default: 'auto'Default: 'auto'
The block size of the element (height in horizontal writing modes). Learn more about the block-size property.
: Specific size values in pixels, percentages, or zero for precise control.auto: Automatically sizes based on content and layout constraints.
- Anchor to clusterableclusterableclusterablebooleanbooleanDefault: falseDefault: false
Whether the marker can be grouped into clusters when the map is zoomed out. Clustering helps reduce visual clutter when many markers are close together at low zoom levels.
- Anchor to commandcommandcommand'--auto' | '--show' | '--hide' | '--toggle''--auto' | '--show' | '--hide' | '--toggle'Default: '--auto'Default: '--auto'
Sets the action the
target should take when this marker is activated. See the documentation of particular components for the actions they support. Learn more about thecommandattribute.--auto: a default action for the target component.--show: shows the target component.--hide: hides the target component.--toggle: toggles the target component.
- Anchor to commandForcommandForcommandForstringstring
The ID of a component that should respond to activations (for example, clicks) on this component. Refer to the
commandproperty for how to control the behavior of the target. Learn more about thecommandforattribute.- Anchor to inlineSizeinlineSizeinlineSizeMaybeResponsive<SizeUnitsOrAuto>MaybeResponsive<SizeUnitsOrAuto>Default: 'auto'Default: 'auto'
The inline size of the element (width in horizontal writing modes). Learn more about the inline-size property.
: Specific size values in pixels, percentages, or zero for precise control.auto: Automatically sizes based on content and layout constraints.
- Anchor to latitudelatitudelatitudenumbernumberDefault: 0Default: 0
The latitude of the marker’s position in degrees. Valid values range from -90 (South Pole) to 90 (North Pole).
- Anchor to longitudelongitudelongitudenumbernumberDefault: 0Default: 0
The longitude of the marker’s position in degrees. Valid values range from -180 (west) to 180 (east).
Anchor to eventsEvents
Learn more about registering events.
- Anchor to clickclickclickCallbackEventListener<typeof tagName>CallbackEventListener<typeof tagName>
A callback fired when the user clicks on the marker. This event does not propagate to the parent map — only the marker receives the click.
Anchor to slotsSlots
Learn more about component slots.
- Anchor to graphicgraphicgraphicHTMLElementHTMLElement
A custom graphic element to use as the marker. If not provided, the map provider’s default marker pin is displayed.
Preview

Examples
Code
Default
<s-map apiKey="YOUR_API_KEY" latitude={51.5074} longitude={-0.1278}> <s-map-marker latitude={51.5074} longitude={-0.1278}></s-map-marker> </s-map>Popover with map marker
Description
Use the `Popover` component to display content when a map marker is clicked.
Default
<s-map apiKey="YOUR_API_KEY" blockSize="400px" inlineSize="400px" latitude={37.7749} longitude={-122.4194} > <s-map-marker latitude={37.7749} longitude={-122.4194} commandFor="popover-san-francisco" ></s-map-marker> <s-popover id="popover-san-francisco">San Francisco</s-popover> </s-map>Map with graphic as map marker
Description
Use the `graphic` slot to display a graphic as a map marker. Find more about slots [here](/docs/api/checkout-ui-extensions/2026-04/using-polaris-components#slots).
Default
<s-map apiKey="YOUR_API_KEY" blockSize="400px" inlineSize="400px" latitude={37.7749} longitude={-122.4194} > <s-map-marker latitude={37.7749} longitude={-122.4194} > <s-image src="https://cdn.shopify.com/YOUR_IMAGE_HERE" slot="graphic"></s-image> </s-map-marker> </s-map>