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
  locale?: LocaleOptions
  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%'). The plot is sized in whole pixels, rounded down, so a container with a fractional size gets a plot up to one pixel smaller rather than one that overflows it
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(). Every event in API: Methods and Events is accepted, including viewChange

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
layout	'hex' redraws the region set as one equal cell per region instead of real boundaries. Licensed feature
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
tiles	Raster tiles from a {z}/{x}/{y} tile server under a webMercator map. Off unless a url is given. Licensed feature
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. layout: 'hex', the seven built-in layouts, and the morph between a layout and real boundaries are covered in Hex Tile Layouts. A geo with no series at all draws an automatic basemap, see Basemap. geo.tiles, its options, and the request hook for keys and headers are covered in Raster Tiles.

series

An array of a discriminated union: choropleth, pixel, bubble, marker, hexbin, arc, or line. Every series shares name, data, stroke, opacity, and valueField; joinBy and fuzzyJoin apply to the series that resolve against geometry, and 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
• Pixel Maps: a choropleth drawn as a lattice of dots, squares, hexagons or diamonds
• Bubbles: proportional-symbol circles for absolute magnitudes
• Markers and Clustering: fixed-size point markers, seven shapes, and distance-based clustering
• Hexbin: point density on a hexagonal lattice, for more points than pixels
• 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

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

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

On by default, and included 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
• locale: the strings the map writes itself (zoom buttons, breadcrumb, data table headings, no-data text, size legend, drilldown announcements), each falling back to its English default. See Localization
• 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

See also

Option area	Detail page
geo.map	Geometry Registry
geo.projection	Projections
geo.layout	Hex Tile Layouts
geo with no series	Basemap
series (choropleth)	Choropleth
series (pixel)	Pixel Maps
series (bubble)	Bubbles
series (marker, cluster)	Markers and Clustering
series (hexbin)	Hexbin
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
locale	Localization
geo.tiles	Raster Tiles
series[].joinBy, fuzzyJoin	Joins