Configuration Overview

Every ApexMaps instance is configured through one options object passed to the constructor. The tree is plain and JSON-serializable, functions are only needed for formatters and accessors, so a saved config can round-trip through map.toSpec(), a database, or another chart's author.

const map = new ApexMaps(element, options)
await map.render()

The top-level shape:

interface ApexMapsOptions {
  chart?: ChartOptions
  geo?: GeoOptions
  series?: Series[]
  dataLabels?: DataLabelOptions
  interaction?: InteractionOptions
  link?: { group?: string; filter?: 'bidirectional' | 'emit' | 'receive' }
  legend?: LegendOptions
  tooltip?: TooltipOptions
  a11y?: A11yOptions
  states?: StatesOptions
  theme?: { mode?: 'light' | 'dark' | 'auto'; palette?: PaletteName }
  annotations?: AnnotationOptions
  debug?: { enabled?: boolean | 'auto'; joinDiagnostics?: boolean }
  responsive?: ResponsiveRule[]
}

Nothing is required except geo.map. Every other key merges under a documented default, so { geo: { map: 'world/countries@110m' }, series: [{ joinBy: 'name', data }] } is a complete, publishable map.

chart

Sizing, the rendering backend, and animation.

Key	What it controls
`width`, `height`	Container size. Numbers are pixels, strings are CSS (`height` defaults to `400`, `width` to `'100%'`)
`type`	Default series `type` for series that omit one. Defaults to `'choropleth'`
`background`, `fontFamily`	CSS background and font for the plot
`context`	`'dashboard'` (default, no entrance animation) or `'story'` (animates entrances). Story mode is a licensed feature
`animations`	`{ enabled, speed, entrance }`. `speed` accepts `'slow' \| 'normal' \| 'fast' \| 'instant'` or a millisecond number
`events`	Inline handlers, keyed by event name, as an alternative to `map.on()`

geo

Which geometry to draw, and how to project and frame it.

Key	What it controls
`map`	A registry id, a URL, or a GeoJSON/TopoJSON object. The only required option
`projection`	A name or a spec object (`rotate`, `parallels`, `clipAngle`, ...). Defaults to `'equalEarth'`
`view`	`{ fit: 'data' \| 'world' \| 'none' \| bbox, padding }`
`graticule`, `sphere`	The latitude/longitude grid and the outer sphere outline
`keyField`, `nameField`, `object`	Force the geometry's join-key property, label property, or TopoJSON object name
`repairWinding`	Normalize ring winding on ingest. On by default

Geometry packs, aliases, and what travels with each one are covered in Geometry Registry. Projection names, spec objects, and registering your own are covered in Projections. A geo with no series at all draws an automatic basemap, see Basemap.

series

An array of a discriminated union: choropleth, bubble, marker, arc, or line. Every series shares name, joinBy, fuzzyJoin, data, stroke, opacity, and valueField; the rest is specific to what the series draws.

series: [
  { type: 'choropleth', name: 'Unemployment rate', joinBy: ['iso_a3', 'code'], data },
  { type: 'bubble', name: 'Metro population', data: cities, size: { scale: 'sqrt' } },
]

Choropleth: fill regions by value, with scale, normalizeBy, and per-series drilldown
Bubbles: proportional-symbol circles for absolute magnitudes
Markers and Clustering: fixed-size point markers, seven shapes, and distance-based clustering
Arcs and Routes: great-circle arc connections and vertex-defined line routes
Drilldown: the drilldown option on a choropleth series, states into counties and back
Scales and Classification: how scale buckets values into classes
Palettes: the built-in color ramps scale.palette and colorScale.palette select from

joinBy and the automatic join-key detection, mismatch diagnostics, FIPS repair, and fuzzyJoin are covered on their own in Joins.

dataLabels

Text drawn directly on features, separate from the legend and the tooltip.

