Data Maps

A powerful, highly-customizable React-Leaflet based choropleth map component designed for beautifully visualizing geographic data, user distributions, and global trends without the need for clunky external map tiles. Built with SSR safety in mind: the component defers Leaflet until after mount, so it renders correctly whether or not your framework prerenders on a server — no hydration mismatches, no broken renders, and nothing for you to wrap.

It features interactive hover tooltips, multiple visual variants (such as solid region fills or density dots), country flag badges, trend indicators, and seamless theme integration that automatically adapts to your site's dark or light mode. Whether you're showing active users per country, traffic breakdowns, or global feature adoption — this component handles it with elegant simplicity. Perfect for building immersive dashboards, analytics panels, and global demographic visualizations in any React application.

The map is pure vector — it fetches world GeoJSON and paints country polygons, so there are no raster tiles to load. Hover any highlighted country for its data card.

Filled regions

PassdataPoints: as { id, name, flag, active, activeTrend }[] — id is the ISO-3 country code the map matches on.
variant"fill": is the default: it paints each matched country polygon in the accent colour and dims the rest.

Accent Color

Installation

New project? Follow the installation guide to set up Tailwind CSS, shadcn, the cn helper and lucide-react, register the @algorize-ui registry once, then copy your styles from the Themes page.

Install Data Maps

npx shadcn@latest add @algorize-ui/data-maps

components/custom/blocks/DataMapsBlock.tsx is written into your project. Copy any snippet from a Usage tab above and it runs.

Install dependencies

Step 1 installs these for you. Run them yourself only if you are adding Data Maps to an existing project by hand. The cn helper and lucide-react are not listed — the installation guide covers them once for every component.

geojson, leaflet and react-leaflet are npm packages.

npm install geojson leaflet react-leaflet

Examples

Density dots

Setvariant"dots": to swap the fills for pulsing centroid markers — the same data read as points rather than areas, which is easier when regions are small or crowded.

Zoomable

Setzoomable: to add the zoom controls and drag-to-pan. Off by default.
scrollWheelZoom: additionally binds the wheel — leave it off inside a scrolling page so the map never steals the scroll.
minZoom: and maxZoom bound how far the reader can go; zoom is the starting level.

Features

Learn about the Data Maps component's geographic visualization features, mapping interactive data points onto vector country paths.

SSR Compatible

Uses Next.js dynamic imports to safely load Leaflet client-side without hydration errors.

Lightweight Vectors

Fetches clean GeoJSON data on the fly instead of relying on heavy raster map tiles.

Dual Variants

Supports both solid polygon fills and modern pulsing dots for geographic emphasis.

Rich Hover Cards

Elegant tooltips with country flags, data metrics, and up/down trend indicators.

Best Practices & Guidelines

Dynamic Imports

Leaflet reads the browser's window at import time, so the component defers loading it until after mount. A Vite SPA has no server render, so there is nothing to opt out of — import and render it directly.

GeoJSON Caching

By default, the map fetches the world map GeoJSON from a remote CDN. For production environments, it is highly recommended to download the custom.geo.json file and host it locally in your public directory to reduce latency.

Props Reference

Component	Prop	Type	Default	Description
`DataMaps`	`dataPoints`	`DataPoint[]`	Required	An array of data point objects to display on the map. See the DataPoint reference below.
`DataMaps`	`variant`	`"fill" \| "dots"`	`"fill"`	The visual style of the map. `fill` colors the entire country polygon, while `dots` places a pulsing dot at the center of the country.
`DataMaps`	`center`	`[number, number]`	`[20, 0]`	The initial latitude and longitude coordinates to center the map on.
`DataMaps`	`zoom`	`number`	`2`	The initial zoom level of the map.
`DataMaps`	`highlightColor`	`string`	`var(--primary)`	The default fill color for highlighted countries.
`DataMaps`	`defaultColor`	`string`	`#cbd5e1`	The fill color for non-highlighted countries.

DataPoint Object

Object	Property	Type	Default	Description
`DataPoint`	`id`	`string`	Required	A 3-letter ISO 3166-1 alpha-3 country code (e.g. 'USA', 'IND', 'GBR'). Used to map data to the correct polygon.
`DataPoint`	`name`	`string`	Required	The title displayed in the header of the hover card.
`DataPoint`	`flag`	`string`	`undefined`	An optional emoji or text to display next to the country name (e.g., 🇺🇸).
`DataPoint`	`active`	`number`	`undefined`	An optional metric to display on the first line.
`DataPoint`	`activeTrend`	`"up" \| "down"`	`undefined`	Renders a green up-arrow or red down-arrow next to the `active` value.
`DataPoint`	`new`	`number`	`undefined`	An optional metric to display on the second line.
`DataPoint`	`newTrend`	`"up" \| "down"`	`undefined`	Renders a green up-arrow or red down-arrow next to the `new` value.
`DataPoint`	`color`	`string`	`undefined`	An optional custom fill color for this specific country, overriding the global highlight.