--- title: Map description: >- The map component displays an interactive map with location markers during checkout. Use map for store finders, delivery confirmation, pickup points, and other location context. api_version: 2026-04 api_name: checkout-ui-extensions source_url: html: >- https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/media-and-visuals/map md: >- https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/media-and-visuals/map.md --- # Map The map component displays an interactive map with location markers during checkout. Use map for store finders, delivery confirmation, pickup points, and other location context. Map components support markers, popovers, and custom marker graphics through the `graphic` slot. For a static map image without panning or zooming, use [image](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/media-and-visuals/image) instead. Map requires a Google Maps API key and a set of allowed domains where the map renders. Refer to the [Google Maps Platform documentation](https://developers.google.com/maps/documentation/javascript/get-api-key) for details on obtaining an API key. Rendering depends on the buyer's network connection and Google Maps availability — offline rendering isn't supported. ### Support Targets (29) ### Supported targets * [purchase.​checkout.​actions.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/navigation#navigation-target) * [purchase.​checkout.​block.​render](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/block#block-target) * [purchase.​checkout.​cart-line-item.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/order-summary#line-item-targets) * [purchase.​checkout.​cart-line-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/order-summary#checkout-cart-line-list-) * [purchase.​checkout.​contact.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/information#information-target) * [purchase.​checkout.​delivery-address.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/shipping#render-after-delivery-address-) * [purchase.​checkout.​delivery-address.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/shipping#delivery-address-targets) * [purchase.​checkout.​footer.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/footer#footer-target) * [purchase.​checkout.​header.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/header#header-target) * [purchase.​checkout.​payment-method-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/payment#render-after-payment-methods-) * [purchase.​checkout.​payment-method-list.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/payment#payment-targets) * [purchase.​checkout.​pickup-location-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/local-pickup#render-after-pickup-locations-) * [purchase.​checkout.​pickup-location-list.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/local-pickup#location-list-targets) * [purchase.​checkout.​pickup-location-option-item.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/local-pickup#location-option-item-target) * [purchase.​checkout.​pickup-point-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/pickup-points#render-after-pickup-points-) * [purchase.​checkout.​pickup-point-list.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/pickup-points#pickup-points-targets) * [purchase.​checkout.​reductions.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/order-summary#checkout-reductions-after-) * [purchase.​checkout.​reductions.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/order-summary#reductions-targets) * [purchase.​checkout.​shipping-option-item.​details.​render](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/shipping#shipping-option-item-targets) * [purchase.​checkout.​shipping-option-item.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/shipping#render-after-shipping-option-) * [purchase.​checkout.​shipping-option-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/shipping#render-after-shipping-options-) * [purchase.​checkout.​shipping-option-list.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/shipping#shipping-option-list-targets) * [purchase.​thank-you.​announcement.​render](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/announcement#thank-you-announcement-) * [purchase.​thank-you.​block.​render](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/block#block-target) * [purchase.​thank-you.​cart-line-item.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/order-summary#line-item-targets) * [purchase.​thank-you.​cart-line-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/order-summary#thank-you-cart-line-list-) * [purchase.​thank-you.​customer-information.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/information#information-target) * [purchase.​thank-you.​footer.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/footer#footer-target) * [purchase.​thank-you.​header.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/header#header-target) #### Use cases * **Store locator**: Display a map centered on the nearest store with a marker showing the pickup address. * **Delivery visualization**: Show the delivery destination on a map to confirm the shipping address visually. * **Pickup point selection**: Present multiple pickup locations as markers so buyers can compare proximity. * **Custom marker branding**: Replace default markers with branded graphics using the `graphic` slot for visual consistency. *** ## Properties Configure the following properties on the map component. * **accessibilityLabel** **string** 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. * **apiKey** **string** 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](https://developers.google.com/maps/documentation/javascript/get-api-key). * **blockSize** **MaybeResponsive\** **Default: 'auto'** The block size of the element (height in horizontal writing modes). Learn more about the [block-size property](https://developer.mozilla.org/en-US/docs/Web/CSS/block-size). * `SizeUnits`: Specific size values in pixels, percentages, or zero for precise control. * `auto`: Automatically sizes based on content and layout constraints. * **id** **string** 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. * **inlineSize** **MaybeResponsive\** **Default: 'auto'** The inline size of the element (width in horizontal writing modes). Learn more about the [inline-size property](https://developer.mozilla.org/en-US/docs/Web/CSS/inline-size). * `SizeUnits`: Specific size values in pixels, percentages, or zero for precise control. * `auto`: Automatically sizes based on content and layout constraints. * **latitude** **number** **Default: 0** The latitude of the map's center point, in degrees. Valid values range from -90 (South Pole) to 90 (North Pole). * **longitude** **number** **Default: 0** The longitude of the map's center point, in degrees. Valid values range from -180 (west) to 180 (east). * **maxBlockSize** **MaybeResponsive\** **Default: 'none'** The maximum block size of the element (maximum height in horizontal writing modes). Learn more about the [max-block-size property](https://developer.mozilla.org/en-US/docs/Web/CSS/max-block-size). * **maxInlineSize** **MaybeResponsive\** **Default: 'none'** The maximum inline size of the element (maximum width in horizontal writing modes). Learn more about the [max-inline-size property](https://developer.mozilla.org/en-US/docs/Web/CSS/max-inline-size). * **maxZoom** **number** **Default: 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. * **minBlockSize** **MaybeResponsive\** **Default: '0'** The minimum block size of the element (minimum height in horizontal writing modes). Learn more about the [min-block-size property](https://developer.mozilla.org/en-US/docs/Web/CSS/min-block-size). * **minInlineSize** **MaybeResponsive\** **Default: '0'** The minimum inline size of the element (minimum width in horizontal writing modes). Learn more about the [min-inline-size property](https://developer.mozilla.org/en-US/docs/Web/CSS/min-inline-size). * **minZoom** **number** **Default: 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. * **zoom** **number** **Default: 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. ```ts 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). ```ts 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. ```ts `${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). ```ts SizeUnits | "none" ``` ### Events The map component provides event callbacks for handling user interactions. Learn more about [handling events](https://shopify.dev/docs/api/polaris/using-polaris-web-components#handling-events). * **boundschange** **CallbackEventListener\** A callback fired when the visible map boundaries change, such as after a pan or zoom completes. * **click** **CallbackEventListener\** A callback fired when the user clicks on the map. Provides the geographic location of the click. * **dblclick** **CallbackEventListener\** A callback fired when the user double-clicks on the map. Provides the geographic location of the double-click. * **viewchange** **CallbackEventListener\** 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 A typed event listener for custom element events. The listener receives a \`CallbackEvent\` with the correct \`currentTarget\` type for the associated custom element tag. ```ts (EventListener & { (event: CallbackEvent & TData): void; }) | null ``` ### CallbackEvent An event type that narrows the \`currentTarget\` to the specific HTML element associated with the custom element tag. This provides type-safe event handling in callback listeners. ```ts 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. ```ts { 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). ```ts number ``` * longitude The longitude of the location in degrees. Valid values range from -180 (west) to 180 (east). ```ts 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. ```ts 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. ```ts MapLocation ``` * zoom The current zoom level of the map after the view change, as a number from 0 (world view) to 18 (street level). ```ts number ``` *** ## Map marker Use MapMarker to display a marker on a map. Use only as a child of `s-map` component. * **accessibilityLabel** **string** 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. * **blockSize** **MaybeResponsive\** **Default: 'auto'** The block size of the element (height in horizontal writing modes). Learn more about the [block-size property](https://developer.mozilla.org/en-US/docs/Web/CSS/block-size). * `SizeUnits`: Specific size values in pixels, percentages, or zero for precise control. * `auto`: Automatically sizes based on content and layout constraints. * **clusterable** **boolean** **Default: 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. * **command** **'--auto' | '--show' | '--hide' | '--toggle'** **Default: '--auto'** Sets the action the `commandFor` target should take when this component is activated. Learn more about the [`command` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#command). * `--auto`: a default action for the target component. * `--show`: shows the target component. * `--hide`: hides the target component. * `--toggle`: toggles the target component. * **commandFor** **string** The ID of the component to control when this component is activated. Pair with the `command` property to specify what action to perform on the target component. Learn more about the [`commandFor` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#commandfor). * **inlineSize** **MaybeResponsive\** **Default: 'auto'** The inline size of the element (width in horizontal writing modes). Learn more about the [inline-size property](https://developer.mozilla.org/en-US/docs/Web/CSS/inline-size). * `SizeUnits`: Specific size values in pixels, percentages, or zero for precise control. * `auto`: Automatically sizes based on content and layout constraints. * **latitude** **number** **Default: 0** The latitude of the marker’s position in degrees. Valid values range from -90 (South Pole) to 90 (North Pole). * **longitude** **number** **Default: 0** The longitude of the marker’s position in degrees. Valid values range from -180 (west) to 180 (east). ### Events The map marker component provides event callbacks for handling user interactions. Learn more about [handling events](https://shopify.dev/docs/api/polaris/using-polaris-web-components#handling-events). * **click** **CallbackEventListener\** 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. ### Slots The map marker component supports slots for additional content placement within the component. Learn more about [using slots](https://shopify.dev/docs/api/polaris/using-polaris-web-components#slots). * **graphic** **HTMLElement** A custom graphic element to use as the marker. If not provided, the map provider’s default marker pin is displayed. *** ## Examples ### Pin a location on a map Embed an interactive map with a marker at a specific location. This example renders an `s-map` centered on London with an `s-map-marker` placed at the same coordinates. ## Pin a location on a map ![A rendered example of the map component](https://shopify.dev/assets/assets/images/templated-apis-screenshots/checkout-ui-extensions/2025-10/map-default-i6aQsCgC.png) ## html ```html ``` ### Show a popover from a map marker Display additional details when a buyer taps a marker. This example uses a `Popover` component to present content anchored to an `s-map-marker`. ## html ```html San Francisco ``` ### Use a graphic as the map marker Replace the default marker with a custom graphic. This example demonstrates the `graphic` slot on `s-map-marker` to display a branded icon instead of the standard pin. ## html ```html ``` *** ## Best 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. ***