World Map `<mv-world-map>`

Dotted SVG world map built from public-domain Natural Earth land data, with true great-circle routes that draw in and carry small packets, beacons on hub cities, crisp HTML labels and a screen-reader list of every place and connection.

Category	Media
Type	Web Component (`<mv-world-map>`)
Status	stable
Keywords	map, world, dotted-map, arcs, routes, great-circle, markers, svg, connections, hero

When to use

Global presence, offices or customers must be shown as markers on a flat dotted map
Shipping lanes, flights or data links between cities should read as real routes with flowing packets
A wide hero or about section needs every location visible at once without 3D interaction

Avoid when

A rotating, draggable 3D earth is wanted as a centerpiece → use Globe instead
Precise geography, zoom, panning or many data points are needed; use a dedicated mapping library

Install

node scripts/add.mjs world-map --out ./src/marvelous

AI agent with the Marvelous UI MCP server: install_components({ slugs: ["world-map"], target_dir: "<absolute path>/src/marvelous", framework: "react" }).

Files copied (dependencies included): tokens/tokens.css, core/base.css, core/dom.js, core/element.js, core/i18n.js, core/observe.js, components/world-map/world-map.js, components/world-map/world-map-land.js, components/world-map/world-map.css.

Usage

Canonical markup, to start from and customize with attributes, data-* and CSS variables:

<div style="display:grid;gap:1.25rem;width:100%;max-width:64rem;margin-inline:auto">
  <header style="display:flex;flex-wrap:wrap;align-items:end;justify-content:space-between;gap:1rem">
    <div>
      <p style="margin:0 0 .4rem;font:600 .75rem/1 var(--mv-font-mono);letter-spacing:.12em;text-transform:uppercase;color:var(--mv-accent-fg)">Shipments in transit</p>
      <h3 style="margin:0;font:700 clamp(1.3rem,2.4vw,1.75rem)/1.15 var(--mv-font-sans);letter-spacing:-.02em">Nine warehouses, one network</h3>
    </div>
    <p style="margin:0;font-size:.85rem;color:var(--mv-fg-muted)">1,248 packages · 3.4-day average transit · hover a city</p>
  </header>
  <mv-world-map label="Shipping lanes between our warehouses" labels
    markers="51.51,-0.13,London; 40.71,-74.01,New York; -23.55,-46.63,São Paulo; 14.72,-17.47,Dakar; 25.2,55.27,Dubai; 1.35,103.82,Singapore; 35.68,139.69,Tokyo; 34.05,-118.24,Los Angeles; -33.87,151.21,Sydney"
    arcs="London>New York; London>São Paulo; London>Dakar; London>Dubai; Dubai>Singapore; Singapore>Sydney; Singapore>Tokyo; Tokyo>Los Angeles; Los Angeles>New York"></mv-world-map>
</div>

API

Attributes

Name	Type	Default	Description
`markers`	string		“lat,lng,Label; …” (label optional). The property also accepts [{ lat, lng, label }].
`arcs`	string		Routes: “0>1; Paris>Dakar” (indexes or labels) or hub (first to all), chain (one after another), all. The property accepts [[from, to], …].
`labels`	boolean		Shows marker labels as small HTML chips (otherwise a native tooltip on hover).
`columns`	number	`160`	Number of dot columns (40-400): grid density.
`stagger`	boolean		Offsets every other row by half a cell (hexagonal grid).
`duration`	number	`3.2`	Seconds a packet takes to travel a route from end to end.
`label`	string	`World map`	Accessible name of the figure.

Properties

Name	Type	Description
`markers / arcs`	Array	Read: parsed values; write: array or string.
`strings`	object	Overrides the screen-reader text: map, places, routes, route (“{from} to {to}, {distance}”).

Methods

Name	Description
`project(lat, lng)`	[x, y] coordinates in the viewBox (to overlay your own SVG elements).

CSS classes

Name	Description
`mv-world-map-dots / -arc / -line / -comet / -marker / -ping / -label`	Generated parts (stylable): -line is the route, -comet its traveling packets, -ping the beacon.

CSS variables

Name	Default	Description
`--mv-world-map-dot`	`fg 24%`	Dot color.
`--mv-world-map-dot-size`	`0.5`	Dot diameter, as a fraction of the cell.
`--mv-world-map-arc`	`var(--mv-accent)`	Route and packet color.
`--mv-world-map-marker`	`var(--mv-accent)`	Marker and beacon color.
`--mv-world-map-label`	`var(--mv-fg)`	Label color.

Accessibility

role=figure named by label; the SVG and the label chips are aria-hidden, and a visually hidden list gives every location and every connection with its great-circle distance (strings are overridable). Hovering a city highlights its routes. On a small map, a label that would overlap another label or pin moves to the other side of its pin, or gives way when neither side is free (the place stays in the pin tooltip and in the screen-reader list). Reduced motion: routes drawn at once, no packets and no beacons. Forced colors: system colors for dots, routes, pins and labels.