API: Methods and Events

Static methods live on the ApexMaps class itself. Everything else is called on an instance created with new ApexMaps(element, options), and most of it is only meaningful after render() resolves.

Statics

Static	Description
`ApexMaps.setLicense(key)`	Registers the license key shared across the whole ApexCharts family. Call once, before any map renders.
`ApexMaps.registerMap(id, geometry, meta?)`	Registers a geometry pack, or a loader function returning one, under `id`. `meta` carries source, license, vintage, and the recommended join key.
`ApexMaps.registerProjection(name, factory)`	Registers a `d3-geo`-style projection factory under `name`. Registering is free; drawing a map that uses a registered projection is a licensed capability. See Projections.
`ApexMaps.registerPalette(name, palette)`	Registers a custom color ramp, `{ kind, stops, colorblindSafe? }`, under `name` for `scale.palette`.
`ApexMaps.listMaps()`	Every registered map id, built-in and custom.
`ApexMaps.listProjections()`	Every registered projection name, built-in and custom.
`ApexMaps.listPalettes()`	Every registered palette name, built-in and custom.
`ApexMaps.palette(name)`	A palette's anchor stops and family: `{ kind, stops, colorblindSafe }`.
`ApexMaps.mapMeta(id)`	Provenance for a registered map: source, license, vintage, boundary policy, recommended join key.
`ApexMaps.catalogue()`	The built-in geometry catalogue with full provenance, for a picker UI or a docs table. Excludes anything added by hand with `registerMap()`.

Instance methods

Lifecycle and options

Method	Returns	Description
`render()`	`Promise<this>`	Builds and draws the map. Call once, after construction.
`updateOptions(options, flags?)`	`Promise<this>`	Merges new options into the current config and redraws. `flags.redrawGeometry` forces reprojection; a map or projection change infers it automatically.
`updateSeries(series)`	`this`	Replaces series data and tweens fills and radii instead of rebuilding the DOM.
`destroy()`	`void`	Tears down listeners, observers, animation frames, and DOM. The instance is not reusable afterward.

Selection

Method	Returns	Description
`setSelection(keys)`	`this`	Replaces the selection set.
`toggleSelection(key)`	`this`	Adds or removes one key.
`clearSelection()`	`this`	Empties the selection.

Drilldown

Method	Returns	Description
`drillTo(key)`	`Promise<boolean>`	Drills into a feature by key, exactly as a click on it would. Resolves `false` when the drilldown is declined: no such feature, no `drilldown` configured, or no child feature belongs to the parent.
`drillUp(levels?)`	`Promise<boolean>`	Climbs back out. Pass `Infinity` to return to the top level.
`drillDepth`	`number`	Read-only property: how many levels below the top are currently displayed.

Camera

Reach the camera through map.camera, available once the map has rendered.

Method	Returns	Description
`map.camera.jumpTo(target)`	`void`	Applies a camera state with no animation.
`map.camera.easeTo(target)`	`Promise<void>`	Animates with a fixed duration and easing. Use for short, mechanical moves.
`map.camera.flyTo(target)`	`Promise<void>`	Animates along a Van Wijk zoom-and-pan path. Use for narrative moves; duration derives from distance unless overridden.
`map.camera.fitBounds(bounds, options?)`	`Promise<void>`	Frames a world-space bounding box.
`map.camera.panBy(dx, dy)`	`void`	Pans by a screen-space delta.
`map.camera.stop()`	`void`	Stops any in-flight move where it is. Every new move calls this first, so moves retarget instead of queueing.
`frameFeature(key, options?)`	`Promise<void>`	Frames one feature by key, turning the globe first on a rotatable projection so a feature on the far side can be framed at all.
`resetView(options?)`	`Promise<void>`	Resets the camera to the initial fit, and the initial rotation on a globe.
`zoomIn()` / `zoomOut()`	`void`	Zooms one step (the `interaction.zoom.step` the `+` / `-` controls use), eased about the plot center.
`rotateTo(angles)`	`void`	Turns a rotatable projection to an absolute `[lambda, phi, gamma?]`, as a drag would. No-op on a projection that cannot rotate.

