maplibre-gl-time-slider

A MapLibre GL JS plugin for visualizing time series vector and raster data with an interactive time slider control.

Features

• Interactive time slider with play/pause controls
• Support for both vector and raster time series data
• Built-in TiTiler integration for Cloud Optimized GeoTIFFs (COGs)
• Add Layer button for persisting time periods as permanent layers for comparison
• Customizable playback speed and loop settings
• Control layer ordering with beforeId parameter
• React component and hooks support
• TypeScript support with full type definitions
• Lightweight and easy to integrate

Installation

npm install maplibre-gl-time-slider

Quick Start

Basic Usage (Vanilla JavaScript/TypeScript)

import maplibregl from 'maplibre-gl';
import { TimeSliderControl } from 'maplibre-gl-time-slider';
import 'maplibre-gl-time-slider/style.css';

const map = new maplibregl.Map({
  container: 'map',
  style: 'https://demotiles.maplibre.org/style.json',
  center: [0, 0],
  zoom: 2,
});

map.on('load', () => {
  const timeSlider = new TimeSliderControl({
    title: 'Time Slider',
    labels: ['2024-01', '2024-02', '2024-03', '2024-04'],
    speed: 1000,
    loop: true,
    onChange: (index, label) => {
      console.log(`Current: ${label} (index: ${index})`);
      // Update your map layers here
    },
  });

  map.addControl(timeSlider, 'top-right');
});

React Usage

import { useState, useEffect, useRef } from 'react';
import maplibregl from 'maplibre-gl';
import { TimeSliderControlReact } from 'maplibre-gl-time-slider/react';
import 'maplibre-gl-time-slider/style.css';

function MyMap() {
  const mapContainer = useRef<HTMLDivElement>(null);
  const [map, setMap] = useState<maplibregl.Map | null>(null);

  useEffect(() => {
    if (!mapContainer.current) return;

    const mapInstance = new maplibregl.Map({
      container: mapContainer.current,
      style: 'https://demotiles.maplibre.org/style.json',
      center: [0, 0],
      zoom: 2,
    });

    mapInstance.on('load', () => setMap(mapInstance));

    return () => mapInstance.remove();
  }, []);

  return (
    <>
      <div ref={mapContainer} style={{ width: '100%', height: '100vh' }} />
      {map && (
        <TimeSliderControlReact
          map={map}
          title="Time Slider"
          labels={['2024-01', '2024-02', '2024-03']}
          onChange={(index, label) => {
            // Update map layers
          }}
        />
      )}
    </>
  );
}

Examples

Vector Data (Filtering by Time)

Filter vector features by a time property:

const months = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];

const timeSlider = new TimeSliderControl({
  labels: months,
  onChange: (index, label) => {
    // Filter vector layer by month
    map.setFilter('my-layer', ['==', ['get', 'month'], index]);
  },
});

Raster Data (TiTiler Integration)

Display time series raster data using TiTiler:

import { TimeSliderControl, buildTiTilerTileUrl } from 'maplibre-gl-time-slider';

const rasterData = {
  '2024-01': 'https://example.com/cog_2024_01.tif',
  '2024-02': 'https://example.com/cog_2024_02.tif',
  '2024-03': 'https://example.com/cog_2024_03.tif',
};

const labels = Object.keys(rasterData);
const urls = Object.values(rasterData);

// Add initial raster source
map.addSource('raster-data', {
  type: 'raster',
  tiles: [
    buildTiTilerTileUrl({
      url: urls[0],
      colormap: 'viridis',
    }),
  ],
  tileSize: 256,
});

map.addLayer({
  id: 'raster-layer',
  type: 'raster',
  source: 'raster-data',
});

// Create time slider
const timeSlider = new TimeSliderControl({
  labels: labels,
  onChange: (index, label) => {
    const source = map.getSource('raster-data');
    source.setTiles([
      buildTiTilerTileUrl({
        url: urls[index],
        colormap: 'viridis',
      }),
    ]);
  },
});

Adding Persistent Layers for Comparison

Enable the "Add Layer" button to allow users to persist specific time periods as permanent layers:

let layerCounter = 0;

