Clustered map

Playground#

Change a prop and the component re-renders. Props marked remounts set an initial value, so the component starts over.

<GeoCluster
  defaultZoom={1}
  maxZoom={6}
  cellSize={44}
  label="Clustered map"
/>

Installation#

pnpm dlx shadcn@latest add @lumesec/geo-cluster

pnpm dlx shadcn@latest registry add @lumesec=https://elements.lumesec.ai/r/{name}.json

npx shadcn@latest add https://elements.lumesec.ai/r/geo-cluster.json

Usage#

import { GeoCluster, type ClusterPoint } from "@/components/lumesec/geo-cluster";

const stores: ClusterPoint[] = [
  { id: "s1", lat: 51.5072, lon: -0.1276, label: "London Bridge" },
  { id: "s2", lat: 51.5155, lon: -0.0922, label: "Bank" },
  { id: "s3", lat: 48.8566, lon: 2.3522, label: "Paris Centre" },
];

export function Example() {
  return <GeoCluster points={stores} onPointClick={(store) => console.log(store.id)} />;
}

Behaviour#

A zoomable map for many points. Nearby points merge into clusters with a count; zooming in splits each cluster into its children, which spring out from where the parent was, and zooming out pulls them back together while the counts roll.

The land dots are re-sampled at the same pixel pitch for every zoom level, so coastlines sharpen as you zoom. Use Ctrl or ⌘ with the wheel, pinch, double-click, or the + and − buttons.

API reference#

Props#

Also accepts every prop of <div> (React.ComponentProps<"div">), spread onto the root element.

Ref#

ref points at the root HTMLDivElement.

Keyboard#

Accessibility#

• The map is a focusable role="group" with aria-roledescription="map", aria-label from label and a description of its keys.
• Clusters and points are native buttons in one roving tab stop. A cluster's aria-label reads like "34 locations around Lagos" (the nearest of 60 reference cities within 900 km, else its coordinates); a point's is its label or its coordinates. Points have aria-pressed for the selection.
• A cluster that holds the selected point adds ", includes the selected location" to its label and gets an accent ring.
• Nodes merging into a parent are inert and aria-hidden while they fly. When the focused node splits or merges, focus moves to its largest child or to its parent. Arrow keys skip nodes outside the frame.
• When the view settles, a polite live region announces the zoom and what is in the frame, for example "Zoom 3×, 12 clusters, 4 points".
• The zoom buttons are native buttons with aria-label ("Zoom out", "Zoom in", "Reset view") and are disabled at the zoom limits. The zoom readout is aria-hidden.
• A cluster that zooming cannot split has aria-haspopup="dialog" and aria-expanded. It opens a role="dialog" list of its points, sorted by name; focus moves to the first row and returns to the cluster when the list closes.
• Both canvases are aria-hidden; every count, name and coordinate is DOM text.
• Reduced motion: the zoom and pan jump without springs, clusters swap without splitting or merging, counts and the zoom readout swap without rolling, the land dots replace each other without a crossfade or the first reveal, and selections play no ripple or sparks.

Theming#

Styled with Tailwind classes on your shadcn theme tokens, so light and dark follow your theme. The accent comes from --lumesec. See Theming.

This component reads --lumesec, --lumesec-glint, --card, --border, --foreground, --muted-foreground, --popover, --popover-foreground, --accent and --background.

Notes#

• The map is Mercator, cut at 78° north and south, with its central meridian at 10° E so the side edges run through the Bering Strait. At zoom 1 the world fills the frame's width; the frame is 2:1 and at most 660 px wide (max-w-[660px]), so pass a width class to change it.
• Clusters are computed once per data set, cell size and frame width, for every whole zoom from 1 to maxZoom. The current level is the zoom rounded down, so a cluster splits when the zoom crosses the next whole number.
• Clicking a cluster glides it to the centre and zooms in until it splits. Points with identical coordinates, and clusters that are still closer than cellSize at maxZoom, open a list instead.
• The land dots are re-sampled at a 4 px pitch for each settled view, 120 ms after the zoom comes to rest, and crossfade over the previous lattice. While zooming out, the previous lattice drops every other row and column so its dots keep their spacing.
• At most 160 nodes are in the DOM: only those in or near the frame are rendered.
• One-finger touch pans only when zoomed in; at zoom 1 the page scrolls. Two fingers pinch to zoom.
• The cluster label uses the nearest reference city only as a place name. Your points and labels are shown as given.
• The animation loop runs only while something moves and pauses while the map is off screen.