target accepts center, zoom, bounds, padding, maxZoom, or raw k / x / y. flyTo and easeTo also take duration and ease; flyTo additionally takes speed and curve. On the azimuthal family a center target is resolved as a rotation (quaternion slerp), not a screen-space pan, so flyTo can reach the far side of a globe. Two read-only properties report the current view: map.zoom (camera scale, 1 at the opening fit) and map.rotation ([lambda, phi, gamma], [0, 0, 0] on a projection that cannot rotate).

Export

Method	Returns	Description
`exportSVG(options?)`	`void`	Downloads the current view as a standalone `.svg` file.
`exportPNG(options?)`	`Promise<void>`	Rasterizes the current view and downloads it as a `.png`.
`getSvgString(options?)`	`string`	Returns the exported SVG markup as a string, with no download.
`dataURI(options?)`	`Promise<{ imgURI: string }>`	Returns the current view as a PNG data URI, for embedding rather than downloading.

options accepts background, scale (PNG pixel-density multiplier, default 2), and filename. See Export.

Diagnostics and serialization

Method	Returns	Description
`diagnoseJoin(seriesIndex?)`	`JoinResult \| null`	The programmatic form of the console join diagnostic: matched and unmatched counts, suggestions for near-misses, and which keys map to more than one feature.
`toSpec()`	`ApexMapsOptions`	Serializes the effective, resolved options tree. JSON-serializable.

Event subscription

Method	Returns	Description
`on(event, handler)`	`this`	Subscribes to one of the events below.
`off(event, handler?)`	`this`	Unsubscribes one handler, or every handler for the event when `handler` is omitted.
`emit(event, payload?)`	`void`	Emits an event manually. Mostly useful in tests.

Events

Most events carry a FeatureEventPayload: { key, name?, value, datum, properties?, seriesName?, seriesIndex, instance }. instance is the ApexMaps instance in every payload that has one.

Event	Payload	Fires when
`rendered`	`{ instance }`	The first `render()` finishes.
`updated`	`{ instance }`	`updateOptions()` or `updateSeries()` finishes applying a change.
`resized`	`{ width, height }`	The container resizes and the map redraws to fit.
`featureClick`	`FeatureEventPayload`	A geometry feature (choropleth or the automatic basemap) is clicked or activated with Enter. Fires before a resulting drilldown.
`featureHover`	`FeatureEventPayload`	Hover enters a geometry feature.
`featureFocus`	`FeatureEventPayload`	Keyboard roving-tabindex focus moves to a feature.
`markClick`	`FeatureEventPayload`	A point or path mark (bubble, marker, arc, or line item) is clicked.
`markHover`	`FeatureEventPayload`	Hover enters a point or path mark.
`clusterClick`	`FeatureEventPayload`	A marker cluster is clicked, before the camera flies to its members.
`drilldown`	`{ key, name?, from?, to?, depth, featureCount, instance }`	A deeper level is on screen, after it renders.
`drillup`	`{ to?, depth, instance }`	Climbing back out finishes.
`selectionChange`	`{ ids, source }`	The selection changes: a click, a box, `setSelection()` / `clearSelection()`, or a linked map broadcasting.
`legendToggle`	`{ classIndex, instance }`	A legend class is clicked to mute or unmute it.
`zoom`	`{ k }`	The camera scale changes.
`rotate`	`{ rotate: [lambda, phi, gamma] }`	The globe's rotation changes, during a drag or a rotation-aware camera move.
`rotateEnd`	`{ rotate: [lambda, phi, gamma] }`	A globe rotation gesture or move settles.
`panEnd`	`undefined`	A pan gesture ends.

map.on('featureClick', ({ key, value, datum }) => {
  console.log(key, value, datum)
})

map.on('drilldown', ({ key, depth, featureCount }) => {
  fetchCounties(key).then((rows) => map.updateSeries([{ ...series, data: rows }]))
})