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:

• Natural Earth Atlas
• Topojson maps by @deldersveld
• Topojson world atlas

In order to get your map data into react-simple-maps, you can either reference a url with map data, or a file that you are serving from your own site. You can also load your topojson or geojson manually and feed it to react-simple-maps. All of this happens via the geography prop on the Geographies component.

// A url to a valid topojson file
<Geographies geography="https://raw.githubusercontent.com/deldersveld/topojson/master/world-countries.json">
  {...}
</Geographies>

// A reference to a valid topojson file in your project
<Geographies geography="/topojson-file.json">
  {...}
</Geographies>

// A reference to a valid geojson file in your project
<Geographies geography="/geojson-file.json">
  {...}
</Geographies>

// A valid geojson object
<Geographies geography={validGeojson}>
  {...}
</Geographies>

// A valid topojson object
<Geographies geography={validTopojson}>
  {...}
</Geographies>

Geojson

GeoJSON is a JSON-based open standard format designed to represent geographical features, alongside non-spatial attributes (properties). Geographic shapes would usually be represented as features in geojson. Each feature has a type, geometry, and properties attribute. properties is an object that can contain any kind of data that can be represented in JSON format. This can be time-series population data, GDP, or any other kind of data that relates to a given geography.

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Polygon",
        "coordinates": [
          [
            [10.6, 47.9],
            [5.8, 47.9],
            [5.8, 45.8],
            [10.6, 45.8],
            [10.6, 47.9]
          ]
        ]
      },
      "properties": {
        "firstProperty": "Something",
        "secondProperty": "Something else"
      }
    },
    { "type": "Feature", "geometry": {...}, "properties": {...} },
    { "type": "Feature", "geometry": {...}, "properties": {...} }
  ]
}

In react-simple-maps you can access the properties of a feature after you load the data via the Geographies component:

<Geographies geography="/geojson-file.json">
  {({ geographies }) =>
    geographies.map((geo) => {
      // You can access `firstProperty` and `secondProperty`
      // via geo.properties.firstProperty and geo.properties.secondProperty

      return <Geography key={geo.rsmKey} geography={geo} />
    })
  }
</Geographies>

Topojson

Topojson is similar to geojson, but instead of encoding geometries individually for each shape, topojson files stitch together geometries from shared line segments. What this means is that if a map file contains two shapes that share a border, this border will only be stored once. The result is that map files with many complex borders can be stored more efficiently, and therefore result in smaller files. These files are transformed client-side into geojson and then used to render shapes in SVG.

A typical topojson file will have the following structure:

{
  "type": "Topology",
  "arcs": [...],
  "objects": {
    "custom_object_name": {
      "type": "GeometryCollection",
      "geometries": [
        {
          "arcs": [...],
          "type": "Polygon",
          "properties": {
            "firstProperty": "Something",
            "secondProperty": "Something else"
          }
        },
        {
          "arcs": [...],
          "type": "Polygon",
          "properties": {...}
        }
      ]
    }
  }
}

Each geometry within the geometries array contains an arcs reference to a set of arcs stored in the global arcs array. Arcs can be shared across different geometries. The above topojson would be treated the same way by react-simple-maps as the geojson example. The resulting code would look like this:

<Geographies geography="/topojson-file.json">
  {({ geographies }) =>
    geographies.map((geo) => {
      // You can access `firstProperty` and `secondProperty`
      // via geo.properties.firstProperty and geo.properties.secondProperty

      return <Geography key={geo.rsmKey} geography={geo} />
    })
  }
</Geographies>

Shapefiles

Shapefiles are very common and can be transformed into usable geojson/topojson using a tool like mapshaper, or other command-line tools. A shapefile consists of a set of files (usually an .shp, .dbf, and .shx file).

You cannot use shapefiles directly with react-simple-maps. To learn how to properly convert a shapefile to usable geojson/topojson, you can follow the tutorial on How to convert and prepare TopoJSON files for interactive mapping with d3.