Choose a version:

Map

The map component displays an interactive map on a page. Use map to show geographic locations such as store addresses, pickup points, or customer delivery destinations.

Maps render using Google Maps and require an API key along with a set of allowed domains. You can add markers to highlight specific locations and attach popovers to provide additional details about each point.

Map requires a Google Maps API key with the following allowed domains: https://*.[MERCHANT-DOMAIN].com, https://shop.app, and https://shopify.com. Refer to the Google Maps Platform documentation for details on obtaining an API key, and to match patterns for the domain syntax. Rendering depends on the customer's network connection and Google Maps availability — there's no built-in offline fallback.

Support

Targets (24)

Supported targets

Anchor to PropertiesProperties

Configure the following properties on the map component.

Anchor to accessibilityLabel 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.
Anchor to apiKey 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.
Anchor to blockSize blockSize <> Default: 'auto': The block size of the element (height in horizontal writing modes). Learn more about the block-size property.

SizeUnits: Specific size values in pixels, percentages, or zero for precise control.

auto: Automatically sizes based on content and layout constraints.
Anchor to id 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.
Anchor to inlineSize inlineSize <> Default: 'auto': The inline size of the element (width in horizontal writing modes). Learn more about the inline-size property.

SizeUnits: Specific size values in pixels, percentages, or zero for precise control.

auto: Automatically sizes based on content and layout constraints.
Anchor to latitude 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).
Anchor to longitude longitude number Default: 0: The longitude of the map's center point, in degrees. Valid values range from -180 (west) to 180 (east).
Anchor to maxBlockSize maxBlockSize <> 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 maxInlineSize maxInlineSize <> 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 maxZoom 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.
Anchor to minBlockSize minBlockSize <> 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 minInlineSize minInlineSize <> 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 minZoom 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.
Anchor to zoom 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.

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

The map component provides event callbacks for handling user interactions. Learn more about handling events.

Anchor to boundschange boundschange <typeof tagName, >: A callback fired when the visible map boundaries change, such as after a pan or zoom completes.
Anchor to click click <typeof tagName, >: A callback fired when the user clicks on the map. Provides the geographic location of the click.
Anchor to dblclick dblclick <typeof tagName, >: A callback fired when the user double-clicks on the map. Provides the geographic location of the double-click.
Anchor to viewchange viewchange <typeof tagName, >: 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.

(EventListener & {
      (event: CallbackEvent<TTagName, TEvent>): 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.

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

Represents a pin or point of interest on a map. Use only as a child of s-map components.

Anchor to accessibilityLabel 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.
Anchor to blockSize blockSize <> Default: 'auto': The block size of the element (height in horizontal writing modes). Learn more about the block-size property.

SizeUnits: Specific size values in pixels, percentages, or zero for precise control.

auto: Automatically sizes based on content and layout constraints.
Anchor to clusterable 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.
Anchor to command 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.

--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 commandFor 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.
Anchor to inlineSize inlineSize <> Default: 'auto': The inline size of the element (width in horizontal writing modes). Learn more about the inline-size property.

SizeUnits: Specific size values in pixels, percentages, or zero for precise control.

auto: Automatically sizes based on content and layout constraints.
Anchor to latitude latitude number Default: 0: The latitude of the marker’s position in degrees. Valid values range from -90 (South Pole) to 90 (North Pole).
Anchor to longitude longitude number Default: 0: The longitude of the marker’s position in degrees. Valid values range from -180 (west) to 180 (east).

Anchor to EventsEvents

The map marker component provides event callbacks for handling user interactions. Learn more about handling events.

Anchor to click click <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

The map marker component supports slots for additional content placement within the component. Learn more about using slots.

Anchor to graphic graphic HTMLElement: A custom graphic element to use as the marker. If not provided, the map provider’s default marker pin is displayed.

Anchor to ExamplesExamples

Anchor to Display a locationDisplay a location

Show a single location on a map with a marker. This example centers the map on a specific latitude and longitude with a zoom level that provides street-level context.

Display a location

A map displaying a single location with a marker.

html

<s-map apiKey="YOUR_API_KEY" latitude={40.7128} longitude={-74.0060} zoom={14}>

<s-map-marker latitude={40.7128} longitude={-74.0060} accessibilityLabel="Store location"></s-map-marker>

</s-map>

Anchor to Add multiple markersAdd multiple markers

Display several locations on a single map. This example places three markers at different coordinates with a zoom level that fits all locations in view.

html

<s-map apiKey="YOUR_API_KEY" latitude={40.7128} longitude={-74.0060} zoom={12}>

<s-map-marker

latitude={40.7128}

longitude={-74.0060}

accessibilityLabel="Downtown store"

></s-map-marker>

<s-map-marker

latitude={40.7580}

longitude={-73.9855}

accessibilityLabel="Midtown store"

></s-map-marker>

<s-map-marker

latitude={40.7282}

longitude={-73.7949}

accessibilityLabel="Queens store"

></s-map-marker>

</s-map>

Anchor to Handle map eventsHandle map events

Respond to customer interactions with the map. This example listens for click events and displays the selected coordinates in a text element below the map.

html

<s-stack gap="base">

<s-map id="store-map" apiKey="YOUR_API_KEY" latitude={40.7128} longitude={-74.0060} zoom={12}>

<s-map-marker latitude={40.7128} longitude={-74.0060} accessibilityLabel="Store location"></s-map-marker>

</s-map>

<s-text id="selected-location">Click a location on the map</s-text>

</s-stack>

const map = document.getElementById('store-map');

const selectedLocation = document.getElementById('selected-location');

map.addEventListener('click', (event) => {

const {location} = event.detail;

selectedLocation.textContent = `Selected: ${location.latitude}, ${location.longitude}`;

});

</script>

Anchor to Show a pickup locationShow a pickup location

Present a pickup point within a section with a text address. This example combines a map with supporting text so customers can identify the location visually and by address.

html

<s-section>

<s-heading>Pickup location</s-heading>

<s-stack gap="base">

<s-map apiKey="YOUR_API_KEY" latitude={40.7128} longitude={-74.0060} zoom={15} blockSize="200px">

<s-map-marker latitude={40.7128} longitude={-74.0060} accessibilityLabel="Pickup point"></s-map-marker>

</s-map>

<s-text>123 Main Street, New York, NY 10001</s-text>

</s-stack>

</s-section>

Anchor to Best practicesBest practices

Provide a sensible default view: Set the initial map center and zoom level so that all relevant markers are visible without requiring the customer to pan or zoom.
Use distinct marker icons for different states: If your markers are interactive, make sure the selected marker's icon is visually different from non-selected markers so customers can identify their selection.
Cluster markers when displaying many locations: If there are a large number of markers obscuring important features of the map, set the markers to clusterable to help increase readability.
Include supporting context: Pair the map with text-based address information so customers who can't interact with the map still have access to the location details.

Was this page helpful?