Symbol Config

Symbol properties control the appearance of markers and point dataset features. The same properties apply whether you are configuring a marker, app-wide defaults via the constructor symbolDefaults, or a custom symbol registration.

How values are resolved

Each property is optional. A value set directly on a marker or dataset layer takes priority over everything else. If a property is not set there, the value registered with the symbol is used. If the symbol has no value for that property, the app-wide symbolDefaults from the constructor applies. If none of those are set, the built-in fallback listed under each property below is used.

haloColor, selectedColor, and activeColor are required tokens in the SVG structure (see SVG structure). Include them in any custom svgContent — the app resolves their values automatically. All three are derived from the active map style — configure them via MapStyleConfig, not per symbol or marker.

Style-keyed colours

Any colour property can be a plain string or an object keyed by map style ID. This lets a single config work across all basemaps:

Copy
backgroundColor: '#d4351c'
backgroundColor: { outdoor: '#d4351c', dark: '#ff6b6b' }

Properties

symbol

Type:

string

Default:

'pin'

Registered symbol ID to use. Built-in values: 'pin', 'circle', 'square', 'hexagon', 'triangle', 'diamond'. Ignored when svgContent is set.

size

Type:

'small' | 'medium' | 'large'

Default:

'medium'

Size of the symbol on the map: 'small' is 75% and 'large' 125% of 'medium'. The shape and its graphic scale; the white halo and the selected/active rings stay the same width. The map key always shows symbols at 'medium'.

SVG-template symbols (svgContent, or a symbol registered with svg) are scaled as a whole, including any rings they draw.

svgContent

Type:

string

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

Copy
{
  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]
}

See SVG structure for the standard three-layer pattern. Anything drawn outside the viewBox is cut off.

viewBox

Type:

string

Default:

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

SVG viewBox attribute. Use alongside svgContent when your paths use a different coordinate space. Ignored by built-in symbols.

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. Each built-in symbol has its own default: the tip for 'pin', the centroid for 'triangle', and the centre for the others.

• On a built-in symbol, [0, 0] is the top-left and [1, 1] the bottom-right of the shape.
• On a custom SVG symbol (svgContent or a registered svg), it's a fraction of the symbol's viewBox.

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

backgroundColor

Type:

string | Record<string, string>

Default:

'#ca3535'

Background fill colour of the symbol shape.

foregroundColor

Type:

string | Record<string, string>

Default:

'#ffffff'

Foreground fill colour — the inner graphic element (e.g. the dot inside a pin).

graphic

Type:

string

SVG d attribute value for the foreground graphic path. Replaces the inner shape (e.g. the dot inside a pin) while keeping the background, halo and selection ring intact.

Pass a built-in name or supply your own path data:

Copy
// Named built-in — resolved automatically
{ symbol: 'pin', graphic: 'cross' }

// Inline path data
{ symbol: 'pin', graphic: 'M14 12 L24 20 L14 28 Z' }

Path data can use any coordinate space, such as a 24×24 icon. The graphic is centred in the shape and scaled down, if needed, to fit a 16×16 area.

Built-in named graphics (16×16 coordinate space, centred at 8,8):

graphic follows the full resolution order above — it can be set as a symbol default, a constructor default, or per item.

Custom tokens

Any {{token}} placeholder in a symbol SVG beyond the built-in set is substituted automatically if a matching key is present anywhere in the resolution order:

Copy
// Symbol SVG contains: fill="{{accentColor}}"
markers.add('id', coords, { accentColor: '#ffdd00' })

SVG structure

Symbols are defined as inner SVG path content (no <svg> wrapper) using {{token}} placeholders. The standard three-layer structure is:

Copy
svg: `
  <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}}"/>
`

• Layer 1 — ring layer: fill is the selected ring ({{selectedColor}}), stroke is the active ring ({{activeColor}}). Both hidden in normal rendering. paint-order="stroke fill" ensures the stroke extends outward without clipping the fill.
• Layer 2 — background shape with fixed halo stroke
• Layer 3 — foreground graphic (e.g. inner dot)