Get started with Leaflet

Use zarr-maps-leaflet to display a multidimensional Zarr dataset as a Leaflet GridLayer.

Installation

npm install zarr-maps-leaflet leaflet

Create a layer

Your page needs a map container with a defined height. After creating the Leaflet map, construct the Zarr layer, wait for its metadata to load, and add it to the map.

import L from 'leaflet';
import 'leaflet/dist/leaflet.css';
import { ZarrLayer } from 'zarr-maps-leaflet';

const map = L.map('map', {
  center: [36.1, -5.4],
  zoom: 6
});

L.tileLayer('https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png', {
  attribution: '© OpenStreetMap contributors'
}).addTo(map);

const layer = new ZarrLayer({
  id: 'salinity',
  url: 'https://example.com/data.zarr',
  variable: 'salinity',
  colormap: 'viridis',
  scale: [30, 40]
});

await layer.load();
layer.addTo(map);

Calling load() opens the dataset, reads its metadata and dimensions, detects its coordinate reference system, and prepares it for tile requests. Leaflet then requests visible tiles as the map moves or zooms.

Select a multidimensional slice

Use selectors to choose values for non-spatial dimensions such as time or elevation. A selector may refer to an array index or to the nearest coordinate value.

const layer = new ZarrLayer({
  id: 'temperature',
  url: 'https://example.com/temperature.zarr',
  variable: 'temperature',
  selectors: {
    time: { type: 'index', selected: 0 },
    elevation: { type: 'value', selected: 50 }
  }
});

Update the visible slice or styling after the layer has loaded:

layer.updateSelectors({
  time: { type: 'index', selected: 5 }
});

layer.updateStyle({
  colormap: 'plasma',
  scale: [20, 35],
  opacity: 0.7
});

Custom stores and private data

Instead of url, pass a store implementing Zarrita's Readable interface. This supports Icechunk and other storage backends without bundling their clients with Zarr-maps.

The Icechunk and private Zarr integrations were directly inspired by CarbonPlan's zarr-layer implementation.

For private HTTP datasets, use requestOverrides for static fetch options or transformRequest for credentials that must be calculated for each object:

const layer = new ZarrLayer({
  id: 'private-temperature',
  url: 'https://data.example.com/temperature.zarr',
  variable: 'temperature',
  transformRequest: async url => ({
    url,
    credentials: 'include',
    headers: { Authorization: `Bearer ${await getAccessToken()}` }
  }),
  onAuthError: status => refreshSession(status)
});

Query the data

The Leaflet layer exposes the query methods of its ZarrTileProvider:

const position: [number, number] = [-5.4, 36.1];

const point = await layer.queryData({ type: 'Point', coordinates: position });
const timeSeries = await layer.getTimeSeries(position);
const profile = await layer.getVerticalProfile(position);
const transect = await layer.getTransect([-6, 36], [-4, 37], {}, { samples: 100 });

Queries do not change the slice displayed on the map. See the LeafletLayerOptions API for all configuration options.