dataLabels: {
  enabled?: boolean
  field?: string | ((datum: unknown) => string)
  formatter?: (context: { value: number | null; name?: string; key?: string }) => string
  collision?: 'hide' | 'none'
  minFeatureArea?: number
  style?: { fontSize?: number; fontWeight?: number | string; halo?: boolean }
}

collision: 'hide' (the default) drops labels that would overlap, culled by projected feature area before any per-label work runs. See Legends, Labels & Tooltips for labels alongside the legend and tooltip they usually appear with.

interaction

Zoom, pan, selection, and hover assistance for point marks.

Key	What it controls
`zoom`	`{ enabled, min, max, wheel, doubleClick, step }`
`pan`	`{ enabled, inertia }`
`selection`	`{ enabled, multiple, rectangle, modifier }`. Click to select, shift-drag a box for more
`nearest`	Proximity hit assistance in screen pixels for bubbles, markers, and clusters

Zoom, pan, and the imperative camera API (flyTo, easeTo, fitBounds, frameFeature) are covered in Zoom, Pan & Camera. Selection, the dimming it applies through states.muted, and linking selection across maps are covered in Selection and Linked Maps.

link

Cross-filter group: maps naming the same group share their selection.

link?: { group?: string; filter?: 'bidirectional' | 'emit' | 'receive' }

filter controls direction: 'bidirectional' (default) brushes both ways, 'emit' sends without receiving, 'receive' follows without leading. This is a licensed feature, see Selection and Linked Maps for how it works without a key and what the watermark covers.

legend

legend?: {
  show?: boolean
  position?: 'bottom' | 'top' | 'left' | 'right'
  align?: 'start' | 'center' | 'end'
  title?: string
  interactive?: boolean
  showNull?: boolean
  style?: 'auto' | 'classes' | 'gradient'
  formatter?: (item: LegendItem, index: number) => string
}

interactive: true (the default) lets a reader click a class to mute it. See Legends, Labels & Tooltips for the classed, gradient, and nested-circle legend styles.

tooltip?: {
  enabled?: boolean
  followCursor?: boolean
  formatter?: (context: TooltipContext) => string
  valueFormatter?: (value: number) => string
  offset?: [number, number]
}

formatter returns HTML and is responsible for its own escaping. Covered alongside the legend in Legends, Labels & Tooltips.

a11y?: {
  enabled?: boolean
  description?: 'auto' | string
  label?: string
  dataTable?: boolean
  keyboardFeatureLimit?: number
}

On by default, and free in every license tier, permanently. description: 'auto' generates a description from the spec and the data. See Accessibility for ARIA roles, keyboard navigation, and the optional data table.

Other top-level keys

A few keys sit outside the nine above but are still part of the tree:

states: { hover, active, muted }, the hover brightness, active outline, and the opacity everything dims to while a selection is active
theme: { mode: 'light' | 'dark' | 'auto', palette }, the default color mode and fallback palette
annotations: { points, features, areas }, editorial overlays pinned to a coordinate, a feature, or a region. Licensed, see Annotations
debug: { enabled: boolean | 'auto', joinDiagnostics }. 'auto' (the default) turns on console diagnostics, including the join report, on localhost
responsive: an array of { breakpoint, options } rules, the narrowest matching breakpoint wins

Option area	Detail page
`geo.map`	Geometry Registry
`geo.projection`	Projections
`geo` with no series	Basemap
`series` (choropleth)	Choropleth
`series` (bubble)	Bubbles
`series` (marker, `cluster`)	Markers and Clustering
`series` (arc, line)	Arcs and Routes
`series[].drilldown`	Drilldown
`series[].scale`	Scales and Classification
`scale.palette`, `colorScale.palette`	Palettes
`legend`, `tooltip`, `dataLabels`	Legends, Labels & Tooltips
`interaction.zoom`, `interaction.pan`	Zoom, Pan & Camera
`interaction.selection`, `link`	Selection and Linked Maps
`annotations`	Annotations
`a11y`	Accessibility
`series[].joinBy`, `fuzzyJoin`	Joins