Installation & Usage

ApexMaps is a JavaScript library for interactive geographic data visualization: choropleths, proportional-symbol bubbles, categorical markers with clustering, and great-circle routes, drawn over a built-in geometry registry so you are not the one finding, converting, and hosting boundary files.

Installation

npm install apexmaps

import ApexMaps from 'apexmaps'

Quick start

A map needs exactly two things: which geometry to draw, and which data joins to it. Everything else, projection, palette, classification, legend, labels, and tooltip, has a default meant to be publishable as-is.

import ApexMaps from 'apexmaps'

const map = new ApexMaps(document.querySelector('#map'), {
  geo: { map: 'world/countries@110m' },
  series: [
    {
      name: 'Unemployment rate',
      joinBy: ['iso_a3', 'code'],
      data: [
        { code: 'FRA', value: 7.3 },
        { code: 'DEU', value: 5.7 },
      ],
    },
  ],
})

await map.render()

'world/countries@110m' is a registry id, one of 26 built-in geometry packs. See Geometry Registry for the full list and what travels with each pack. joinBy matches the geometry's iso_a3 property against each row's code field; see Joins for the other forms and what happens when a join fails.

Rendering is asynchronous

render() returns a promise. Geometry can come from a registry pack, a URL, or a plain object, so the map may need a network round trip before anything is on screen:

await map.render()
map.camera.flyTo({ center: [2.35, 48.85], zoom: 6 })

Call methods that touch the rendered map, camera, setSelection(), updateSeries(), frameFeature(), only after render() resolves. When you remove the map from the DOM, call map.destroy() to release its resize observer, event listeners, and interaction handlers.

Server-side rendering

Constructing an instance, new ApexMaps(element, options), never throws in a server environment: importing and constructing the class is safe to run during SSR. render() is different. It checks for a usable document and window and is a no-op until both exist, so a server render of render() does nothing rather than failing.

In practice this means: create the instance wherever is convenient, but call render() from a browser-only lifecycle hook, a useEffect in React, onMounted in Vue, or afterNextRender/ngAfterViewInit in Angular, rather than at module scope or during a server render pass. The framework wrappers below handle this for you.

Setting the license

ApexMaps.setLicense(key) is a static call, shared across the whole ApexCharts family: one key covers ApexCharts, ApexGrid, and ApexMaps, but each library needs its own call. Call it once, before rendering any map:

import ApexMaps from 'apexmaps'

ApexMaps.setLicense('APEX-xxxxxxxx')

A handful of features, clustering, custom projections, drilldown, annotations, arc and line routes, and linked-map selection, work without a key so you can evaluate them, with a watermark on the map. See Licensing for the full picture and how the watermark tracks your options.

Framework wrappers

If you are building with a framework rather than plain DOM APIs, use the typed wrapper for it instead of the core package directly:

• React, react-apexmaps
• Vue, vue-apexmaps
• Angular, ngx-apexmaps

Each wrapper is typed against ApexMaps' own option types and handles the SSR guard and the render lifecycle for you.