zarr-gl

Custom WebGL Zarr layer for Mapbox and Maplibre.

This library allows you to load Zarr data into a Mapbox GL JS or Maplibre GL JS map.

Takes inspiration from carbonplan/maps, but with two differences:

1. A library, rather than a framework, so you can use it how you like.
2. Adds a Custom Layer to Mapbox's GL context, rather than creating a whole separate one. Allows you to mix and match with Map styles, adjust layer ordering etc.

You can see a demo at: rainy.rdrn.me.

Quickstart

npm install zarr-gl

You'll need to prepare the data using carbonplan/ndpyramid. Hoping to make that unnecessary at least for use-cases where a narrow zoom-range works. There's a basic data preparation example at example/prep.py.

import { ZarrLayer } from "zarr-gl";
// or skip the npm install and just do this:
// import { ZarrLayer } from "https://cdn.jsdelivr.net/npm/zarr-gl@0.2.0/+esm";

const map = new mapboxgl.Map({
  container: "map",
  style: "mapbox://styles/mapbox/standard",
  projection: "mercator",
});

const layer = new ZarrLayer({
  id: "myZarrLayer",
  source: "https://example.com/path/to/my.zarr",
  variable: "precip",
  selector: { time: "2026-04-05" },
  colormap: [[200, 10, 50], [30, 40, 30], [50, 10, 200]],
  vmin: 0,
  vmax: 100,
  opacity: 0.8,
  map,
});
map.addLayer(layer);

Roadmap

• Support a selector option to index into additional dimensions. Currently only 2D datasets are supported.
• Reproject from lon/lat to EPSG:3857 on the fly
• Handle chunk sizes other than 128x128.
• Appropriately handle non-float32 data.
• Add more lifecycle events.

Examples

1. There is a very basic example (including data prep) in the example directory.
2. There's also a more complex React app inside demo and viewable at rainy.rdrn.me.

Multidimensional Datasets

zarr-gl can render a single 2D slice selected from a multidimensional array, for example time, y, x or time, band, y, x.

• Use selector to choose exactly one coordinate for every non-spatial dimension that should be fixed.
• Spatial dimensions can be named x/y, lon/lat, or longitude/latitude.
• Coordinate selectors may be numbers or strings, for example { time: "2026-04-05" }.
• If a non-spatial dimension has length greater than one and you omit it from selector, zarr-gl will now throw an explicit error.

This means ERA5-style data can work well when prepared as a pyramid where each rendered layer is a single variable plus one selected time slice.

Contributing

I'd love input on use-cases, ideas, missing features etc. Even better if they come with code.

See CONTRIBUTING.md for details on how to contribute.

Testing Pull Requests

When you open a pull request, a preview build is automatically created and deployed. A Github action will autmatically provide the link and the code snippet to use in a comment on the PR.