Map

v1.0.0

Documentation Under Review

Catalyst Map wraps react-simple-maps with Catalyst design tokens, interactive geography and marker primitives, and seamless Popover integration — giving you a production-ready geographic visualization with zero additional configuration.

Installation

npm install @pmi/catalyst-map

import {
  MapRoot,
  MapGeography,
  MapGeographies,
  MapGeographyHighlight,
  MapMarker,
  MapMarkerCircle,
  MapZoomableGroup,
  MapLine,
  MapAnnotation,
  MapGraticule,
} from '@pmi/catalyst-map';

The Map component requires geographic data in GeoJSON or TopoJSON format. The Catalyst docsite ships an example file at /json/features.json. For custom data, common sources include Natural Earth Data and World Atlas TopoJSON.

API Reference

Map is a compound component built on react-simple-maps primitives. The sections below cover Catalyst-specific sub-components. Passthrough sub-components (MapRoot, MapMarker, MapGeographies, MapZoomableGroup, MapLine, MapAnnotation, MapGraticule) accept all props from the underlying react-simple-maps elements directly.

MapGeography

Renders a single geographic region with interactive visual states.

MapGeographyHighlight

Overlays a gradient highlight on a geography — typically used to indicate a selected region.

MapMarkerCircle

A circular SVG marker with hover and active states, designed for placement inside MapMarker.

Accessibility

Map is designed to meet WCAG 2.2 AA standards.

ARIA

• Interactive geographies and markers are mouse-driven by default. The component does not add tabIndex or keyboard handlers — if you need keyboard-accessible regions, pass tabIndex={0} and an onKeyDown handler to MapGeography directly.
• When using MapMarker with PopoverContent, add aria-label to the PopoverContent to describe the marker's data context (e.g. aria-label="Salary data for United States").
• MapGeographyHighlight is decorative — it adds no semantic content and needs no ARIA annotation.
• 1.4.3 Contrast (Minimum) — default geography fill and stroke colors (--surface-primary, --border-neutral-soft) and marker colors meet the 4.5:1 minimum. Verify contrast when applying custom className overrides.

Choosing the Right Component

Use Map when you need to display data tied to geographic locations. Reach for a different primitive when:

Related

• Chart
• Popover