Symbol Map API

A force-de-overlapped symbol/bubble map: you supply lng/lat per item, a one-shot force simulation pulls overlapping circles apart - see the Symbol Map demo.

Import

Web Component

import "@michi-vz/wc/symbol-map-chart";
// <michi-vz-symbol-map-chart> is now defined

Vanilla JS

import { mountSymbolMapChart } from "@michi-vz/core";

const chart = mountSymbolMapChart(el, props);

Props

Prop	Type	Default	Description
timeline	boolean | TimelinePeriodConfig	-	Opt-in "play through years": snapshots one period at a time over the distinct per-row `date` values, with a headless controller (`chart.timeline()`) plus an optional built-in play button + scrubber. Off by default; requires rows with `date`. Values tween between periods unless `interpolate: false`.
dataSet*	SymbolMapDataItem[]	-	Array of symbols; each supplies its own lng/lat (core bundles no coordinate table).
geography	GeoJSON.FeatureCollection | GeoFeatureItem[]	-	OPTIONAL muted backdrop landmass (new capability - the legacy chart never drew one). A full GeoJSON FeatureCollection or a pre-normalized `GeoFeatureItem[]`, same contract as `ChoroplethMapChartProps.geography`. Omit for the legacy chart's dot-only look (the default).
title	string	-	Optional chart title rendered above the plot
projection	GeoProjectionName	-	d3-geo / d3-geo-projection projection (default "geoMercator", matching the legacy chart). With no `geography`, the projection is used UNTUNED (bare `factory()`, no translate/scale/rotate/center) and the projected point extent is rescaled to fill the plot - see the chart's docs page. With `geography` supplied, the SAME tuned dispatch as ChoroplethMapChart is used instead, so the backdrop and the symbols share one consistent geographic framing.
projectionConfig	GeoProjectionConfig	-	Fine-tunes the projection; only consulted when `geography` is supplied (see `projection`).
radiusRange	[number, number]	DEFAULT_RADIUS_RANGE	[min, max] circle radius in px (default [3, 70], the legacy `circleRange`). Mapped from the value domain via `buildSymbolMapRadiusScale`, whose domain is the TRUE combined extent of every item's `value` and `valueSecond` - DELIBERATELY NOT legacy Chart.js's own domain formula, which was defective (`[min(primaryMin, secondaryMax), max(primaryMin, secondaryMax)]` silently drops the primary max and secondary min). Relative circle sizes will differ from the legacy chart whenever `value` and `valueSecond` ranges diverge - see `symbolMap/scales.ts`'s `buildSymbolMapRadiusScale` for the worked example and the pinned regression test.
radiusVisibleMin	number	-	Hides items whose RAW `value` is <= this threshold (and, when `valueSecond` is set, whose `valueSecond` is also < this threshold) BEFORE the force layout runs - ported from the legacy chart's own filter, which compares the raw value/valueSecond, not the scaled radius. Omit to show every located item.
positionMode	"force" | "precise"	"force"	How symbols are placed: "force" (default) runs a one-shot de-overlap simulation that pulls colliding circles apart, while "precise" keeps every symbol at its exact projected lng/lat (overlaps allowed). - "force": a one-shot de-overlap simulation pulls colliding circles apart - readable for dense data, but symbols DRIFT from their true lng/lat (on small plots the drift can be large). Avoid it when the audience will read exact geographic position off the chart: a symbol drawn over the wrong country is a cartographic-accuracy problem and can be politically sensitive. - "precise": every symbol stays at its exact projected lng/lat; overlapping circles are allowed. Prefer this whenever a `geography` backdrop is shown, since a visible landmass invites reading positions literally.
geographyColor	string	DEFAULT_GEOGRAPHY_COLOR	Fill for the optional backdrop `geography` (default `#eef1f5`, a muted neutral).
strokeColor	string	DEFAULT_STROKE_COLOR	Border colour for the optional backdrop `geography` (default `#d7dce3`).
strokeWidth	number	1	Border width for the optional backdrop `geography`, in px (default 1).
showLabels	boolean	true	Draw a fitted label inside each circle when it is large enough (default true).
isLoading	boolean	-	Loading overlay (stale symbols hidden while true)
isNodata	boolean | ((dataSet: SymbolMapDataItem[] | null | undefined) => boolean)	-	No-data predicate/flag; default = empty dataSet
noDataLabel	string	-	Text for the built-in no-data overlay
suppressDefaultOverlay	boolean	-	Set by a framework wrapper passing its own overlay node - suppresses the default overlay
tooltipFormatter	(d: SymbolMapDataItem) => string	-	Formats the tooltip for a hovered symbol.
onHighlightItem	(labels: string[]) => void	-	Called when the hovered/highlighted label(s) change

Common props - shared by every chart (14)

Prop	Type	Default	Description
width	number	900	Chart width in pixels
height	number	520	Chart height in pixels
margin	Margin	{ top: 40, right: 10, bottom: 10, left: 10 }	Inner margins (top/right/bottom/left, in px) reserved for axes, titles, and labels
colors	string[]	-	Categorical palette for series/labels without an explicit colour or colorsMapping entry
colorsMapping	Record<string, string>	-	Explicit label -> colour map; takes precedence over the palette and per-item colours
highlightItems	string[]	-	Labels to emphasise; all other marks dim
disabledItems	string[]	-	Labels to hide and exclude from scales/stacks
renderer	"svg" | "canvas" | "webgpu"	"svg"	Render as inline SVG (default) or to a canvas (faster for large datasets); getContext() is identical either way
locale	string	-	BCP-47 locale used for number and date formatting
skipColorMappingDispatch	boolean	false	External-CSS mode: unmapped labels resolve to transparent and onColorMappingGenerated is not emitted, so mark colours come from your CSS via the data-label-safe contract
enableTransitions	boolean	true	Animate updates with CSS transitions (default true)
onColorMappingGenerated	(mapping: Record<string, string>) => void	-	Called with the resolved label -> colour map after the chart assigns colours
onChartDataProcessed	(context: ChartContext) => void	-	Called with the renderer-agnostic ChartContext whenever the data is (re)processed
onDataWarning	(warnings: DataWarning[]) => void	-	Called with any non-fatal data warnings (duplicate labels, non-finite values, non-monotonic dates, ...)

Events

The web component dispatches these bubbling CustomEvents (the engine exposes the same via the on* callbacks in the table above):

Event	Detail	Fires when
michi-vz:highlight	string[]	hover highlight changes
michi-vz:colormapping	Record<string, string>	a color mapping is generated
michi-vz:dataprocessed	ChartContext	data is (re)processed
michi-vz:datawarning	DataWarning[]	input warnings are detected (missing/invalid lng-lat, negative values, duplicate ids)

getContext()

mountSymbolMapChart(el, props).getContext() returns a renderer-agnostic SymbolMapChartContext: stats.locatedCount / visibleCount / hiddenCount (excluded by radiusVisibleMin) / invalidCount (dropped for bad coordinates) / valueDomain / min / max, a symbols[] array (one row per visible item: id, label, value, valueSecond, radius, radiusSecond, color), the resolved projection name, a deterministic natural-language summary, and an a11yTable. See LLM context.

Source

Props are typed as SymbolMapChartProps in @michi-vz/core.