Bertin.js is a JavaScript library for visualizing geospatial data and make thematic maps for the web.

The project is under active development. Some of features and options are subject to change. We welcome contributions of all kinds: bug reports, code contributions and documentation. A todo list of the next improvements is available here.

Introduction
Who is Bertin?
Installation
Usage
Drawing a map
Map types
Map components
Custom Layer
Geojson properties selections
Other functions
Update function
Bonus: a cheat sheet

bertin is an easy to use JavaScript library mainly based on D3.js makes creating thematic maps simple. The principle is to work with layers stacked on top of one other. Much like in Geographic Information Software (GIS) software, Bertin.js displays layers with a specific hierarchy. The layer at bottom are rendered and then followed by the layer right above it. Some of the layers are used to display various components of a map, some of common layers are: header, footer, graticule, outline, choro, typo, prop, shadow, scalebar, text etc.

The draw() function is the most important function of the library. It allows you to draw all types of maps.
The update() function allows you to modify specific elements of the map without the need to redraw everything. Only the parameters underlined in the documentation can be modified through this function.

Cheat Sheet

Who is Bertin? {#who-is-bertin}

Jacques Bertin (1918-2010) was a French cartographer, whose major contribution was a theoretical and practical reflection on all graphic representations (diagrams, maps and graphs), forming the subject of a fundamental treatise, Graphic Semiology, originally published in 1967. Bertin's influence remains strong not only in academics, teaching of cartography today, but also among statisticians and data visualization specialists.

Installation {#installation}

In browser

Latest version

<script
  src="https://cdn.jsdelivr.net/npm/bertin"
  charset="utf-8"
></script>

Pinned version

<script src="https://cdn.jsdelivr.net/npm/bertin@1.7" charset="utf-8"></script>

In Observable

Latest version

bertin = require("bertin");

Pinned version

bertin = require("bertin@1.7");

In Quarto

In Quarto, you can use bertin with ojs cells. This allows to combine analyses in R or Python with visualizations made with bertin. An example is available here

Usage {#usage}

In browser

<script src="https://cdn.jsdelivr.net/npm/d3@7"></script>
<script src="https://cdn.jsdelivr.net/npm/bertin"></script>

<script>
  let geojson =
    "https://raw.githubusercontent.com/neocarto/bertin/main/data/world.geojson";

  d3.json(geojson).then((r) =>
    document.body.appendChild(
      bertin.draw({
        params: {
          projection: "VanDerGrinten4",
          clip: true,
        },
        layers: [
          { geojson: r, tooltip: ["$ISO3", "$NAMEen"] },
          { type: "outline" },
          { type: "graticule" },
        ],
      })
    )
  );
</script>

See examples: Example 1, Example 2 and Example 3.

In Observable Notebook

The bertin.js library is really easy to use within an Observable notebook. You'll find many examples in this notebook collection. Feel free to fork, copy, modify with your own data.

Drawing a map {#drawing-a-map}

draw() is the main function of the library. It allows you to make various thematic maps. It allows to display and overlay different types of layers listed below. The layers written on top are displayed first. Source Example

Global parameters

In the section params, we define the global parameters of the map: its size, projection, background color, etc. To have access to a large number of projections, you will need to load the d3-geo-projection@4 library. This section is optional.