TimelineWidget (Experimental)

This widget provides a time slider with play/pause controls. Configure a time range, step interval, and play speed to animate data over time.

JavaScript

import {Deck} from '@deck.gl/core';
import {ScatterplotLayer} from '@deck.gl/layers';
import {_TimelineWidget as TimelineWidget} from '@deck.gl/widgets';
import '@deck.gl/widgets/stylesheet.css';

let time = 0;

const renderLayer = currentTime =>
  new ScatterplotLayer({
    id: 'point',
    data: [{position: [0, 0]}],
    getPosition: d => d.position,
    getRadius: 1000 + currentTime * 200,
    getFillColor: [200, 0, 80]
  });

const deck = new Deck({
  layers: [renderLayer(time)],
  widgets: [
    new TimelineWidget({
      timeRange: [0, 10],
      step: 1,
      playInterval: 250,
      autoPlay: true,
      onTimeChange: value => {
        time = value;
        deck.setProps({layers: [renderLayer(time)]});
      }
    })
  ]
});

TypeScript

import {Deck} from '@deck.gl/core';
import {ScatterplotLayer} from '@deck.gl/layers';
import {_TimelineWidget as TimelineWidget} from '@deck.gl/widgets';
import '@deck.gl/widgets/stylesheet.css';

type Point = {position: [number, number]};

let time = 0;

const renderLayer = (currentTime: number) =>
  new ScatterplotLayer<Point>({
    id: 'point',
    data: [{position: [0, 0]}],
    getPosition: d => d.position,
    getRadius: 1000 + currentTime * 200,
    getFillColor: [200, 0, 80]
  });

const deck = new Deck({
  layers: [renderLayer(time)],
  widgets: [
    new TimelineWidget({
      timeRange: [0, 10],
      step: 1,
      playInterval: 250,
      autoPlay: true,
      onTimeChange: (value: number) => {
        time = value;
        deck.setProps({layers: [renderLayer(time)]});
      }
    })
  ]
});

React

import React, {useState} from 'react';
import DeckGL, {_TimelineWidget as TimelineWidget} from '@deck.gl/react';
import {ScatterplotLayer} from '@deck.gl/layers';
import '@deck.gl/widgets/stylesheet.css';

function App() {
  const [time, setTime] = useState(0);

  return (
    <DeckGL
      layers={[
        new ScatterplotLayer({
          id: 'point',
          data: [{position: [0, 0]}],
          getPosition: d => d.position,
          getRadius: 1000 + time * 200,
          getFillColor: [200, 0, 80]
        })
      ]}
    >
      <TimelineWidget
        timeRange={[0, 10]}
        step={1}
        playInterval={250}
        autoPlay
        onTimeChange={setTime}
      />
    </DeckGL>
  );
}

Installation

npm install deck.gl
# or
npm install @deck.gl/core @deck.gl/layers @deck.gl/widgets @deck.gl/react

import {_TimelineWidget as TimelineWidget, type TimelineWidgetProps} from '@deck.gl/widgets';
import '@deck.gl/widgets/stylesheet.css';

To use pre-bundled scripts:

<script src="https://unpkg.com/deck.gl@^9.0.0/dist.min.js"></script>
<link href="https://unpkg.com/deck.gl@^9.0.0/dist/stylesheet.css" rel='stylesheet' />
<!-- or -->
<script src="https://unpkg.com/@deck.gl/core@^9.0.0/dist.min.js"></script>
<script src="https://unpkg.com/@deck.gl/widgets@^9.0.0/dist.min.js"></script>
<link href="https://unpkg.com/@deck.gl/widgets@^9.0.0/dist/stylesheet.css" rel='stylesheet' />

new deck._TimelineWidget({});

Types

TimelineWidgetProps

The TimelineWidget accepts the generic WidgetProps and:

timeRange ([number, number], optional)

• Default: [0, 100]

Minimum and maximum values for the time slider.

step (number, optional)

• Default: 1

Increment step for the slider and play animation.

initialTime (number, optional)

• Default: timeRange[0]

Starting value of the slider.

onTimeChange (Function, optional)

(value: number) => void

• Default: () => {}

Callback invoked when the time value changes (drag or play).

autoPlay (boolean, optional)

• Default: false

Start playing automatically.

loop (boolean, optional)

• Default: false

Start playing from the beginning when time reaches the end.

playInterval (number, optional)

• Default: 1000

Interval in milliseconds between automatic time increments when playing.

formatLabel (function, optional)

(value: number) => string

Format time value for display.

timeline (Timeline, optional)

A Timeline instance that is manipulated by this widget.

Methods

play

timelineWidget.play();

Start playback.

stop

timelineWidget.stop();

Stop playback.

Styles

The TimelineWidget uses theme CSS variables for RangeInput.

Learn more about how to replace icons in the styling guide.

Name	Type	Default
--icon-play	SVG Data Url	Material Symbol Play Arrow
--icon-pause	SVG Data Url	Material Symbol Pause

Source

modules/widgets/src/timeline-widget.tsx