Symbol Registry

The symbol registry is a service that manages reusable named symbols for map markers. It is available to plugin authors via services.symbolRegistry.

Application code that needs a one-off custom marker should pass symbolSvgContent directly to addMarker() via MarkerOptions instead — no registration required.

Built-in symbols

Three symbols are registered by default:

ID	Anchor	Description
`'pin'`	`[0.5, 1]`	Teardrop pin — tip aligns with the coordinate
`'circle'`	`[0.5, 0.5]`	Filled circle — centre aligns with the coordinate
`'square'`	`[0.5, 0.5]`	Rounded square — centre aligns with the coordinate

Both use the standard {{token}} placeholders and respect the resolution order described in Symbol Config.

Methods

Available on services.symbolRegistry inside a plugin.

`setDefaults(defaults)`

Set constructor-level defaults. Called automatically during app initialisation with the symbolDefaults constructor config. Plugin authors do not normally need to call this.

`getDefaults()`

Returns the merged app-wide defaults (hardcoded symbolDefaults.js + constructor overrides).

const defaults = services.symbolRegistry.getDefaults()
// { symbol: 'pin', backgroundColor: '#ca3535', foregroundColor: '#ffffff', ... }

`register(symbolDef)`

Register a custom symbol. Once registered it can be referenced by ID via MarkerOptions.symbol or a dataset style.symbol.

Property	Type	Required	Description
`id`	`string`	Yes	Unique symbol identifier
`svg`	`string`	Yes	Inner SVG path content with `{{token}}` placeholders — see SVG structure
`viewBox`	`string`	Yes	SVG viewBox, e.g. `'0 0 44 44'`
`anchor`	`[number, number]`	Yes	Normalised [x, y] anchor point
(token)	`string \| Record<string, string>`	No	Default token value for this symbol, e.g. `backgroundColor: '#1d70b8'`. `selectedColor` and `activeColor` are ignored here — they are always derived from the active map style.

services.symbolRegistry.register({
  id: 'star',
  viewBox: '0 0 44 44',
  anchor: [0.5, 0.5],
  backgroundColor: '#1d70b8',
  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}}"/>
  `
})

See Symbol Config for the full list of token properties and the SVG structure convention.

`get(id)`

Returns the symbol definition for the given ID, or undefined if not registered.

const symbolDef = services.symbolRegistry.get('pin')

`list()`

Returns an array of all registered symbol definitions.

const symbols = services.symbolRegistry.list()

`resolve(symbolDef, styleColors, mapStyle)`

Resolves a symbol's SVG for normal (unselected, inactive) rendering. Both {{selectedColor}} and {{activeColor}} are replaced with 'none', so neither ring is visible.

const svg = services.symbolRegistry.resolve(
  services.symbolRegistry.get('pin'),
  { backgroundColor: '#d4351c' },
  mapStyle
)

`resolveActive(symbolDef, styleColors, mapStyle)`

Resolves a symbol's SVG for active (keyboard cursor) rendering. Both {{selectedColor}} and {{activeColor}} are live — the committed ring and the focus ring are both visible simultaneously, so an active item always shows both rings regardless of whether it is also selected.

const svg = services.symbolRegistry.resolveActive(
  services.symbolRegistry.get('pin'),
  { backgroundColor: '#d4351c' },
  mapStyle
)

`resolveSelected(symbolDef, styleColors, mapStyle)`

Resolves a symbol's SVG for committed-selection rendering. {{selectedColor}} is live (the black committed ring is visible) but {{activeColor}} is forced to 'none' — use this when an item is selected but not the current keyboard cursor.

const svg = services.symbolRegistry.resolveSelected(
  services.symbolRegistry.get('pin'),
  { backgroundColor: '#d4351c' },
  mapStyle
)