HelixOverviewComponentsMapsGraphIntroductionInstallationDeriving a themeSandboxTheme builderVisual testingCortexDocsEngramBuildingTraceBuildingRecallDeclaredServicesInsightsGet in touchSource on GitHub
Loading the reference
MapView SourceEdit in SandboxView MarkdownCopy MarkdownOpen in ClaudeOpen in CursorA frame around a map drawn by another library.StableSince 0.100.0MediaUsageimport'@fusion.dev/helix/map'import'@fusion.dev/helix-headless/map'Preview
API ReferenceRoothelix-mapA frame around a map drawn by another library.
PropTypeDescriptionactivateHintLabelstringDefault"Press the map to use it"The hint shown when a surface waiting to be pressed is scrolled or
swiped over, with gestures="activate". Each family declares it as a
word property with its own English, such as "Press the map to use it".bearingnumberDefault0The map's rotation, in degrees clockwise from north. connectMap keeps it
current, and the Face north button's needle turns with it.clusterbooleanDefaultfalseCombines markers that would overlap into one count. Counts split apart as
the map zooms in, and pressing one zooms in to its places.controlsstringWhich controls to show, as a list such as pan zoom fullscreen, or
none. A family can add words of its own.controlsLabelstringDefault"Map controls"The name of the group of controls, read by screen readers. Each family
declares it as a word property with its own English, "Map controls" or
"Board controls", which names what the controls drive rather than the
mechanism.controlsPlacement"top-start"|"top-end"|"bottom-start"|"bottom-end"Which corner the controls sit in.creditPlacement"bottom-end"|"bottom-start"Where the map's credit is drawn. Unset, it is a strip under the map.
bottom-end or bottom-start draws it in that corner over the map, on
one line that shows the whole credit on hover or focus, the form
OpenStreetMap's attribution guidance accepts for a small credit. Keep it
clear of a corner the controls are in.faceNorthLabelstringDefault"Face north"The Face north button's label.fallbackLabelstringDefault"Map"The map's name where label is empty and the host has no aria-label.fillbooleanDefaultfalseCovers the container instead of taking a height of its own, for a map
behind a page's content. The container needs a position, such as
position: relative. The frame draws no border or corners then, since
the container's edge is the map's.flatLabelstringDefault"Looking straight down"What screen readers hear when the map is tilted back to looking straight down.fullscreenLabelstringDefault"Fill the screen"The fullscreen button's label.gestures"activate"|"always"|"cooperative"Which gestures the surface takes from the page.hybridLabelstringDefault"Hybrid"The Hybrid map type's name.idleDelaynumberDefault0How long, in milliseconds, before the header and footer hide when the
user is inactive. 0 keeps them visible. The attribute also takes a CSS
time, such as 3s.labelstringDefault""The map's name, read by screen readers. Name the place, such as "Delivery
area", so that several maps on one page can be told apart. Required.layersLabelstringDefault"Map layers"The name of the layers button and menu, and of the list of the map's
layers, such as routes, areas, and points, read by screen readers.mapType"hybrid"|"satellite"How the map draws the ground, where it has imagery: hybrid for imagery
under the roads and names, and satellite for imagery alone. Absent is
the standard, themed map. The layers menu chooses it.mapTypeLabelstringDefault"Map type"The name of the map types in the layers menu, read by screen readers.material"frosted"|"glass"|"transparent"The background of the pan and zoom buttons. Leave unset for solid. glass
shows the map through a blur, frosted blurs more, and transparent has
no background. Your theme sets how see-through each one is.movedDownLabelstringDefault"Moved down"What screen readers hear when the map has moved down.movedLeftLabelstringDefault"Moved left"What screen readers hear when the map has moved left.movedRightLabelstringDefault"Moved right"What screen readers hear when the map has moved right.movedUpLabelstringDefault"Moved up"What screen readers hear when the map has moved up.northLabelstringDefault"Facing north"What screen readers hear when the map is turned back to face north.panDownLabelstringDefault"Pan down"The pan down button's label.panLeftLabelstringDefault"Pan left"The pan left button's label.panRightLabelstringDefault"Pan right"The pan right button's label.panStepnumberDefault0.25How far one press pans the view, as a fraction of its size.panUpLabelstringDefault"Pan up"The pan up button's label.pitchnumberDefault0How far the map is tilted, in degrees from looking straight down.
connectMap keeps it current, and the 3D button is pressed while it is
above 0.roleLabelstringDefault"map"What a screen reader calls the map in place of its role, after its
name: "Edinburgh, map". Said only where the map has a name of its
own, since the fallback name is the same word. Empty leaves the role.rotateLeftLabelstringDefault"Rotate left"The rotate left button's label.rotateRightLabelstringDefault"Rotate right"The rotate right button's label.satelliteLabelstringDefault"Satellite"The Satellite map type's name.standardLabelstringDefault"Standard"The Standard map type's name.tiltedLabelstringDefault"{degrees, plural, one {Tilted # degree} other {Tilted # degrees}}"What screen readers hear when the map is tilted. {degrees} is the tilt
from looking straight down, written in the locale, and each language
writes the forms it has.tiltLabelstringDefault"Show in 3D"The 3D button's label.turnedLabelstringDefault"{degrees, plural, one {Facing # degree} other {Facing # degrees}}"What screen readers hear when the map is turned. {degrees} is the way the
top of the map faces, clockwise from north, written in the locale, and
each language writes the forms it has.twoFingerHintLabelstringDefault"Use two fingers to move the map"The hint shown when one finger swipes over a surface with
gestures="cooperative". Each family declares it as a word property.usingLabelstringDefault"Using the map. Press Escape to scroll the page again."The line shown while a surface with gestures="activate" has the
gestures. Each family declares it as a word property.wheelHintLabelstringDefault"Use {key} and scroll to zoom the map"The hint shown when the wheel scrolls past a surface with
gestures="cooperative", with {key}. Each family declares it as a
word property.zoomedLabelstringDefault"Zoom level {level}"What screen readers hear after a zoom. {level} is the zoom level,
written in the locale.zoomInLabelstringDefault"Zoom in"The zoom in button's label.zoomLevelnumberHow far the map is zoomed, in its renderer's levels. connectMap keeps it
current, and the map says it after a zoom.zoomOutLabelstringDefault"Zoom out"The zoom out button's label.
ReadTypeDescriptionreadybooleanWhether the map has been drawn whole, which drawn() says. For a page that
connects after helix-map-ready has been sent, and missed it.whenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
SlotDescription(default)The element your renderer draws the map in, and the map's markers, routes, areas, positions, and points layers.attributionThe map credit, which most tile licenses require.face-north-iconReplaces the compass needle. It inherits --map-needle-turn, so rotate: var(--map-needle-turn) keeps it pointing north.footerContent below the map, such as a legend or a scale.fullscreen-iconReplaces the glyph inside the fullscreen button.headerContent above the map, such as a title or a search field.layers-iconReplaces the glyph inside the layers button.pan-down-iconReplaces the glyph inside the pan down button.pan-end-iconReplaces the glyph inside the button that pans toward the end of a line of text.pan-start-iconReplaces the glyph inside the button that pans toward the start of a line of text.pan-up-iconReplaces the glyph inside the pan up button.rotate-left-iconReplaces the glyph inside the rotate left button.rotate-right-iconReplaces the glyph inside the rotate right button.tilt-iconReplaces the "3D" inside the 3D button.zoom-in-iconReplaces the glyph inside the zoom-in button.zoom-out-iconReplaces the glyph inside the zoom-out button.
EventTypeDescriptionchangeEventThe layers menu changed the map type, which map-type now holds.helix-activateHelixActivateEventA marker was pressed. The value is the marker's name, or its label if it has no name. A cluster sends helix-map-cluster instead.helix-before-changeHelixBeforeChangeEventA map type was chosen in the layers menu, with its name: standard, hybrid, or satellite. Cancelable: cancel it to keep the current type.helix-before-toggleHelixBeforeToggleEventA layer's tile in the layers menu was pressed. Sent from the layer, with checked true when it is to be shown. Cancelable: cancel it to keep the layer as it is.helix-map-clusterHelixMapClusterEventA cluster was pressed. Sent from the marker that shows the cluster, with the names of its places.helix-map-panHelixMapPanEventA pan button or arrow key was pressed. Move your map in response.helix-map-part-changeHelixMapPartChangeEventClustering was turned on or off. Used by connectMap; pages do not need to listen for it.helix-map-readyHelixMapReadyEventThe map has been drawn whole: its style, every tile the view needs, and the ground where it has terrain. Sent once per connection. Show a map that is finished on it, where it would otherwise draw in stages.helix-map-rotateHelixMapRotateEventA rotate or Face north button, or Shift with Left or Right, was pressed. Turn your map in response.helix-map-tiltHelixMapTiltEventThe 3D button, or Shift with Up or Down, was pressed. Tilt your map in response.helix-map-zoomHelixMapZoomEventA zoom button or key was pressed, with a direction. Zoom your map in response.helix-toggleHelixToggleEventA layer's tile in the layers menu showed or hid it. Sent from the layer once its hidden attribute holds the choice, with checked true when it is shown.
MethodTypeDescriptiondrawn(whole: unknown) => voidSays the map has been drawn whole, or with false, that it no longer is.faceNorth() => voidTurns the map to face north.moved() => voidSays the map has moved, where a reader asked it to.pan(to: ViewportWay) => voidPans the view one step in a direction.rotate(by: number) => voidTurns the map by some degrees, clockwise where positive.tilt(by: number) => voidTilts the map by some degrees, toward the horizon where positive.tiltTo(to: number) => voidTilts the map to some degrees from looking straight down. 0 makes it flat.toggleFullscreen() => voidTurns fullscreen on or off.zoom(by: number) => voidZooms the view one step: 1 zooms in and -1 zooms out.
PartDescriptionattributionThe strip under the map that holds the credit.compassThe compass and the pan and rotate buttons around it.controlsThe column of buttons that move the map, a toolbar and one tab stop.face-northThe compass: its needle points north as the map turns, and pressing it turns the map to face north.face-north-buttonface-north's inner button.face-north-liveface-north's live region, which speaks while it is pending.face-north-spinnerThe ring face-north turns while it is pending.face-north-textThe box face-north's glyph sits in.footerThe strip below the map.fullscreenThe button that makes the map fill the screen.fullscreen-buttonfullscreen's inner button.fullscreen-livefullscreen's live region, which speaks while it is pending.fullscreen-spinnerThe ring fullscreen turns while it is pending.fullscreen-textThe box fullscreen's glyph sits in.gesture-hintWords over the map for a moment when it lets a gesture pass to the page, such as how to zoom it.gesture-statusThe line shown while a map with gestures="activate" has the gestures.headerThe strip above the map.layerOne entry in the list of the map's layers.layer-choiceOne layer's tile in the layers menu, pressed while the layer is shown.layer-choicesThe layer tiles in the layers menu, under the map types.layer-iconThe picture on a layer's tile, drawn for its kind: a line for a route, a peak for terrain.layer-nameThe name on a layer's tile.layersThe list of the map's shown layers, such as routes, areas, and points, read by screen readers.layers-menuThe menu of the map's layers, which the layers button opens.layers-toggleThe button that opens and closes the layers menu.layers-toggle-buttonlayers-toggle's inner button.layers-toggle-livelayers-toggle's live region, which speaks while it is pending.layers-toggle-spinnerThe ring layers-toggle turns while it is pending.layers-toggle-textThe box layers-toggle's glyph sits in.liveWhat screen readers hear after the map moves: the zoom level, the way it faces, its tilt, or the way it moved. Visually hidden in the styled tier.map-typeOne map type's card in the layers menu: a radio button, its picture, and its name.map-type-nameThe name on a map type's card.map-type-previewThe picture of the map on a map type's card.map-typesThe map-type cards at the top of the layers menu, where the map has imagery.needleThe compass needle, turned to point north.pan-downThe button that pans the map down.pan-down-buttonpan-down's inner button.pan-down-livepan-down's live region, which speaks while it is pending.pan-down-spinnerThe ring pan-down turns while it is pending.pan-down-textThe box pan-down's glyph sits in.pan-endThe button that pans toward the end of a line of text: right in English.pan-end-buttonpan-end's inner button.pan-end-livepan-end's live region, which speaks while it is pending.pan-end-spinnerThe ring pan-end turns while it is pending.pan-end-textThe box pan-end's glyph sits in.pan-startThe button that pans toward the start of a line of text: left in English.pan-start-buttonpan-start's inner button.pan-start-livepan-start's live region, which speaks while it is pending.pan-start-spinnerThe ring pan-start turns while it is pending.pan-start-textThe box pan-start's glyph sits in.pan-upThe button that pans the map up.pan-up-buttonpan-up's inner button.pan-up-livepan-up's live region, which speaks while it is pending.pan-up-spinnerThe ring pan-up turns while it is pending.pan-up-textThe box pan-up's glyph sits in.regionThe named region the map sits in.rotate-leftThe button that turns the map counterclockwise.rotate-left-buttonrotate-left's inner button.rotate-left-liverotate-left's live region, which speaks while it is pending.rotate-left-spinnerThe ring rotate-left turns while it is pending.rotate-left-textThe box rotate-left's glyph sits in.rotate-rightThe button that turns the map clockwise.rotate-right-buttonrotate-right's inner button.rotate-right-liverotate-right's live region, which speaks while it is pending.rotate-right-spinnerThe ring rotate-right turns while it is pending.rotate-right-textThe box rotate-right's glyph sits in.tiltThe 3D button, which tilts the map and makes it flat again. Pressed while the map is tilted.tilt-buttontilt's inner button.tilt-livetilt's live region, which speaks while it is pending.tilt-spinnerThe ring tilt turns while it is pending.tilt-textThe box tilt's glyph sits in.viewportThe box the map is drawn in.zoom-inThe button that zooms in.zoom-in-buttonzoom-in's inner button.zoom-in-livezoom-in's live region, which speaks while it is pending.zoom-in-spinnerThe ring zoom-in turns while it is pending.zoom-in-textThe box zoom-in's glyph sits in.zoom-outThe button that zooms out.zoom-out-buttonzoom-out's inner button.zoom-out-livezoom-out's live region, which speaks while it is pending.zoom-out-spinnerThe ring zoom-out turns while it is pending.zoom-out-textThe box zoom-out's glyph sits in.
CSS PropertyDescription--map-attribution-border-colorThe rule above the map credit, under the map.--map-attribution-colorThe color of the map credit.--map-attribution-font-sizeThe size of the map credit's text.--map-background-colorThe color behind the map while tiles load.--map-block-sizeThe frame's height, as a length. Ignored with fill, where the container decides it.--map-border-colorThe frame's border color.--map-chosen-colorThe fill of the pressed 3D button and the ring around the chosen map type and each shown layer in the layers menu.--map-layers-menu-gapThe space between the map types and the layers in the layers menu.--map-layers-menu-inline-sizeThe width of the layers menu.--map-layers-menu-paddingThe space inside the edge of the layers menu.--map-needle-north-colorThe north half of the compass needle.--map-needle-south-colorThe south half of the compass needle.--map-needle-turnHow far the needle turns to point north, as an angle. The frame writes it from bearing.--map-radiusThe frame's corners.--viewport-control-background-colorThe background of the pan and zoom buttons. Canvas uses the same property.
Custom stateDescriptionfullscreenThe map fills the screen.idleThe user has been still long enough for the header and footer to fade.layers-openThe layers menu is open.readyThe map has been drawn whole, after helix-map-ready.rotatedThe map is turned away from north, by bearing.settledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.sharingThe page keeps the plain wheel and one finger, with gestures="cooperative" or while a map with gestures="activate" waits to be pressed.tiltedThe map is tilted by pitch, so it no longer looks straight down.usingA map with gestures="activate" has been pressed and has the gestures.
Areahelix-map-areaA shape on a map, such as a delivery zone.
PropTypeDescriptioncaptionstringWords drawn on the map with the area, such as A for a search sector.
Unset, nothing is drawn. Keep it short: it is a caption on a map, and the
area's label is what a screen reader hears.captionPlacement"inside"|"outside"Default"inside"Where the caption stands. inside, the default, at the point of the area
furthest from its edges. outside, just above the area's northernmost
point, clear of the shape, for an area whose caption would cover what is
in it.descriptionstringMore about the area. Read after its label in the frame's list.groupstringA name this layer shares with other layers, such as a route and its
dotted legs. The layers menu shows layers in the same group as one entry,
named by the first of them, and its checkbox shows or hides them all.labelstringDefault"Area"The area's name, used in the frame's list and its tile in the layers
menu. Defaults to "Area", so neither is ever a control with no name.pointsMapPoint[]The corners of the shape, in order. The last point connects back to the
first.tone"accent"|"danger"|"info"|"neutral"|"primary"|"success"|"warning"The area's color. Uses your primary color unless set.
ReadTypeDescriptionisMapLayerbooleanMarks this as a layer for the frame and the connector, whatever its tag.whenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
EventTypeDescriptionhelix-map-part-changeHelixMapPartChangeEventThe area's points, name, or color changed. Used by connectMap; pages do not need to listen for it.
CSS PropertyDescription--map-area-colorThe area's color when no tone is set.
Custom stateDescriptionsettledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Buildingshelix-map-buildingsThe buildings on a map, raised to their real heights in 3D.
PropTypeDescriptiondescriptionstringMore about the buildings. Read after the label in the frame's list.groupstringA name this layer shares with other layers, such as a route and its
dotted legs. The layers menu shows layers in the same group as one entry,
named by the first of them, and its checkbox shows or hides them all.labelstringDefault"3D buildings"The layer's name in the frame's list.tone"accent"|"danger"|"info"|"neutral"|"primary"|"success"|"warning"The buildings' color. Uses your raised surface color unless set.
ReadTypeDescriptionisMapLayerbooleanMarks this as a layer for the frame and the connector, whatever its tag.whenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
EventTypeDescriptionhelix-map-part-changeHelixMapPartChangeEventThe layer's name or color changed. Used by connectMap; pages do not need to listen for it.
CSS PropertyDescription--map-buildings-colorThe buildings' color when no tone is set.
Custom stateDescriptionsettledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Contourshelix-map-contoursContour lines on a map, each at one height, labeled at every fifth.
PropTypeDescriptionattributionstringThe elevation provider's credit, shown in the frame's footer. Links in it stay links.descriptionstringMore about the lines. Read after the label in the frame's list.encoding"mapbox"|"terrarium"Default"terrarium"How the tiles store heights in their colors: terrarium or mapbox.groupstringA name this layer shares with other layers, such as a route and its
dotted legs. The layers menu shows layers in the same group as one entry,
named by the first of them, and its checkbox shows or hides them all.labelstringDefault"Contour lines"The layer's name in the frame's list.maxZoomnumberThe deepest zoom the provider has tiles for.srcstringOne elevation tile URL with {z}, {x}, and {y} in it.unit"feet"|"meters"Default"meters"The unit the heights are labeled in: meters or feet.
ReadTypeDescriptionisMapLayerbooleanMarks this as a layer for the frame and the connector, whatever its tag.whenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
EventTypeDescriptionhelix-map-part-changeHelixMapPartChangeEventThe tiles, the unit, or the layer's name or color changed. Used by connectMap; pages do not need to listen for it.
Custom stateDescriptionsettledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Landcoverhelix-map-landcoverWhat covers the ground on a map: forest, grass, farmland, wetland, sand, rock, and ice.
PropTypeDescriptiondescriptionstringMore about the land cover. Read after the label in the frame's list.groupstringA name this layer shares with other layers, such as a route and its
dotted legs. The layers menu shows layers in the same group as one entry,
named by the first of them, and its checkbox shows or hides them all.labelstringDefault"Land cover"The layer's name in the frame's list.
ReadTypeDescriptionisMapLayerbooleanMarks this as a layer for the frame and the connector, whatever its tag.whenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
EventTypeDescriptionhelix-map-part-changeHelixMapPartChangeEventThe layer's name or color changed. Used by connectMap; pages do not need to listen for it.
CSS PropertyDescription--map-landcover-groundThe land color the covers are mixed into.
Custom stateDescriptionsettledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Markerhelix-map-markerA named place on a map.
PropTypeDescriptionlabelstringThe place's name. Shown next to the marker and read by screen readers.latnumberLatitude, in degrees. A marker without both lat and lng is not shown.lngnumberLongitude, in degrees.material"frosted"|"glass"|"transparent"The background of the name. Leave unset for solid. glass shows the map
through a blur, frosted blurs more, and transparent has no background.namestringDefault""The value helix-activate reports. Defaults to the label.passedbooleanDefaultfalseMarks the place as passed, such as a stop already visited. The marker is
drawn muted, and its name is followed by passed-label.passedLabelstringDefault"{label}, passed"What a passed place is called. {label} is its name.separation"elevated"|"filled"|"outlined"|"plain"How the point stands out from the map. Leave unset for a surface-colored
edge, a halo in the marker's color, and a small shadow. outlined has the
edge only, elevated a larger shadow, filled a wider, softer halo with
no edge, and plain no edge, halo, or shadow.shape"diamond"|"pin"|"ring"|"rounded"|"square"The point's shape. A circle unless set. Use shapes with tones to tell
kinds of places apart. pin places the tip of a pin on the location, for
a destination.tone"accent"|"danger"|"info"|"neutral"|"primary"|"success"|"warning"The point's color. Uses your primary color unless set.
ReadTypeDescriptionisMapMarkerbooleanMarks the element as a map marker. The frame and the connector find
markers among the frame's children by this flag, so they treat a styled
marker and a headless one the same way.whenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
SlotDescriptioniconA letter, number, or icon shown in the point, such as a stop's order. Screen readers read the marker's label only.
EventTypeDescriptionhelix-map-clusterHelixMapClusterEventThis marker shows a cluster and was pressed. connectMap zooms in to its places.helix-map-part-changeHelixMapPartChangeEventThe marker moved or was renamed. Used by connectMap; pages do not need to listen for it.
MethodTypeDescriptionextent() => numberHow far the marker reaches from its point along the line, name included,
in CSS pixels: the button's width, which is laid out even while its name is
faded, so the connector can ask before the name is ever shown.focus(options: FocusOptions) => voidFocuses the marker's button. The host draws no box of its own.
PartDescriptionlabelThe place's name, next to the point.markerThe button, holding the point and the name.pointThe dot on the place, holding the icon if there is one.
CSS PropertyDescription--map-marker-cluster-colorA cluster's fill color.--map-marker-cluster-sizeA cluster's width.--map-marker-colorThe point's color when no tone is set.--map-marker-inkThe color of the dot, letter, or icon in the point. Set it with --map-marker-color when white is hard to read on your color.--map-marker-label-border-widthThe width of the name's border.--map-marker-label-shadowThe name's shadow.--map-marker-sizeThe point's width.
Custom stateDescriptionbehindOn the far side of a globe, out of sight until the globe turns it into view.clusterShows several markers as one count.clusteredHidden inside another marker's cluster.currentHolds the map's tab stop.fannedSpread out from a location it shares with other markers, after their cluster was pressed.iconHas content in the icon slot.passedMarked as passed.placedPlaced on the map by the connector.settledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.startShows its name before the point, because there was no room after it.
Pointshelix-map-pointsThousands of places on a map, loaded from data.
PropTypeDescriptionclusterbooleanDefaultfalseCombines nearby points into counts. Pressing a count zooms in to it.countLabelstringDefault"{count, plural, one {# place} other {# places}}"The name read for a count. {count} is replaced by the number of places.
Defaults to "{count} places".dataMapPointsCollection|readonlyMapPointsPlace[]The points, as a GeoJSON collection or a list of { lat, lng, label, id }
places.descriptionstringMore about the points, such as how many there are. Read after the label in
the frame's list.groupstringA name this layer shares with other layers, such as a route and its
dotted legs. The layers menu shows layers in the same group as one entry,
named by the first of them, and its checkbox shows or hides them all.labelstringDefault"Places"The layer's name, used in the frame's list, its tile in the layers menu,
and the group of places the keyboard walks. Defaults to "Places".nameKeystringDefault"name"The GeoJSON property each point is named by. Defaults to name.srcstringA GeoJSON file of points to load. Ignored when data is set.tone"accent"|"danger"|"info"|"neutral"|"primary"|"success"|"warning"The points' color. Uses your primary color unless set.
ReadTypeDescriptionisMapLayerbooleanMarks this as a layer for the frame and the connector, whatever its tag.whenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
EventTypeDescriptionhelix-activateHelixActivateEventA point in view was pressed. The value is its id, or its name if it has no id.helix-map-clusterHelixMapClusterEventA count in view was pressed from the keyboard. connectMap zooms in to it.helix-map-part-changeHelixMapPartChangeEventThe points, name, or color changed. Used by connectMap; pages do not need to listen for it.
PartDescriptioncountThe button on a count, which is also a place.labelThe name of the focused point or count.placeThe button on a point or count in view.placesThe group of buttons, named by the layer's label.
CSS PropertyDescription--map-points-casing-colorThe edge around each point and count.--map-points-colorThe points' color when no tone is set.--map-points-inkThe color of the numbers in counts.
Custom stateDescriptionsettledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Positionhelix-map-positionA moving point on a map, such as a vehicle or a person.
PropTypeDescriptionaccuracynumberHow accurate the position is, in meters. Drawn as a ring with this radius.announceEverynumberDefault5000The least time between announcements, in milliseconds. A change during the
wait is announced when the wait ends. The attribute also takes a CSS time,
such as 5s.descriptionstringWhat screen readers announce when it changes, such as "Two stops away".headingnumberThe direction it faces, in degrees clockwise from north. Shows an arrow.labelstringDefault"Live position"What it is, such as "Van 12". Read by screen readers. Defaults to "Live position".latnumberLatitude, in degrees.lngnumberLongitude, in degrees.separation"elevated"|"filled"|"outlined"|"plain"How the point stands out from the map. Leave unset for an edge, a halo,
and a small shadow. outlined has the edge only, elevated a larger
shadow, filled the halo without an edge, and plain none of these.shape"diamond"|"ring"|"rounded"|"square"The point's shape. A circle unless set. A position with a heading is
always an arrow.tone"accent"|"danger"|"info"|"neutral"|"primary"|"success"|"warning"The position's color. Uses your theme's foreground color unless set.
ReadTypeDescriptionisMapPositionbooleanMarks this as a position for the connector, whatever its tag.whenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
EventTypeDescriptionhelix-map-part-changeHelixMapPartChangeEventIt moved, turned, or its accuracy changed. Used by connectMap; pages do not need to listen for it.
PartDescriptionaccuracyThe ring that shows how accurate the position is.arrowThe arrow shown when the position has a heading.dotThe point shown when the position has no heading.headingThe cone that shows its direction.positionThe image of the position, named by its label.pulseA ring that spreads out from the point, showing that the position is live.statusThe description, announced when it changes.
CSS PropertyDescription--map-position-colorThe color of the halo, direction cone, and pulse when no tone is set.--map-position-edgeThe edge around the point and the arrow.--map-position-fillThe color of the point and the arrow when no tone is set.--map-position-sizeThe point's width.
Custom stateDescriptionplacedPlaced on the map by the connector.settledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Rasterhelix-map-rasterMap tiles laid over a map, such as weather radar.
PropTypeDescriptionattributionstringThe tile provider's credit, shown in the frame's footer. Links in it stay links.descriptionstringMore about the layer. Read after the label in the frame's list.framenumberWhich of frames shows, counting from 0. Starts at the last frame.framesstring[]Tile URLs to show in order, one per frame, as a list separated by spaces.groundbooleanDefaultfalseDraws the tiles as the ground, under the map's roads and place names, for
imagery such as satellite photographs.groupstringA name this layer shares with other layers, such as a route and its
dotted legs. The layers menu shows layers in the same group as one entry,
named by the first of them, and its checkbox shows or hides them all.intervalnumberDefault600How long each frame shows while playing, in milliseconds. The attribute
also takes a CSS time, such as 0.6s.labelstringDefault"Overlay"The layer's name in the frame's list and its tile in the layers menu.
Defaults to "Overlay", so neither is ever a control with no name.maxZoomnumberThe deepest zoom the provider has tiles for. The map enlarges those tiles
at deeper zooms, where it would otherwise ask for tiles that do not exist.opacitynumberDefault0.7How opaque the tiles are, from 0 to 1.playingbooleanDefaultfalseWhether the frames play in order. Has no effect with one frame, or under reduced motion.srcstringOne tile URL with {z}, {x}, and {y} in it, for a layer of one frame.
ReadTypeDescriptionisMapLayerbooleanMarks this as a layer for the frame and the connector, whatever its tag.whenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
EventTypeDescriptionhelix-map-part-changeHelixMapPartChangeEventThe tiles, the frame shown, the opacity, or where the tiles are drawn changed. Used by connectMap; pages do not need to listen for it.
Custom stateDescriptionsettledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Routehelix-map-routeA line on a map, such as a route between stops.
PropTypeDescriptiondescriptionstringMore about the route, such as its distance or time. Read after its label
in the frame's list.groupstringA name this layer shares with other layers, such as a route and its
dotted legs. The layers menu shows layers in the same group as one entry,
named by the first of them, and its checkbox shows or hides them all.labelstringDefault"Route"The route's name, used in the frame's list and its tile in the layers
menu. Defaults to "Route", so neither is ever a control with no name.pointsMapPoint[]The points the line passes through, in order. Write the attribute as
lat,lng pairs separated by spaces, or set the property to an array of { lat, lng }.progressnumberHow much of the route has been traveled, from 0 to 1. The traveled part is
drawn in a lighter color.tone"accent"|"danger"|"info"|"neutral"|"primary"|"success"|"warning"The route's color. Uses your primary color unless set.variant"dotted"dotted draws the route as dots, for a walk off the road network.
ReadTypeDescriptionisMapLayerbooleanMarks this as a layer for the frame and the connector, whatever its tag.whenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
EventTypeDescriptionhelix-map-part-changeHelixMapPartChangeEventThe route's points, progress, name, or color changed. Used by connectMap; pages do not need to listen for it.
CSS PropertyDescription--map-route-casing-colorThe color of the casing under the route.--map-route-colorThe route's color when no tone is set.
Custom stateDescriptionsettledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Terrainhelix-map-terrainHills and mountains on a map, shaded and raised in 3D.
PropTypeDescriptionattributionstringThe elevation provider's credit, shown in the frame's footer. Links in it stay links.descriptionstringMore about the terrain. Read after the label in the frame's list.encoding"mapbox"|"terrarium"Default"terrarium"How the tiles store heights in their colors: terrarium or mapbox.exaggerationnumberDefault1How many times its real height the ground is raised, where raised is set.groupstringA name this layer shares with other layers, such as a route and its
dotted legs. The layers menu shows layers in the same group as one entry,
named by the first of them, and its checkbox shows or hides them all.labelstringDefault"Terrain"The layer's name in the frame's list.maxZoomnumberThe deepest zoom the provider has tiles for. The map enlarges those tiles
at deeper zooms, where it would otherwise ask for tiles that do not exist.raisedbooleanDefaultfalseRaises the ground to its real height in 3D. Tilt the map to see it.srcstringOne elevation tile URL with {z}, {x}, and {y} in it.
ReadTypeDescriptionisMapLayerbooleanMarks this as a layer for the frame and the connector, whatever its tag.whenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
EventTypeDescriptionhelix-map-part-changeHelixMapPartChangeEventThe tiles, how the ground is raised, or the layer's name or colors changed. Used by connectMap; pages do not need to listen for it.
CSS PropertyDescription--map-terrain-highlight-colorThe color of slopes that face the light.--map-terrain-shadow-colorThe color of slopes that face away from the light.
Custom stateDescriptionsettledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Roothelix-headless-mapA frame around a map drawn by another library.
PropTypeDescriptionactivateHintLabelstringDefault"Press the map to use it"The hint shown when the map, waiting to be pressed with
gestures="activate", is scrolled or swiped over.bearingnumberDefault0The map's rotation, in degrees clockwise from north. connectMap keeps it
current, and the Face north button's needle turns with it.clusterbooleanDefaultfalseCombines markers that would overlap into one count. Counts split apart as
the map zooms in, and pressing one zooms in to its places.controlsstringWhich controls to show, as a list such as pan zoom fullscreen, or
none. A family can add words of its own.controlsLabelstringDefault"Map controls"The name of the group of controls, read by screen readers, which names
what the controls drive rather than the mechanism.controlsPlacement"top-start"|"top-end"|"bottom-start"|"bottom-end"Which corner the controls sit in.faceNorthLabelstringDefault"Face north"The Face north button's label.fallbackLabelstringDefault"Map"The map's name where label is empty and the host has no aria-label.flatLabelstringDefault"Looking straight down"What screen readers hear when the map is tilted back to looking straight down.fullscreenLabelstringDefault"Fill the screen"The fullscreen button's label.gestures"activate"|"always"|"cooperative"Which gestures the surface takes from the page.hybridLabelstringDefault"Hybrid"The Hybrid map type's name.idleDelaynumberDefault0How long, in milliseconds, before the header and footer hide when the
user is inactive. 0 keeps them visible. The attribute also takes a CSS
time, such as 3s.labelstringDefault""The map's name, read by screen readers. Name the place, such as "Delivery
area", so that several maps on one page can be told apart. Required.layersLabelstringDefault"Map layers"The name of the layers button and menu, and of the list of the map's
layers, such as routes, areas, and points, read by screen readers.mapType"hybrid"|"satellite"How the map draws the ground, where it has imagery: hybrid for imagery
under the roads and names, and satellite for imagery alone. Absent is
the standard, themed map. The layers menu chooses it.mapTypeLabelstringDefault"Map type"The name of the map types in the layers menu, read by screen readers.movedDownLabelstringDefault"Moved down"What screen readers hear when the map has moved down.movedLeftLabelstringDefault"Moved left"What screen readers hear when the map has moved left.movedRightLabelstringDefault"Moved right"What screen readers hear when the map has moved right.movedUpLabelstringDefault"Moved up"What screen readers hear when the map has moved up.northLabelstringDefault"Facing north"What screen readers hear when the map is turned back to face north.panDownLabelstringDefault"Pan down"The pan down button's label.panLeftLabelstringDefault"Pan left"The pan left button's label.panRightLabelstringDefault"Pan right"The pan right button's label.panStepnumberDefault0.25How far one press pans the view, as a fraction of its size.panUpLabelstringDefault"Pan up"The pan up button's label.pitchnumberDefault0How far the map is tilted, in degrees from looking straight down.
connectMap keeps it current, and the 3D button is pressed while it is
above 0.roleLabelstringDefault"map"What a screen reader calls the map in place of its role, after its
name: "Edinburgh, map". Said only where the map has a name of its
own, since the fallback name is the same word. Empty leaves the role.rotateLeftLabelstringDefault"Rotate left"The rotate left button's label.rotateRightLabelstringDefault"Rotate right"The rotate right button's label.satelliteLabelstringDefault"Satellite"The Satellite map type's name.standardLabelstringDefault"Standard"The Standard map type's name.tiltedLabelstringDefault"{degrees, plural, one {Tilted # degree} other {Tilted # degrees}}"What screen readers hear when the map is tilted. {degrees} is the tilt
from looking straight down, written in the locale, and each language
writes the forms it has.tiltLabelstringDefault"Show in 3D"The 3D button's label.turnedLabelstringDefault"{degrees, plural, one {Facing # degree} other {Facing # degrees}}"What screen readers hear when the map is turned. {degrees} is the way the
top of the map faces, clockwise from north, written in the locale, and
each language writes the forms it has.twoFingerHintLabelstringDefault"Use two fingers to move the map"The hint shown when one finger swipes over the map with gestures="cooperative".usingLabelstringDefault"Using the map. Press Escape to scroll the page again."The line shown while the map, with gestures="activate", has the gestures.wheelHintLabelstringDefault"Use {key} and scroll to zoom the map"The hint shown when the wheel scrolls past the map with
gestures="cooperative". {key} is ⌘ on a Mac and Ctrl elsewhere.zoomedLabelstringDefault"Zoom level {level}"What screen readers hear after a zoom. {level} is the zoom level,
written in the locale.zoomInLabelstringDefault"Zoom in"The zoom in button's label.zoomLevelnumberHow far the map is zoomed, in its renderer's levels. connectMap keeps it
current, and the map says it after a zoom.zoomOutLabelstringDefault"Zoom out"The zoom out button's label.
ReadTypeDescriptionreadybooleanWhether the map has been drawn whole, which drawn() says. For a page that
connects after helix-map-ready has been sent, and missed it.whenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
SlotDescription(default)The element your renderer draws the map in, and the map's markers, routes, areas, positions, and points layers.attributionThe map credit, which most tile licenses require.face-north-iconReplaces the compass needle. It inherits --map-needle-turn, so rotate: var(--map-needle-turn) keeps it pointing north.footerContent below the map, such as a legend or a scale.fullscreen-iconReplaces the glyph inside the fullscreen button.headerContent above the map, such as a title or a search field.layers-iconReplaces the glyph inside the layers button.pan-down-iconReplaces the glyph inside the pan down button.pan-end-iconReplaces the glyph inside the button that pans toward the end of a line of text.pan-start-iconReplaces the glyph inside the button that pans toward the start of a line of text.pan-up-iconReplaces the glyph inside the pan up button.rotate-left-iconReplaces the glyph inside the rotate left button.rotate-right-iconReplaces the glyph inside the rotate right button.tilt-iconReplaces the "3D" inside the 3D button.zoom-in-iconReplaces the glyph inside the zoom-in button.zoom-out-iconReplaces the glyph inside the zoom-out button.
EventTypeDescriptionchangeEventThe layers menu changed the map type, which map-type now holds.helix-activateHelixActivateEventA marker was pressed. The value is the marker's name, or its label if it has no name. A cluster sends helix-map-cluster instead.helix-before-changeHelixBeforeChangeEventA map type was chosen in the layers menu, with its name: standard, hybrid, or satellite. Cancelable: cancel it to keep the current type.helix-before-toggleHelixBeforeToggleEventA layer's tile in the layers menu was pressed. Sent from the layer, with checked true when it is to be shown. Cancelable: cancel it to keep the layer as it is.helix-map-clusterHelixMapClusterEventA cluster was pressed. Sent from the marker that shows the cluster, with the names of its places.helix-map-panHelixMapPanEventA pan button or arrow key was pressed. Move your map in response.helix-map-part-changeHelixMapPartChangeEventClustering was turned on or off. Used by connectMap; pages do not need to listen for it.helix-map-readyHelixMapReadyEventThe map has been drawn whole: its style, every tile the view needs, and the ground where it has terrain. Sent once per connection. Show a map that is finished on it, where it would otherwise draw in stages.helix-map-rotateHelixMapRotateEventA rotate or Face north button, or Shift with Left or Right, was pressed. Turn your map in response.helix-map-tiltHelixMapTiltEventThe 3D button, or Shift with Up or Down, was pressed. Tilt your map in response.helix-map-zoomHelixMapZoomEventA zoom button or key was pressed, with a direction. Zoom your map in response.helix-toggleHelixToggleEventA layer's tile in the layers menu showed or hid it. Sent from the layer once its hidden attribute holds the choice, with checked true when it is shown.
MethodTypeDescriptiondrawn(whole: unknown) => voidSays the map has been drawn whole, or with false, that it no longer is.faceNorth() => voidTurns the map to face north.moved() => voidSays the map has moved, where a reader asked it to.pan(to: ViewportWay) => voidPans the view one step in a direction.rotate(by: number) => voidTurns the map by some degrees, clockwise where positive.tilt(by: number) => voidTilts the map by some degrees, toward the horizon where positive.tiltTo(to: number) => voidTilts the map to some degrees from looking straight down. 0 makes it flat.toggleFullscreen() => voidTurns fullscreen on or off.zoom(by: number) => voidZooms the view one step: 1 zooms in and -1 zooms out.
PartDescriptionattributionThe strip under the map that holds the credit.compassThe compass and the pan and rotate buttons around it.controlsThe column of buttons that move the map, a toolbar and one tab stop.face-northThe compass: its needle points north as the map turns, and pressing it turns the map to face north.face-north-buttonface-north's inner button.face-north-liveface-north's live region, which speaks while it is pending.face-north-spinnerThe ring face-north turns while it is pending.face-north-textThe box face-north's glyph sits in.footerThe strip below the map.fullscreenThe button that makes the map fill the screen.fullscreen-buttonfullscreen's inner button.fullscreen-livefullscreen's live region, which speaks while it is pending.fullscreen-spinnerThe ring fullscreen turns while it is pending.fullscreen-textThe box fullscreen's glyph sits in.gesture-hintWords over the map for a moment when it lets a gesture pass to the page, such as how to zoom it.gesture-statusThe line shown while a map with gestures="activate" has the gestures.headerThe strip above the map.layerOne entry in the list of the map's layers.layer-choiceOne layer's tile in the layers menu, pressed while the layer is shown.layer-choicesThe layer tiles in the layers menu, under the map types.layer-iconThe picture on a layer's tile, drawn for its kind: a line for a route, a peak for terrain.layer-nameThe name on a layer's tile.layersThe list of the map's shown layers, such as routes, areas, and points, read by screen readers.layers-menuThe menu of the map's layers, which the layers button opens.layers-toggleThe button that opens and closes the layers menu.layers-toggle-buttonlayers-toggle's inner button.layers-toggle-livelayers-toggle's live region, which speaks while it is pending.layers-toggle-spinnerThe ring layers-toggle turns while it is pending.layers-toggle-textThe box layers-toggle's glyph sits in.liveWhat screen readers hear after the map moves: the zoom level, the way it faces, its tilt, or the way it moved. Visually hidden in the styled tier.map-typeOne map type's card in the layers menu: a radio button, its picture, and its name.map-type-nameThe name on a map type's card.map-type-previewThe picture of the map on a map type's card.map-typesThe map-type cards at the top of the layers menu, where the map has imagery.needleThe compass needle, turned to point north.pan-downThe button that pans the map down.pan-down-buttonpan-down's inner button.pan-down-livepan-down's live region, which speaks while it is pending.pan-down-spinnerThe ring pan-down turns while it is pending.pan-down-textThe box pan-down's glyph sits in.pan-endThe button that pans toward the end of a line of text: right in English.pan-end-buttonpan-end's inner button.pan-end-livepan-end's live region, which speaks while it is pending.pan-end-spinnerThe ring pan-end turns while it is pending.pan-end-textThe box pan-end's glyph sits in.pan-startThe button that pans toward the start of a line of text: left in English.pan-start-buttonpan-start's inner button.pan-start-livepan-start's live region, which speaks while it is pending.pan-start-spinnerThe ring pan-start turns while it is pending.pan-start-textThe box pan-start's glyph sits in.pan-upThe button that pans the map up.pan-up-buttonpan-up's inner button.pan-up-livepan-up's live region, which speaks while it is pending.pan-up-spinnerThe ring pan-up turns while it is pending.pan-up-textThe box pan-up's glyph sits in.regionThe named region the map sits in.rotate-leftThe button that turns the map counterclockwise.rotate-left-buttonrotate-left's inner button.rotate-left-liverotate-left's live region, which speaks while it is pending.rotate-left-spinnerThe ring rotate-left turns while it is pending.rotate-left-textThe box rotate-left's glyph sits in.rotate-rightThe button that turns the map clockwise.rotate-right-buttonrotate-right's inner button.rotate-right-liverotate-right's live region, which speaks while it is pending.rotate-right-spinnerThe ring rotate-right turns while it is pending.rotate-right-textThe box rotate-right's glyph sits in.tiltThe 3D button, which tilts the map and makes it flat again. Pressed while the map is tilted.tilt-buttontilt's inner button.tilt-livetilt's live region, which speaks while it is pending.tilt-spinnerThe ring tilt turns while it is pending.tilt-textThe box tilt's glyph sits in.viewportThe box the map is drawn in.zoom-inThe button that zooms in.zoom-in-buttonzoom-in's inner button.zoom-in-livezoom-in's live region, which speaks while it is pending.zoom-in-spinnerThe ring zoom-in turns while it is pending.zoom-in-textThe box zoom-in's glyph sits in.zoom-outThe button that zooms out.zoom-out-buttonzoom-out's inner button.zoom-out-livezoom-out's live region, which speaks while it is pending.zoom-out-spinnerThe ring zoom-out turns while it is pending.zoom-out-textThe box zoom-out's glyph sits in.
CSS PropertyDescription--map-needle-turnHow far the needle turns to point north, as an angle. The frame writes it from bearing.
Custom stateDescriptionfullscreenThe map fills the screen.idleThe user has been still long enough for the header and footer to fade.layers-openThe layers menu is open.readyThe map has been drawn whole, after helix-map-ready.rotatedThe map is turned away from north, by bearing.settledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.sharingThe page keeps the plain wheel and one finger, with gestures="cooperative" or while a map with gestures="activate" waits to be pressed.tiltedThe map is tilted by pitch, so it no longer looks straight down.usingA map with gestures="activate" has been pressed and has the gestures.
Areahelix-headless-map-areaA shape on a map, such as a delivery zone.
PropTypeDescriptioncaptionstringWords drawn on the map with the area, such as A for a search sector.
Unset, nothing is drawn. Keep it short: it is a caption on a map, and the
area's label is what a screen reader hears.captionPlacement"inside"|"outside"Default"inside"Where the caption stands. inside, the default, at the point of the area
furthest from its edges. outside, just above the area's northernmost
point, clear of the shape, for an area whose caption would cover what is
in it.descriptionstringMore about the area. Read after its label in the frame's list.groupstringA name this layer shares with other layers, such as a route and its
dotted legs. The layers menu shows layers in the same group as one entry,
named by the first of them, and its checkbox shows or hides them all.labelstringDefault"Area"The area's name, used in the frame's list and its tile in the layers
menu. Defaults to "Area", so neither is ever a control with no name.pointsMapPoint[]The corners of the shape, in order. The last point connects back to the
first.
ReadTypeDescriptionisMapLayerbooleanMarks this as a layer for the frame and the connector, whatever its tag.whenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
EventTypeDescriptionhelix-map-part-changeHelixMapPartChangeEventThe area's points, name, or color changed. Used by connectMap; pages do not need to listen for it.
Custom stateDescriptionsettledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Buildingshelix-headless-map-buildingsThe buildings on a map, raised to their real heights in 3D.
PropTypeDescriptiondescriptionstringMore about the buildings. Read after the label in the frame's list.groupstringA name this layer shares with other layers, such as a route and its
dotted legs. The layers menu shows layers in the same group as one entry,
named by the first of them, and its checkbox shows or hides them all.labelstringDefault"3D buildings"The layer's name in the frame's list.
ReadTypeDescriptionisMapLayerbooleanMarks this as a layer for the frame and the connector, whatever its tag.whenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
EventTypeDescriptionhelix-map-part-changeHelixMapPartChangeEventThe layer's name or color changed. Used by connectMap; pages do not need to listen for it.
Custom stateDescriptionsettledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Contourshelix-headless-map-contoursContour lines on a map, each at one height, labeled at every fifth.
PropTypeDescriptionattributionstringThe elevation provider's credit, shown in the frame's footer. Links in it stay links.descriptionstringMore about the lines. Read after the label in the frame's list.encoding"mapbox"|"terrarium"Default"terrarium"How the tiles store heights in their colors: terrarium or mapbox.groupstringA name this layer shares with other layers, such as a route and its
dotted legs. The layers menu shows layers in the same group as one entry,
named by the first of them, and its checkbox shows or hides them all.labelstringDefault"Contour lines"The layer's name in the frame's list.maxZoomnumberThe deepest zoom the provider has tiles for.srcstringOne elevation tile URL with {z}, {x}, and {y} in it.unit"feet"|"meters"Default"meters"The unit the heights are labeled in: meters or feet.
ReadTypeDescriptionisMapLayerbooleanMarks this as a layer for the frame and the connector, whatever its tag.whenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
EventTypeDescriptionhelix-map-part-changeHelixMapPartChangeEventThe tiles, the unit, or the layer's name or color changed. Used by connectMap; pages do not need to listen for it.
Custom stateDescriptionsettledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Landcoverhelix-headless-map-landcoverWhat covers the ground on a map: forest, grass, farmland, wetland, sand, rock, and ice.
PropTypeDescriptiondescriptionstringMore about the land cover. Read after the label in the frame's list.groupstringA name this layer shares with other layers, such as a route and its
dotted legs. The layers menu shows layers in the same group as one entry,
named by the first of them, and its checkbox shows or hides them all.labelstringDefault"Land cover"The layer's name in the frame's list.
ReadTypeDescriptionisMapLayerbooleanMarks this as a layer for the frame and the connector, whatever its tag.whenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
EventTypeDescriptionhelix-map-part-changeHelixMapPartChangeEventThe layer's name or color changed. Used by connectMap; pages do not need to listen for it.
Custom stateDescriptionsettledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Markerhelix-headless-map-markerA named place on a map.
PropTypeDescriptionlabelstringThe place's name. Shown next to the marker and read by screen readers.latnumberLatitude, in degrees. A marker without both lat and lng is not shown.lngnumberLongitude, in degrees.namestringDefault""The value helix-activate reports. Defaults to the label.passedbooleanDefaultfalseMarks the place as passed, such as a stop already visited. The marker is
drawn muted, and its name is followed by passed-label.passedLabelstringDefault"{label}, passed"What a passed place is called. {label} is its name.
ReadTypeDescriptionisMapMarkerbooleanMarks the element as a map marker. The frame and the connector find
markers among the frame's children by this flag, so they treat a styled
marker and a headless one the same way.whenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
SlotDescriptioniconA letter, number, or icon shown in the point, such as a stop's order. Screen readers read the marker's label only.
EventTypeDescriptionhelix-map-clusterHelixMapClusterEventThis marker shows a cluster and was pressed. connectMap zooms in to its places.helix-map-part-changeHelixMapPartChangeEventThe marker moved or was renamed. Used by connectMap; pages do not need to listen for it.
MethodTypeDescriptionextent() => numberHow far the marker reaches from its point along the line, name included,
in CSS pixels: the button's width, which is laid out even while its name is
faded, so the connector can ask before the name is ever shown.focus(options: FocusOptions) => voidFocuses the marker's button. The host draws no box of its own.
PartDescriptionlabelThe place's name, next to the point.markerThe button, holding the point and the name.pointThe dot on the place, holding the icon if there is one.
Custom stateDescriptionbehindOn the far side of a globe, out of sight until the globe turns it into view.clusterShows several markers as one count.clusteredHidden inside another marker's cluster.currentHolds the map's tab stop.fannedSpread out from a location it shares with other markers, after their cluster was pressed.iconHas content in the icon slot.passedMarked as passed.placedPlaced on the map by the connector.settledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.startShows its name before the point, because there was no room after it.
Pointshelix-headless-map-pointsThousands of places on a map, loaded from data.
PropTypeDescriptionclusterbooleanDefaultfalseCombines nearby points into counts. Pressing a count zooms in to it.countLabelstringDefault"{count, plural, one {# place} other {# places}}"The name read for a count. {count} is replaced by the number of places.
Defaults to "{count} places".dataMapPointsCollection|readonlyMapPointsPlace[]The points, as a GeoJSON collection or a list of { lat, lng, label, id }
places.descriptionstringMore about the points, such as how many there are. Read after the label in
the frame's list.groupstringA name this layer shares with other layers, such as a route and its
dotted legs. The layers menu shows layers in the same group as one entry,
named by the first of them, and its checkbox shows or hides them all.labelstringDefault"Places"The layer's name, used in the frame's list, its tile in the layers menu,
and the group of places the keyboard walks. Defaults to "Places".nameKeystringDefault"name"The GeoJSON property each point is named by. Defaults to name.srcstringA GeoJSON file of points to load. Ignored when data is set.
ReadTypeDescriptionisMapLayerbooleanMarks this as a layer for the frame and the connector, whatever its tag.whenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
EventTypeDescriptionhelix-activateHelixActivateEventA point in view was pressed. The value is its id, or its name if it has no id.helix-map-clusterHelixMapClusterEventA count in view was pressed from the keyboard. connectMap zooms in to it.helix-map-part-changeHelixMapPartChangeEventThe points, name, or color changed. Used by connectMap; pages do not need to listen for it.
PartDescriptioncountThe button on a count, which is also a place.labelThe name of the focused point or count.placeThe button on a point or count in view.placesThe group of buttons, named by the layer's label.
Custom stateDescriptionsettledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Positionhelix-headless-map-positionA moving point on a map, such as a vehicle or a person.
PropTypeDescriptionaccuracynumberHow accurate the position is, in meters. Drawn as a ring with this radius.announceEverynumberDefault5000The least time between announcements, in milliseconds. A change during the
wait is announced when the wait ends. The attribute also takes a CSS time,
such as 5s.descriptionstringWhat screen readers announce when it changes, such as "Two stops away".headingnumberThe direction it faces, in degrees clockwise from north. Shows an arrow.labelstringDefault"Live position"What it is, such as "Van 12". Read by screen readers. Defaults to "Live position".latnumberLatitude, in degrees.lngnumberLongitude, in degrees.
ReadTypeDescriptionisMapPositionbooleanMarks this as a position for the connector, whatever its tag.whenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
EventTypeDescriptionhelix-map-part-changeHelixMapPartChangeEventIt moved, turned, or its accuracy changed. Used by connectMap; pages do not need to listen for it.
PartDescriptionaccuracyThe ring that shows how accurate the position is.arrowThe arrow shown when the position has a heading.dotThe point shown when the position has no heading.headingThe cone that shows its direction.positionThe image of the position, named by its label.pulseA ring that spreads out from the point, showing that the position is live.statusThe description, announced when it changes.
Custom stateDescriptionplacedPlaced on the map by the connector.settledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Rasterhelix-headless-map-rasterMap tiles laid over a map, such as weather radar.
PropTypeDescriptionattributionstringThe tile provider's credit, shown in the frame's footer. Links in it stay links.descriptionstringMore about the layer. Read after the label in the frame's list.framenumberWhich of frames shows, counting from 0. Starts at the last frame.framesstring[]Tile URLs to show in order, one per frame, as a list separated by spaces.groundbooleanDefaultfalseDraws the tiles as the ground, under the map's roads and place names, for
imagery such as satellite photographs.groupstringA name this layer shares with other layers, such as a route and its
dotted legs. The layers menu shows layers in the same group as one entry,
named by the first of them, and its checkbox shows or hides them all.intervalnumberDefault600How long each frame shows while playing, in milliseconds. The attribute
also takes a CSS time, such as 0.6s.labelstringDefault"Overlay"The layer's name in the frame's list and its tile in the layers menu.
Defaults to "Overlay", so neither is ever a control with no name.maxZoomnumberThe deepest zoom the provider has tiles for. The map enlarges those tiles
at deeper zooms, where it would otherwise ask for tiles that do not exist.opacitynumberDefault0.7How opaque the tiles are, from 0 to 1.playingbooleanDefaultfalseWhether the frames play in order. Has no effect with one frame, or under reduced motion.srcstringOne tile URL with {z}, {x}, and {y} in it, for a layer of one frame.
ReadTypeDescriptionisMapLayerbooleanMarks this as a layer for the frame and the connector, whatever its tag.whenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
EventTypeDescriptionhelix-map-part-changeHelixMapPartChangeEventThe tiles, the frame shown, the opacity, or where the tiles are drawn changed. Used by connectMap; pages do not need to listen for it.
Custom stateDescriptionsettledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Routehelix-headless-map-routeA line on a map, such as a route between stops.
PropTypeDescriptiondescriptionstringMore about the route, such as its distance or time. Read after its label
in the frame's list.groupstringA name this layer shares with other layers, such as a route and its
dotted legs. The layers menu shows layers in the same group as one entry,
named by the first of them, and its checkbox shows or hides them all.labelstringDefault"Route"The route's name, used in the frame's list and its tile in the layers
menu. Defaults to "Route", so neither is ever a control with no name.pointsMapPoint[]The points the line passes through, in order. Write the attribute as
lat,lng pairs separated by spaces, or set the property to an array of { lat, lng }.progressnumberHow much of the route has been traveled, from 0 to 1. The traveled part is
drawn in a lighter color.
ReadTypeDescriptionisMapLayerbooleanMarks this as a layer for the frame and the connector, whatever its tag.whenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
EventTypeDescriptionhelix-map-part-changeHelixMapPartChangeEventThe route's points, progress, name, or color changed. Used by connectMap; pages do not need to listen for it.
Custom stateDescriptionsettledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Terrainhelix-headless-map-terrainHills and mountains on a map, shaded and raised in 3D.
PropTypeDescriptionattributionstringThe elevation provider's credit, shown in the frame's footer. Links in it stay links.descriptionstringMore about the terrain. Read after the label in the frame's list.encoding"mapbox"|"terrarium"Default"terrarium"How the tiles store heights in their colors: terrarium or mapbox.exaggerationnumberDefault1How many times its real height the ground is raised, where raised is set.groupstringA name this layer shares with other layers, such as a route and its
dotted legs. The layers menu shows layers in the same group as one entry,
named by the first of them, and its checkbox shows or hides them all.labelstringDefault"Terrain"The layer's name in the frame's list.maxZoomnumberThe deepest zoom the provider has tiles for. The map enlarges those tiles
at deeper zooms, where it would otherwise ask for tiles that do not exist.raisedbooleanDefaultfalseRaises the ground to its real height in 3D. Tilt the map to see it.srcstringOne elevation tile URL with {z}, {x}, and {y} in it.
ReadTypeDescriptionisMapLayerbooleanMarks this as a layer for the frame and the connector, whatever its tag.whenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
EventTypeDescriptionhelix-map-part-changeHelixMapPartChangeEventThe tiles, how the ground is raised, or the layer's name or colors changed. Used by connectMap; pages do not need to listen for it.
Custom stateDescriptionsettledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Examples
NameDescriptionAreasSearch sectors, each named on the map by its caption: two inside their sector and one above it, clear of what it holds.Behind ContentA map behind a page's own words, filling a hero whose words decide its height, with its credit in a corner, no landmarks, and the page's scroll left to the page.BuildingsBuildings raised to their real heights on a tilted map of downtown Austin.ClustersMarkers that would overlap combine into counts, and two places at one address spread out when you press their count.Controls And PlacementPan and fullscreen buttons in the bottom corner, for a map library that draws its own zoom buttons.EventsMoving your own map in response to helix-map-pan and helix-map-zoom.FramedThe frame with its pan and zoom buttons and the map credit.GlobeOffices around the world on a globe, where the places on its far side are hidden until it turns them into view.PointsThousands of places as one clustered layer, set from a script.PreviewA frame around a map, with pan and zoom buttons and the map credit.PreviewA frame around a map, with pan and zoom buttons and the map credit.Route With StopsLettered stops, a route, and a live position, with the stops already passed drawn muted.SatelliteDowntown Austin in the Hybrid map type, aerial photographs under the roads and names, with Standard and Satellite in the layers menu.TerrainYosemite Valley raised in 3D, shaded by its slopes, colored by its land cover, and drawn in contour lines, with the Hybrid and Satellite map types in the layers menu.WeatherWeather radar over Texas for the last 50 minutes, with a button that plays it as a loop.Without ControlsA frame with no pan or zoom buttons, for a map that has its own.