MarkerConfig

A marker is a pin or symbol placed at a specific coordinate on the map, used to highlight a location. The properties below are used in the markers option to define initial markers. The MarkerOptions properties also apply to markers added at runtime via addMarker().

Properties

id

Type:

string (required)

Unique marker identifier. Use this ID to reference the marker when calling removeMarker().

coords

Type:

[number, number] (required)

Coordinates [lng, lat] or [easting, northing] depending on the CRS of the map provider.

options

Type:

MarkerOptions

Optional marker appearance options. See MarkerOptions below.

MarkerOptions

Controls the visual appearance of a marker. All properties are optional — unset values fall back through the resolution order.

symbol

Type:

string

Default:

'pin'

Symbol to use for this marker. Built-in symbols: 'pin', 'circle', 'square', 'hexagon', 'triangle', 'diamond'. For a custom one-off symbol, use svgContent instead.

size

Type:

'small' | 'medium' | 'large'

Default:

'medium', or the constructor's symbolDefaults.size

Size of the marker's symbol — see Symbol Config.

svgContent

Type:

string

Inner SVG path content (no <svg> wrapper) to render instead of a registered symbol. Use {{token}} placeholders for colours. When set, symbol is ignored.

Copy
// Using built-in tokens with per-style colours
markers.add('id', coords, {
  svgContent: `
    <path d="..." fill="{{selectedColor}}" stroke="{{activeColor}}" stroke-width="6" paint-order="stroke fill"/>
    <path d="..." fill="{{backgroundColor}}" stroke="{{haloColor}}" stroke-width="2" paint-order="stroke fill"/>
    <path d="..." fill="{{foregroundColor}}"/>
  `,
  viewBox: '0 0 44 44',
  anchor: [0.5, 1],
  backgroundColor: { outdoor: '#d4351c', dark: '#ff6b6b' }
})

// Using a custom token
markers.add('id', coords, {
  svgContent: `
    <path d="..." fill="{{customColor}}"/>
  `,
  viewBox: '0 0 38 38',
  anchor: [0.5, 0.5],
  customColor: { outdoor: '#1d70b8', dark: '#4c9ed9' }
})

{{selectedColor}} and {{activeColor}} are required to render the selection and focus rings.

viewBox

Type:

string

Default:

registered symbol's viewBox, or '0 0 44 44'

SVG viewBox attribute for the symbol. Use alongside svgContent when your paths use a different coordinate space.

anchor

Type:

[number, number]

Default:

registered symbol's anchor, or [0.5, 0.5]

Normalised [x, y] anchor point — which point on the symbol sits on the geographic coordinate. On a built-in symbol it's a fraction of the shape; on a custom SVG symbol it's a fraction of its viewBox. See Symbol Config: anchor.

Copy
anchor: [0.5, 1]   // bottom-centre of the shape
anchor: [0.5, 0.5] // centre

label

Type:

string

Plain-text label for this marker. Serves two purposes:

1. Accessible name — always used as the aria-label on the marker SVG, even when no bubble is visible.
2. Visible bubble — rendered as a tooltip-style label above the symbol when showLabel is true, or as a standalone label with a down-arrow when symbol is null.

Copy
// Accessible name only — no visible bubble
markers.add('id', coords, { label: 'Town Hall' })

// Visible label bubble above the pin
markers.add('id', coords, { label: 'Town Hall', showLabel: true })

// Standalone label — no symbol, arrow points to the coordinate
markers.add('id', coords, { label: 'Town Hall', symbol: null })

showLabel

Type:

boolean

Default:

false

Whether to render a visible label bubble above the marker symbol. When false, label is still used as the accessible name of the marker.

Colour and graphic properties

backgroundColor, foregroundColor, graphic, and any custom tokens are all supported.

See Symbol Config for the full property reference.