This repo has been superceded by one at oi.hexmap.js. Please update your links.

Hexmap Library

odi.hexmap.js (20kB; 12kB minified; 5kB minified+gzipped) is our small, standalone, Javascript library for making interactive hexmaps (cartograms). There are some examples below.

This library assumes you have an existing hex layout as HexJSON (e.g. layouts we've made) and the ability to add Javascript to a webpage. The library creates an SVG (scalable vector graphic) of hexes - which can be styled via CSS - and some basic event callbacks.

A basic hexmap

Let's create a very basic hex map using a HexJSON layout. Everything happens in ODI.hexmap(el,attributes) where el is the DOM element we are attaching the hex map to and attributes defines properties of the hex map. At a minimum, attributes should include hexjson which can either be inline HexJSON or a path to an external HexJSON file. In this example we will add the HexJSON inline.

By default, the title of each hex (try hovering over them) uses the n or name property of the hex in the HexJSON.

Styling hexes and labels

We will use the same hexmap but this time we add some extra properties to each item in the HexJSON. The colour property is used to colour each hex. We also turn on labels, make sure they are clipped to the hexagon, and customise the text of the label. The default label text is the value of n but we can provide a format function to customise the content. Here we split the string into separate tspan elements and add the population value. We make use of CSS classes so that we can make some parts of the label only visible on hover and even scale the size of the hexagon on hover (the code adds the style .hover to the hexagon and label).

Cartogram showing Leeds wards with coloured assigned manually.

Using external data and adding tooltips

This example loads in an external HexJSON file, loads in some data, and then colours the hexes depending on the data. To work out the colours we'll make a little helper function ColourScale.

Cartogram showing UK constituencies coloured by the number of signatures they received on House of Commons petitions during 2017-2019. Data from The House of Commons Library. Layout by ODI Leeds and contributors.