# WorldMap

> A dotted world map with office pins; each pin names its place on hover or focus and links to it on a full map.

URL: https://apogee.avaui.dev/docs/world-map
Last updated: 2026-10-16

A dotted world map with office pins; each pin names its place on hover or focus and links to it on a full map.

Last updated October 16, 2026

```astro
<WorldMap pins={pins} />
```

## Add

```sh
npx @ava-ui/apogee add world-map
```

Pulls in Tooltip. The land is drawn from Natural Earth (public domain): each region has its own grid of dots, framed to that continent alone, with dots the same size in every region. Where land runs on past a region’s frame (Russia east of Europe, the Aleutians west of North America), its dots fade out. Each region is drawn at its own latitude, so shapes come out true rather than stretched sideways. Europe includes Turkey and Cyprus; North America leaves out Greenland, which the world map shows. All seven grids together are about 25 KB.

## Usage

```astro
---
import WorldMap from '@/components/apogee/WorldMap/WorldMap.astro'
---
<WorldMap pins={[{ label: 'London', detail: '100 Oxford Street', lat: 51.5154, lon: -0.141 }]} />
```

## API

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `pins` | `{ label, lat, lon, detail?, href? }[]` | — | Required. `detail` is the second tooltip line (an address); `href` overrides the full-map link. |
| `label` | `string` | `'Our offices'` | Names the map for screen readers. |
| `region` | `'world' \| 'north-america' \| 'south-america' \| 'europe' \| 'africa' \| 'asia' \| 'oceania'` | `'world'` | The whole world, or one continent on its own grid: only its land, framed tightly, with dots the same size as every other region’s. |
| `class` | `string` | — | Extra classes on the root, merged last. Width fills; height follows the region’s shape (5:2 for the world). |

## Variants

Every `region`, each with an office in it:

```astro
<WorldMap region="north-america" pins={[…]} />
<WorldMap region="south-america" pins={[…]} />
<WorldMap region="europe" pins={[…]} />
<WorldMap region="africa" pins={[…]} />
<WorldMap region="asia" pins={[…]} />
<WorldMap region="oceania" pins={[…]} />
```

## States

-   **Hover or focus a pin** — a tooltip shows the place and its address.

## Examples

On a contact page: [Map 02](https://apogee.avaui.dev/docs/contact-sections/map-02) and [Vector map 03](https://apogee.avaui.dev/docs/contact-sections/vector-map-03).

## Accessibility

-   The dots are decoration and hidden from screen readers; the pins carry the meaning.
-   Each pin is a link named by its place and address (“Melbourne, 100 Flinders Street…, opens a map in a new tab”), reachable by Tab, with the tooltip on focus.
-   The map is a named group, so a screen reader announces “Our offices” before the pins.
-   Pins sit between 84°N and 60°S; places outside that band fall off the edge.

## Tokens

| Token | Used for |
| --- | --- |
| `--foreground-neutral-faded` | The dots (at half strength) |
| `--background-primary` | Pins |
| `--outline-color-focus` | Pin focus ring |

## Do / Don’t

-   **Do** pair it with the addresses as text; hide it on phones, where the pins get too small to tap.
-   **Don’t** use it for more than a dozen places; they crowd.

## Content

-   Pin labels are the city; the address goes in `detail`.

## Related

[

MapEmbedAn embedded street map centred on a place, with a marker and a link to the full map; no key, no script.

](https://apogee.avaui.dev/docs/map-embed)[

TooltipA short hint shown on hover and keyboard focus, anchored to its trigger in the top layer with hover intent.

](https://apogee.avaui.dev/docs/tooltip)