const timeSlider = new TimeSliderControl({
  labels: ['2020', '2021', '2022', '2023'],
  onChange: (index, label) => {
    // Update the main time slider layer
    const source = map.getSource('main-raster');
    source.setTiles([getTileUrlForYear(label)]);
  },
  onAddLayer: (index, label, beforeId) => {
    // Create a persistent layer for the selected time period
    layerCounter++;
    const sourceId = `persistent-source-${label}`;
    const layerId = `Persistent Layer ${label}`;

    // Add source
    map.addSource(sourceId, {
      type: 'raster',
      tiles: [getTileUrlForYear(label)],
      tileSize: 256,
    });

    // Add layer before the main time slider layer
    map.addLayer({
      id: layerId,
      type: 'raster',
      source: sourceId,
      paint: {
        'raster-opacity': 0.7,
      },
    }, beforeId);

    console.log(`Added persistent layer for ${label}`);
  },
  beforeId: 'main-layer-id', // Insert persistent layers before this layer
});

This feature is useful for:

• Comparing data across multiple time periods
• Creating side-by-side visualizations
• Highlighting specific time periods for analysis
• Building temporal comparisons in the layer control

API Reference

TimeSliderControl

Main control class that implements MapLibre's IControl interface.

Constructor Options

Option	Type	Default	Description
labels	string[]	[]	Array of labels to display (required)
title	string	'Time Slider'	Title displayed in the panel header
collapsed	boolean	true	Whether to start with panel collapsed
position	string	'top-right'	Control position on the map
panelWidth	number	300	Width of the panel in pixels
initialIndex	number	0	Initial index to start at
speed	number	1000	Playback speed in milliseconds
loop	boolean	true	Whether to loop playback
className	string	''	Custom CSS class name
onChange	function	-	Callback when index changes: (index: number, label: string) => void
onAddLayer	function	-	Callback when "Add Layer" button is clicked: (index: number, label: string, beforeId?: string) => void
beforeId	string	-	Layer ID to insert new persistent layers before (ensures proper layer ordering)

Methods

Method	Description
play()	Start playback
pause()	Pause playback
togglePlayback()	Toggle play/pause state
next()	Move to next label
prev()	Move to previous label
goTo(index)	Navigate to specific index
setSpeed(ms)	Set playback speed
setLoop(enabled)	Set loop state
setLabels(labels, resetIndex?)	Update labels
getCurrentIndex()	Get current index
getCurrentLabel()	Get current label
getLabels()	Get all labels
getState()	Get full state object
toggle()	Toggle panel collapsed state
expand()	Expand panel
collapse()	Collapse panel
on(event, handler)	Register event listener
off(event, handler)	Remove event listener

Events

Event	Description
change	Fired when the current index changes
play	Fired when playback starts
pause	Fired when playback pauses
collapse	Fired when panel collapses
expand	Fired when panel expands
statechange	Fired on any state change

TiTiler Utilities

buildTiTilerTileUrl(options)

Builds a TiTiler XYZ tile URL for MapLibre raster sources.

const tileUrl = buildTiTilerTileUrl({
  url: 'https://example.com/my-cog.tif',
  endpoint: 'https://giswqs-titiler-endpoint.hf.space',  // optional, default
  colormap: 'viridis',              // optional, default
  rescale: [-10, 10],               // optional
  bidx: [1],                        // optional, band indexes
});

getTiTilerBounds(url, endpoint?)

Fetches the bounds of a COG file.

const bounds = await getTiTilerBounds('https://example.com/my-cog.tif');
map.fitBounds(bounds);

getTiTilerInfo(url, endpoint?)

Fetches metadata about a COG file.

getTiTilerStatistics(url, endpoint?)

Fetches statistics (min, max, mean, std) for each band.

Development

# Install dependencies
npm install

# Start development server
npm run dev

# Build library
npm run build

# Build examples
npm run build:examples

# Run tests
npm test

# Lint code
npm run lint

# Format code
npm run format

Docker

The examples can be run using Docker. The image is automatically built and published to GitHub Container Registry.

Pull and Run

# Pull the latest image
docker pull ghcr.io/opengeos/maplibre-gl-time-slider:latest

# Run the container
docker run -p 8080:80 ghcr.io/opengeos/maplibre-gl-time-slider:latest

Then open http://localhost:8080/maplibre-gl-time-slider/ in your browser to view the examples.

Build Locally

# Build the image
docker build -t maplibre-gl-time-slider .

# Run the container
docker run -p 8080:80 maplibre-gl-time-slider

Available Tags

Tag	Description
latest	Latest release
x.y.z	Specific version (e.g., 1.0.0)
x.y	Minor version (e.g., 1.0)

License

MIT License - see LICENSE for details.