Rendering Geometric Data and Maps in React
@visx/shape and @vx/shape are React component libraries for creating chart elements like arcs and lines, with @visx being the modern version of @vx. d3-shape is the underlying vanilla JavaScript engine that calculates the geometry for these shapes without any React dependency. react-simple-maps is a specialized library built on D3 Geo for rendering interactive maps within React applications. Together, these tools cover the spectrum from raw mathematical calculations to high-level map components.
Npm Package Weekly Downloads Trend
Github Stars Ranking
Stat Detail
Rendering Geometric Data and Maps in React
When building data visualizations in React, you need tools that can turn numbers into SVG paths. The packages @visx/shape, @vx/shape, d3-shape, and react-simple-maps all handle geometric data, but they operate at different levels of abstraction. Let's compare how they fit into your architecture.
🛠️ Maintenance Status: Active vs Deprecated
The first thing to check is whether the library is still supported. Using a deprecated package can lead to security risks and compatibility issues down the line.
@visx/shape is the current, actively maintained package from Airbnb.
- It receives regular updates and works with modern React versions.
- This is the standard choice for new React visualization projects.
// @visx/shape: Active import
import { Arc } from '@visx/shape';
function PieSlice({ data }) {
return <Arc data={data} />;
}
@vx/shape is the old name for the same library.
- It is officially deprecated and renamed to
@visx/shape. - You should not install this for new work.
// @vx/shape: Deprecated import
import { Arc } from '@vx/shape'; // ⚠️ Do not use
function PieSlice({ data }) {
return <Arc data={data} />;
}
d3-shape is a core D3 module that is highly stable.
- It is framework-independent and updated frequently.
- It is safe to use as a dependency for long-term projects.
// d3-shape: Stable import
import { arc } from 'd3-shape';
const pathGenerator = arc().innerRadius(0).outerRadius(100);
react-simple-maps is stable but less active than visx.
- It is still widely used for maps but has fewer recent feature updates.
- It remains a solid choice for dedicated map visualizations.
// react-simple-maps: Stable import
import { ComposableMap } from 'react-simple-maps';
function Map() {
return <ComposableMap>{/*...*/}</ComposableMap>;
}
🧩 Abstraction Level: Components vs Functions
How you write code depends on whether you want React components or raw JavaScript functions. This affects how much boilerplate you need to write.
@visx/shape provides ready-made React components.
- You pass props like
innerRadiusandouterRadiusdirectly to the component. - It handles the SVG path generation behind the scenes.
// @visx/shape: Component API
import { Arc } from '@visx/shape';
<Arc
outerRadius={100}
innerRadius={0}
data={datum}
/>
@vx/shape used the exact same component API.
- The only difference is the package name in your import statement.
- Migrating involves changing the import path only.
// @vx/shape: Component API (Legacy)
import { Arc } from '@vx/shape';
<Arc
outerRadius={100}
innerRadius={0}
data={datum}
/>
d3-shape gives you functions to generate path strings.
- You must create the generator and call it with data yourself.
- You then insert the result into a standard SVG
<path>element.
// d3-shape: Function API
import { arc } from 'd3-shape';
const arcGenerator = arc().innerRadius(0).outerRadius(100);
<path d={arcGenerator(datum)} />
react-simple-maps provides high-level map components.
- It abstracts away the geo-projection logic entirely.
- You focus on placing geographies rather than drawing paths.
// react-simple-maps: Map Component API
import { ComposableMap, Geo } from 'react-simple-maps';
<ComposableMap>
<Geo geography={geoJson} />
</ComposableMap>
🌍 Domain Focus: Charts vs Maps
Not all shape libraries are meant for the same job. Some are built for statistical charts, while others are built for geographic data.
@visx/shape is designed for statistical charts.
- It excels at pies, donuts, lines, and areas.
- It does not handle geographic projections out of the box.
// @visx/shape: Chart Focus
import { Pie } from '@visx/shape';
<Pie data={data} pieValue={d => d.value} />
@vx/shape was also designed for statistical charts.
- It shares the same limitations as
@visx/shaperegarding maps. - It is best avoided due to deprecation.
// @vx/shape: Chart Focus (Legacy)
import { Pie } from '@vx/shape';
<Pie data={data} pieValue={d => d.value} />
d3-shape is for general geometric shapes.
- It creates the math for arcs and lines but not maps.
- For maps, you would need
d3-geoalongside this package.
// d3-shape: General Geometry
import { line } from 'd3-shape';
const lineGenerator = line().x(d => d.x).y(d => d.y);
<path d={lineGenerator(data)} />
react-simple-maps is specialized for geographic maps.
- It is the only one here built specifically for GeoJSON and TopoJSON.
- It includes built-in support for zooming and panning maps.
// react-simple-maps: Map Focus
import { ZoomableGroup } from 'react-simple-maps';
<ZoomableGroup center={[0, 0]}>
{/* Map contents */}
</ZoomableGroup>
⚛️ React Integration Patterns
Each package handles the React lifecycle differently. Some manage state for you, while others expect you to handle it.
@visx/shape fits naturally into React renders.
- It accepts props and returns SVG elements.
- It works well with React state for animations.
// @visx/shape: React Props
function Chart({ radius }) {
return <Arc outerRadius={radius} />;
}
@vx/shape followed the same React pattern.
- It was built specifically for React from the start.
- The integration style remains valid in
@visx.
// @vx/shape: React Props (Legacy)
function Chart({ radius }) {
return <Arc outerRadius={radius} />;
}
d3-shape requires manual integration with React.
- You calculate the path in the render function or a memo.
- You are responsible for managing the SVG elements.
// d3-shape: Manual Integration
function Chart({ radius }) {
const path = arc().outerRadius(radius)();
return <path d={path} />;
}
react-simple-maps manages complex map state internally.
- It handles projection calculations and coordinate transforms.
- You interact with it via props like
centerorzoom.
// react-simple-maps: Internal State
function Map({ zoom }) {
return <ZoomableGroup zoom={zoom}>{/*...*/}</ZoomableGroup>;
}
📊 Summary: Key Differences
| Feature | @visx/shape | @vx/shape | d3-shape | react-simple-maps |
|---|---|---|---|---|
| Status | ✅ Active | ❌ Deprecated | ✅ Active | ✅ Stable |
| Type | React Components | React Components | JS Functions | React Components |
| Best For | Custom Charts | Legacy Code | Custom Logic | Geographic Maps |
| Learning Curve | Medium | Medium | High | Low |
| Map Support | ❌ (Use visx/geo) | ❌ (Use vx/geo) | ❌ (Use d3-geo) | ✅ Built-in |
💡 Final Recommendation
@visx/shape is the go-to choice for modern React charting. It balances ease of use with flexibility and is backed by a strong team. Use this for dashboards, analytics, and custom data views.
@vx/shape should only appear in older projects. If you see this in a codebase, plan to migrate it to @visx/shape to ensure future compatibility.
d3-shape is best when you need to build something unique that pre-made components cannot handle. It gives you the raw math without any React overhead.
react-simple-maps is the quickest way to get a map on the screen. If your project is map-heavy, this saves weeks of setup time compared to building from raw D3 Geo.
Final Thought: For most React teams, a mix of @visx/shape for charts and react-simple-maps for geography offers the best balance of speed and control. Avoid @vx entirely in new work.
How to Choose: react-simple-maps vs @visx/shape vs @vx/shape vs d3-shape
- react-simple-maps:
Choose
react-simple-mapsif your primary goal is to display geographic data like choropleths or point maps quickly. It handles the complex setup of D3 Geo and TopoJSON for you, offering ready-to-use components for zooming and panning. This package is best for projects focused specifically on maps rather than general statistical charts. - @visx/shape:
Choose
@visx/shapeif you are building custom charts in React and want pre-built components that wrap D3 logic. It is the maintained successor to@vxand integrates well with the rest of thevisxecosystem. This package is ideal for teams that want the power of D3 without writing low-level path generators manually. - @vx/shape:
Do not choose
@vx/shapefor any new project because it is deprecated and renamed to@visx/shape. The code API is nearly identical, but the package no longer receives updates or security patches. You should only encounter this in legacy codebases that have not yet migrated to the@visxnamespace. - d3-shape:
Choose
d3-shapeif you need full control over the mathematical generation of shapes or are working outside of React. It is the best option for custom React integrations where you want to calculate path data yourself and pass it to SVG elements. This package is suitable for developers who prefer functions over components and need maximum flexibility.
Popular Comparisons
README for react-simple-maps
react-simple-maps
Create beautiful SVG maps in react with d3-geo and topojson using a declarative api.
Read the docs, or check out the examples.
Why
React-simple-maps aims to make working with svg maps in react easier. It handles tasks such as panning, zooming and simple rendering optimization, and takes advantage of parts of d3-geo and topojson-client instead of relying on the entire d3 library.
Since react-simple-maps leaves DOM work to react, it can also easily be used with other libraries, such as react-spring and react-annotation.
Install
To install react-simple-maps
$ npm install --save react-simple-maps
...or if you use yarn:
$ yarn add react-simple-maps
Usage
React-simple-maps exposes a set of components that can be combined to create svg maps with markers and annotations. In order to render a map you have to provide a reference to a valid topojson file. You can find example topojson files on here or here. To learn how to make your own topojson maps from shapefiles, please read "How to convert and prepare TopoJSON files for interactive mapping with d3" on medium.
import React from "react";
import ReactDOM from "react-dom";
import { ComposableMap, Geographies, Geography } from "react-simple-maps";
// url to a valid topojson file
const geoUrl =
"https://raw.githubusercontent.com/deldersveld/topojson/master/world-countries.json";
const App = () => {
return (
<div>
<ComposableMap>
<Geographies geography={geoUrl}>
{({ geographies }) =>
geographies.map((geo) => (
<Geography key={geo.rsmKey} geography={geo} />
))
}
</Geographies>
</ComposableMap>
</div>
);
};
document.addEventListener("DOMContentLoaded", () => {
ReactDOM.render(<App />, document.getElementById("app"));
});
Check out the live example
The above will render a world map using the equal earth projection. You can read more about this projection on Shaded Relief and on Wikipedia.
For other examples and components, check out the documentation.
Map files
React-simple-maps does not restrict you to one specific map and relies on custom map files that you can modify in any way necessary for the project. This means that you can visualise countries, regions, and continents in various resolutions, as long as they can be represented using geojson/topojson.
In order for this to work properly, you will however need to provide these valid map files to react-simple-maps yourself. Luckily, there are decent sources for map files on github and elsewhere. Here are some you can check out:
License
MIT licensed. Copyright (c) Richard Zimerman 2017. See LICENSE.md for more details.