# How to Implement the Time Slider Plugin for Temporal Geospatial Data in GeoLibre

> Implement the GeoLibre Time Slider plugin to interactively explore temporal geospatial data. Scrub Zarr or NetCDF time series seamlessly without rebuilding map layers.

- Repository: [Open Geospatial Solutions/GeoLibre](https://github.com/opengeos/GeoLibre)
- Tags: how-to-guide
- Published: 2026-08-02

---

**The GeoLibre Time Slider plugin enables interactive exploration of temporal datasets by binding a UI dock directly to a layer's time dimension, allowing users to scrub through Zarr or NetCDF time series without rebuilding map layers.**

The opengeos/GeoLibre framework provides a built-in Time Slider plugin specifically designed for visualizing temporal geospatial data. This plugin integrates with multi-dimensional Zarr datasets and time-enabled NetCDF files, exposing a UI dock that drives a layer's *time* property directly. By implementing this plugin according to the core architecture, developers enable end-users to explore time slices interactively while the underlying DuckDB-WASM engine queries temporal data via `ST_Read`.

## How the Time Slider Plugin Works

The plugin operates through a unidirectional data flow that keeps the map renderer synchronized with the temporal state. When a user moves the slider, the system updates the core store, which triggers the MapLibre renderer to fetch and display the appropriate time slice without reconstructing the layer object.

### Core Components

- **Zarr Layer** (`addZarrLayer`): Loads multi-dimensional datasets and exposes a `time` dimension that the slider manipulates.
- **Time Slider Plugin** ([`packages/plugins/src/plugins/maplibre-time-slider.ts`](https://github.com/opengeos/GeoLibre/blob/main/packages/plugins/src/plugins/maplibre-time-slider.ts)): Registers the `<TimeSliderDock>` UI component and dispatches `{ time: n }` updates to active layers.
- **Plugin Registry** ([`packages/plugins/src/viewer-plugins.ts`](https://github.com/opengeos/GeoLibre/blob/main/packages/plugins/src/viewer-plugins.ts)): Declares the plugin as a built-in viewer plugin, making it available in the *Plugins* panel for toggle activation.
- **Core Store** (`@geolibre/core`): Maintains layer state; receives `setLayerTime` calls and notifies renderers of temporal changes.
- **MapLibre Sync** (`@geolibre/map`): Reacts to store changes and invokes DuckDB-WASM to retrieve specific temporal slices.

## Step-by-Step Implementation Guide

Follow these steps to integrate the Time Slider into your GeoLibre application.

### 1. Register the Plugin

Import and register the plugin in your application's plugin hook to make it available in the interface.

```typescript
// apps/geolibre-desktop/src/hooks/usePlugins.ts
import { maplibreTimeSlider } from '@geolibre/plugins';

const plugins = [
  maplibreTimeSlider,
  // other plugins...
];

```

### 2. Load a Temporal Dataset

Use the `addZarrLayer` helper to load data with a time dimension. The function automatically detects temporal dimensions but allows explicit configuration.

```typescript
import { addZarrLayer } from '@geolibre/core';

const layerId = await addZarrLayer({
  url: 'https://example.com/climate-timeseries.zarr',
  temporalDimension: 'time', // Optional: override auto-detection
});

```

This creates a `GeoLibreLayer` instance with a mutable `time` property that the slider controls.

### 3. Activate the Time Slider UI

Open the *Plugins* panel via the gear icon, then enable **Time Slider**. The dock appears on the right side of the map canvas and automatically binds to the active temporal layer.

### 4. Control Time Programmatically

Use `setLayerTime` to jump to specific indices programmatically, bypassing the UI when necessary.

```typescript
import { setLayerTime } from '@geolibre/core';

// Jump to the 42nd time step
await setLayerTime(layerId, 42);

```

### 5. Persist State (Optional)

The current time index is automatically tracked in the project state. Call `saveProject` to write the temporal position to [`.geolibre.json`](https://github.com/opengeos/GeoLibre/blob/main/.geolibre.json).

```typescript
import { saveProject } from '@geolibre/core';

await saveProject(); // Saves current time index with layer configuration

```

## Practical Code Examples

### Toggling the Slider UI in React

Create a button component that toggles the plugin visibility using the `usePluginToggle` hook.

```typescript
import { usePluginToggle } from '@geolibre/ui';
import { maplibreTimeSlider } from '@geolibre/plugins';

export function TimeSliderToggle() {
  const { enabled, toggle } = usePluginToggle(maplibreTimeSlider);
  
  return (
    <button onClick={toggle}>
      {enabled ? 'Hide' : 'Show'} Time Slider
    </button>
  );
}

```

### Programmatic Time Jump from Analysis Tools

Execute temporal navigation from custom processing workflows without user interaction.

```typescript
import { getActiveLayerId, setLayerTime } from '@geolibre/core';

async function runTemporalAnalysis() {
  const layerId = await getActiveLayerId();
  const optimalIndex = await computeBestTimeIndex(); // Custom logic
  
  await setLayerTime(layerId, optimalIndex);
}

```

### Auto-Loading Data with Slider Activation

Automatically open the time slider when adding a temporal layer.

```typescript
import { addZarrLayer, openPlugin } from '@geolibre/core';
import { maplibreTimeSlider } from '@geolibre/plugins';

async function loadAndExplore() {
  const id = await addZarrLayer({ url: '/data/weather.zarr' });
  
  // Automatically open slider dock for the new layer
  await openPlugin(maplibreTimeSlider, { layerId: id });
}

```

## Key Source Files and Implementation Details

The following files define the Time Slider architecture according to the GeoLibre source:

- **[`packages/plugins/src/plugins/maplibre-time-slider.ts`](https://github.com/opengeos/GeoLibre/blob/main/packages/plugins/src/plugins/maplibre-time-slider.ts)**: Implements the UI dock (`<TimeSliderDock>`) and handles the binding between slider events and `setLayerTime` dispatches.
- **[`packages/plugins/src/viewer-plugins.ts`](https://github.com/opengeos/GeoLibre/blob/main/packages/plugins/src/viewer-plugins.ts)**: Declares `maplibreTimeSlider` in the viewer plugin registry, controlling its availability in the *Plugins* panel.
- **[`apps/geolibre-desktop/src/hooks/usePlugins.ts`](https://github.com/opengeos/GeoLibre/blob/main/apps/geolibre-desktop/src/hooks/usePlugins.ts)**: Entry point where built-in plugins are registered for the desktop application.
- **[`docs/plugin-api.md`](https://github.com/opengeos/GeoLibre/blob/main/docs/plugin-api.md)**: Documents the plugin interface and store interaction patterns used by the time slider.
- **[`tests/time-slider-binding.test.ts`](https://github.com/opengeos/GeoLibre/blob/main/tests/time-slider-binding.test.ts)**: Contains test suites verifying slider-layer binding, auto-close behavior, and configuration persistence.
- **[`packages/core/src/layers.ts`](https://github.com/opengeos/GeoLibre/blob/main/packages/core/src/layers.ts)**: Defines the core layer object that holds the `time` property manipulated by the slider.

## Summary

- The **Time Slider plugin** (`maplibreTimeSlider`) provides a UI dock for exploring temporal datasets without layer reconstruction.
- **Temporal data** loads via `addZarrLayer`, which exposes time dimensions for the slider to manipulate.
- **Programmatic control** is available through `setLayerTime`, `getActiveLayerId`, and `openPlugin` functions.
- The architecture uses a **core store** pattern where the slider updates state, triggering DuckDB-WASM queries via the MapLibre sync layer.
- **State persistence** automatically saves the current time index when calling `saveProject`.

## Frequently Asked Questions

### Does the Time Slider plugin support NetCDF files?

Yes, the plugin supports any temporal dataset loaded through GeoLibre's data layer API. While Zarr is the primary format mentioned in the implementation, NetCDF files with time dimensions are supported when loaded via compatible layer helpers that expose a `time` property to the core store.

### Can I control the time slider programmatically without displaying the UI dock?

Yes, you can manipulate temporal state directly using `setLayerTime` from `@geolibre/core`. This updates the layer's time index and triggers a re-render without requiring the `<TimeSliderDock>` component to be mounted or visible.

### How does the plugin handle large temporal datasets with thousands of time steps?

The plugin delegates temporal slicing to the DuckDB-WASM engine using `ST_Read`, which performs efficient columnar queries on the source data. Only the active time slice is fetched and rendered, keeping memory usage constant regardless of the total temporal extent.

### Where is the current time index stored when saving a project?

The current time index is stored as part of the layer state in the project JSON ([`.geolibre.json`](https://github.com/opengeos/GeoLibre/blob/main/.geolibre.json)). When you call `saveProject`, the core store serializes the `time` property of each layer, allowing projects to reopen at the exact temporal position where they were saved.