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. Each map has its own registry, so symbols registered and symbolDefaults set on one map don't affect another on the same page.

Built-in symbols

Six symbols are registered by default:

Each can be shown at any size and takes a custom graphic. They use the same token resolution order as any other symbol.

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 map's merged defaults (hardcoded symbolDefaults.js + constructor overrides).

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

register(symbolDef)

Register a custom SVG-template symbol, such as one with several colours. Once registered it can be referenced by ID via MarkerOptions.symbol or a dataset style.symbol. Throws if id, svg or viewBox is missing, or anchor is invalid.

Copy
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.

getSymbolDef(style)

Returns the symbol definition for a dataset or draw style, sized for its symbolSize — with the viewBox and anchor for that size. Pass the result to the resolve methods.

Reads the style's symbol or symbolSvgContent, symbolSize, symbolViewBox and symbolAnchor. Marker options drop the symbol prefix (svgContent, size, viewBox, anchor); for those, use getMarkerSymbolDef.

getMarkerSymbolDef(options)

Returns the symbol definition for marker options, sized for their size — with the viewBox and anchor for that size. Reads svgContent or symbol, size, viewBox and anchor, each falling back to the map's defaults. Returns undefined when neither names a known symbol.

getKeySymbol(style, mapStyle)

Returns { svg, viewBox } for a dataset style's symbol as drawn in the map key: always at 'medium' size, and in the page's colour scheme (mapStyle.appColorScheme) rather than the map's. Returns null when the style has no known symbol.

getSizedSymbolDef(symbolDef, { viewBox, size, anchor })

Sizes a definition from get() (or { svg } for inline content) directly. viewBox only applies to SVG-template symbols; anchor is as described in Symbol Config: anchor.

get(id)

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

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

list()

Returns an array of all registered symbol definitions.

Copy
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.

Copy
const svg = services.symbolRegistry.resolve(
  services.symbolRegistry.getSymbolDef({ symbol: 'pin', symbolSize: 'large' }),
  { 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.

Copy
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.

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

resolveVariant(symbolDef, styleColors, mapStyle, variant)

Resolves a symbol's SVG for the named variant: 'normal' (resolve), 'active' (resolveActive) or 'selected' (resolveSelected).