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>
  );
}

React Controlled

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';

const TIME_RANGE: [number, number] = [0, 10];

function App() {
  const [time, setTime] = useState(TIME_RANGE[0]);
  const [playing, setPlaying] = useState(false);

  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={TIME_RANGE}
        step={1}
        playInterval={250}
        time={time}
        onTimeChange={setTime}
        playing={playing}
        onPlayingChange={(next) => {
          // In controlled mode, the app handles restart-from-beginning
          if (next && time >= TIME_RANGE[1]) {
            setTime(TIME_RANGE[0]);
          }
          setPlaying(next);
        }}
      />
    </DeckGL>
  );
}

Constructor

import {_TimelineWidget as TimelineWidget, type TimelineWidgetProps} from '@deck.gl/widgets';
new TimelineWidget({} satisfies TimelineWidgetProps);

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 for uncontrolled usage.

time (number, optional)

Controlled time value. When provided, the widget is in controlled mode for the time slider and will not update its internal time — the app is the sole source of truth. Use with onTimeChange to handle updates.

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 when the widget is added. In controlled mode, this calls onPlayingChange(true) instead of starting playback directly, allowing the app to decide how to respond.

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.

playing (boolean, optional)

Controlled playing state. When provided, the widget is in controlled mode for play/pause and will not start or stop playback on its own — the app is the sole source of truth. Use with onPlayingChange to handle updates.

In controlled mode, the widget does not automatically reset time to the beginning when playback starts at the end of the range. The app is responsible for handling this in its onPlayingChange callback (see the React Controlled example above).

onPlayingChange (Function, optional)

(playing: boolean) => void

• Default: () => {}

Callback when play/pause button is clicked.

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