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, proportional-symbol bubbles, markers, great-circle arcs, and routes, all over a built-in geometry registry so there is no GeoJSON to find, host, or parse.

→ 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

  • Five series types: choropleth (region fills), bubble (proportional symbols), marker (points), 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
  • 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
  • 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
  • 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 is verified against apexmaps 0.3.0 (pre-alpha). Expect option-level changes between minor versions until the library stabilizes.

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.