Home > Docs > ApexMaps Skill

ApexMaps Skill

AI models routinely get map code wrong: hunting for a GeoJSON file to host instead of using the built-in geometry registry, forgetting that render() is async because geometry packs load lazily, joining data with the wrong key, or passing { lat, lon } in the wrong order for bubble coordinates.

The ApexMaps Skill is a context file you add to your project once. Your AI assistant reads it and generates correct ApexMaps code from the start: choropleths, pixel maps, proportional-symbol bubbles, markers, binned point density, great-circle arcs, and routes, all over a built-in geometry registry so there is no GeoJSON to find, host, or parse, plus hex tile maps and raster street tiles under a Web Mercator map.

→ GitHub: apexcharts/apexmaps-skill

Install

Claude Code

mkdir -p .claude/skills
cd .claude/skills
git clone https://github.com/apexcharts/apexmaps-skill.git

Cursor / Windsurf

curl -o .cursorrules https://raw.githubusercontent.com/apexcharts/apexmaps-skill/main/.cursorrules

GitHub Copilot

Reference the skill file in Copilot Chat:

@workspace #file:SKILL.md How do I build a choropleth of US states with ApexMaps?

Or paste the contents of .cursorrules into your Copilot custom instructions so it applies to all conversations.

Generic AI (ChatGPT, Gemini, etc.)

Paste the contents of SKILL.md into your system prompt or attach it as context at the start of the conversation.

As an npm dependency

npm install apexmaps-skill

import { skillFile, referencePath } from 'apexmaps-skill';
import { readFile } from 'node:fs/promises';

const skill = await readFile(skillFile, 'utf8');
const geo   = await readFile(referencePath('geo-and-projections.md'), 'utf8');

What the skill covers

  • Seven series types: choropleth (region fills), pixel (a choropleth drawn as a lattice of marks), bubble (proportional symbols), marker (points), hexbin (binned point density), arc (great-circle flow maps), and line (routes)
  • Built-in geometry registry: world countries, US states and counties, EU NUTS 0-3, and admin-1 boundaries for 15 countries, referenced by a pack id (geo: { map: 'us' }) so there is no GeoJSON to host or parse, and the seven hex tile layouts (geo.layout: 'hex')
  • Data joins: matching your rows to geometry with joinBy (for us/states the recommended key is the postal code, e.g. 'CA'), with choropleth rows as { <joinKey>, value } objects and null, never undefined, for missing values
  • Projections: choosing and configuring the map projection for the region you are drawing
  • Raster tiles: the geo.tiles street-tile underlay, which needs projection: 'webMercator'
  • Scales and palettes: classed (quantile, quantize, threshold) and continuous color scales, plus the built-in palettes
  • Interaction: drilldown, marker clustering, selection, and the camera API for programmatic pan and zoom, with the viewChange event and getView() for what is on screen
  • Theming and text: the family --apx-* tokens, the apexmaps/ignite-ui add-on that follows an Ignite UI theme, and locale for the text the map writes itself
  • Labels, legend, tooltip, and annotations
  • Lifecycle: new ApexMaps(el, options) then await map.render(); an instance is not reusable after destroy(); no CSS import is needed (styles are inlined)
  • Framework wrappers: react-apexmaps, vue-apexmaps, ngx-apexmaps

The skill's guidance (apexmaps-skill 1.4.0) is verified against apexmaps 1.3.0. apexcharts_list_products reports the skill and library versions the server you are connected to bundles. The library follows semantic versioning from 1.0.0, so breaking changes wait for a major.

Repository structure

├── SKILL.md                              # Main entry point
├── .cursorrules                          # Self-contained Cursor / Windsurf version
├── references/
│   ├── data-format.md                    # series types, joinBy, coordinate order, null handling
│   ├── geo-and-projections.md            # geometry registry, pack ids, projections
│   ├── styling-and-interaction.md        # scales, palettes, legend, tooltip, drilldown, camera
│   └── framework-wrappers.md             # React, Vue, Angular
└── install/
    ├── claude-code.md
    ├── cursor.md
    └── copilot.md

Repository

https://github.com/apexcharts/apexmaps-skill

See also: ApexCharts Skill for the core charting library, plus the ApexMaps docs and the ApexMaps library on GitHub.