Route map

Installation

The command adds the example above to components/charts/ and, the first time, the chart kit to components/ui/charts/. Both are source files in your project from then on: read them, change them, delete what you don't use.

Usage

data holds two lists. places each have an id, a longitude and a latitude, and routes name two places by from and to, with an optional value. A route to a missing place is skipped.

import { worldCountries } from "@/components/charts/data/world-countries";
import {
  RouteMapChart,
  RouteMapLand,
  RouteMapPlaces,
  RouteMapRoutes,
  RouteMapTooltip,
} from "@/components/ui/charts";

const network = {
  places: [
    { id: "LHR", latitude: 51.47, longitude: -0.45, name: "London" },
    { id: "JFK", latitude: 40.64, longitude: -73.78, name: "New York" },
    { id: "DXB", latitude: 25.25, longitude: 55.36, name: "Dubai" },
    { id: "SIN", latitude: 1.36, longitude: 103.99, name: "Singapore" },
  ],
  routes: [
    { from: "LHR", to: "JFK", value: 9800 },
    { from: "LHR", to: "DXB", value: 7200 },
    { from: "DXB", to: "SIN", value: 5200 },
  ],
};

export const HubRoutes = () => (
  <RouteMapChart
    ariaLabel="Daily passengers on our hub routes"
    data={network}
    geography={worldCountries}
  >
    <RouteMapLand />
    <RouteMapRoutes />
    <RouteMapPlaces />
    <RouteMapTooltip valueLabel="Passengers a day" />
  </RouteMapChart>
);

Anatomy

The layers stack in a fixed order: the world's outline, the land, the graticule, the routes, then the places on top.

<RouteMapChart data={network} geography={worldCountries}>
  <RouteMapGraticule />
  <RouteMapLand />
  <RouteMapRoutes />
  <RouteMapPlaces />
  <RouteMapTooltip valueLabel="Passengers" />
</RouteMapChart>

• RouteMapChart: Holds the places, the routes and the projection every layer shares.
• RouteMapGraticule: Lines of longitude and latitude, and the world's outline.
• RouteMapLand: The countries from geography.
• RouteMapRoutes: Each route as a great circle, wider the higher its value.
• RouteMapPlaces: A dot on each place.
• RouteMapTooltip: A route's two ends and value, or a place's name and how many routes touch it.
• RouteMapLegend: The route categories and their colors. It needs colorKey.

Routes and widths

Each route follows the shortest path over the globe between its two places, so long routes bow toward the poles on a flat map.

Its value sets the width, from 1 to 4 px by default (widthRange). Widths come in four steps on a square-root scale, not a smooth range, so routes of similar weight look the same. A route without a value is drawn at the thinnest.

Hovering routes

Thin lines are hard to hit, so the pointer doesn't have to land on one: the nearest route within 6 px is picked, and a place under the pointer wins over any route. The others dim to inactiveOpacity (0.25).

Regions and colors

Set fit="data" to fit the map to your places instead of the whole world, and projection="mercator" for a familiar regional view. Countries past the edge are clipped.

colorKey on <RouteMapRoutes> gives each value of a route's field its own chart color, in order of appearance, and <RouteMapLegend /> names them under the map.

Customization

The kit is in your project, in components/ui/charts/: your framework's components over a shared core/. Change a default there and every chart picks it up.

className goes on the chart's container, so size and spacing are utility classes.

content on <RouteMapTooltip> gets either a route or a place, with the other one null, so one function covers both. Any extra field on a route, such as a flight number or a carrier, is there to show.

<RouteMapPlaces> takes radius and color for the dots, and <RouteMapLand> the countries' fill, stroke and strokeWidth.

<RouteMapTooltip
  content={({ place, route }) => (
    <div className="px-3 py-2 text-sm">
      {route ? `${route.from} to ${route.to}` : place?.name}
    </div>
  )}
/>

Where a part renders content of its own, you pass it in. In React:

• RouteMapTooltip: content={({ route, place, index }) => …}

Loading state

With status="loading" the land stays, and skeleton arcs shimmer between a few dots on it. The pointer is ignored until "ready", when the skeleton fades and the real routes trace in.

loadingLabel puts a short line of text over the map.

Animation

The land fades in, the routes trace themselves from end to end, and the places pop in while the last ones are still drawing. animationDuration (900 ms) is how long each route takes to trace.

Change revealSignature to play it again. animate={false} and reduced motion both draw the map at rest.

Theming

Every color in the kit is one of your theme's tokens or a mix of them, except --chart-positive, a fixed green. A preset or the .dark class restyles the chart, and overriding a token in your CSS changes it everywhere.

Routes default to --chart-1, and with colorKey they take --chart-1 to --chart-5 in order. Places are --chart-foreground, the land --muted with --chart-background borders.

:root {
  --chart-background: var(--background);
  --chart-tooltip-background: var(--card);
}

Accessibility

The map is announced as an image named by ariaLabel ("Route map" by default). Say what the routes carry and over what period, and name the busiest in ariaDescription.

Arrow keys move through the places and routes from left to right, a route counted at its midpoint. Each shows the tooltip it shows on hover.

API reference

RouteMapChart

RouteMapRoutes

RouteMapPlaces

RouteMapLand

RouteMapGraticule

RouteMapTooltip

RouteMapLegend