Skip to content
D3plus

Timeline

Creates an interactive timeline brush component for selecting time periods within a visualization.

Basic example

Section titled “Basic example”

With brushing: false, the timeline selects a single period across the domain; enabling playButton adds controls to step through the periods automatically.

const config = {
  align: "start",
  brushing: false,
  domain: [2012, 2020],
  height: 100,
  playButton: true,
  width: 400,
};

Range selection

Section titled “Range selection”

With brushing: true, viewers can drag to select a time range instead of a single period.

const config = {
  domain: [2000, 2020],
  brushing: true,
  height: 100,
  width: 520,
};

Tick format

Section titled “Tick format”

The timeline is an Axis, so ticks chooses which periods get a mark and tickFormat rewrites their labels; abbreviating the years keeps a long range readable at a narrow width.

const config = {
  domain: [2000, 2020],
  height: 100,
  tickFormat: d =>
    `'${String(d instanceof Date ? d.getFullYear() : d).slice(-2)}`,
  ticks: [2000, 2004, 2008, 2012, 2016, 2020],
  width: 520,
};

Initial selection

Section titled “Initial selection”

selection sets the range (or single period) that is highlighted before the viewer touches anything, and snapping: false lets the brush handles rest between ticks instead of jumping to the nearest period.

const config = {
  brushing: true,
  domain: [2000, 2020],
  height: 100,
  selection: [2008, 2012],
  snapping: false,
  width: 520,
};

Limiting the selection

Section titled “Limiting the selection”

brushMax caps how many ticks a selection can span. Drag across more and the brush is pulled in on release, keeping the end you dragged; a wider starting selection keeps its latest periods. brushMin sets the fewest the same way, with ticks or buttons: a narrower brush widens, and a click selects that many periods from the one clicked. On a chart, pass both through timelineConfig. When brushMin is larger, brushMin wins.

const config = {
  brushMax: 3,
  brushing: true,
  buttonBehavior: "ticks",
  domain: [2010, 2021],
  height: 100,
  selection: [2010, 2021],
  ticks: [
    2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019, 2020, 2021,
  ],
  width: 520,
};

Configuration

import {Timeline} from "@d3plus/core";

Extends Axis → BaseClass.

barConfigrecord

Axis line style.

baselineBreakConfigrecord

Style of the break drawn when baselineBreak is on and the domain stops short of baseline: space (pixels of axis between the baseline tick and the first tick after the break), gap (pixels between the two break marks, where the axis line is not drawn), size (length of each mark, drawn outward from the axis line on the tick side so it never reaches into the plot), angle (degrees each mark tilts from perpendicular), lines and lineConfig (the lines a Plot runs across the plot from each mark, as in breakConfig), mask (whether a Plot cuts the gap between those lines across the shapes, default true), plus stroke/stroke-width and other line styles for the marks.

breakConfigrecord

Style of the breaks set with break: space (pixels of axis each break occupies), gap (pixels between its two marks, where the axis line is not drawn), size (length of each mark, drawn outward from the axis line on the tick side so it never reaches into the plot), angle (degrees each mark tilts from perpendicular), lines (whether a Plot runs a line across the plot from each mark, default true), lineConfig (those lines' style — stroke, stroke-width, … — over the axis line's barConfig style), mask (whether a Plot cuts the gap between the lines across the shapes, default true), plus stroke/stroke-width and other line styles for the marks.

classNamestring | array.<string> | undefined

CSS classes added to the outermost element this chart or component draws into, next to its fixed d3plus classes, so page CSS can target it: a chart's root <svg class="d3plus-viz"> (its <canvas> with the Canvas renderer) and a standalone component's <svg>. Takes a space-separated string or an array. A new value replaces the classes the previous one added; unset adds none. Tooltips take their own tooltipConfig.className.

colorDefaultscolordefaultsconfig

Overrides the default colors used when assigning fills from data and choosing legible text colors: dark and light (the text colors picked for contrast against a background), missing (null/undefined values), on/off (true/false values), sequential (the anchor hue for magnitude ramps), and scale (the categorical palette, given as a d3 ordinal scale or an array of colors). Keys are merged into the current defaults, and a Viz passes its overrides down to the shapes and components it draws.

configd3plusconfig

Methods that correspond to the key/value pairs and returns this class.

dataarray.&lt;unknown&gt;

An array of data points, which helps determine which ticks should be shown and which time resolution should be displayed.

gridConfigrecord

Grid config of the axis.

handleConfigrecord

Handle style.

labelRotationnumber | boolean | undefined

Whether to rotate the axis labels, and by how much. true rotates them -90 degrees and false keeps them flat. Left undefined (the default), a horizontal axis of categories rotates its labels when any label would not fit its share of the axis whole (a word dropped, cut off, or broken across lines) or would overlap its neighbor: they slant 30 degrees (-30 on a bottom axis, 30 on a top one), or stand at -90 when even slanted they would leave more labels cut short or hidden. A vertical axis never rotates its labels on its own. A number rotates them by that many degrees (clockwise, so -45 rises to the right): each label hangs off the axis from the end of its text nearest the axis, which sits across from its tick, so on a bottom axis a negative angle ends each label at its tick and a positive one starts it there. Angles outside -90 to 90 turn a half turn to read left to right (135 draws as -45), and 0 keeps the labels flat. Slanted labels wrap between words onto up to three lines, as many as fit between neighboring labels, so they reach less far from the axis. Labels that still overlap once rotated are thinned evenly.

localestring | object

The locale used for all text and number formatting. Supports the locales defined in d3plus-format. The locale can be a complex Object, a locale code (like "en-US"), or a 2-digit language code (like "en"). If a 2-digit code is provided, the "findLocale" function is used to identify the most approximate locale.

onstring

Event listener for the specified brush event typename. Mirrors the core d3-brush behavior.

orientstringDefault bottom

The orientation of the shape.

parentunknown

Parent config used by the wrapper.

playButtonConfigrecord

The config Object for the Rect class used to create the playButton.

renderfunction

Draws the timeline.

selectstring | htmlelement | null | undefined

The SVG container element as a d3 selector or DOM element.

Passing null or undefined deliberately leaves the axis unmounted — renderMode("compute") plus select(null) produces a scene-only axis (no detached SVG fallback). This is the formal contract callers in plotPaint use to compute axis layout without mounting DOM.

selectionConfigrecord

Selection style.

shapeConfigrecord

Tick style of the axis.

titleConfigrecord

Title configuration of the axis.

translatefunction

Defines how informational text strings should be displayed. By default, this function will try to find the string in question (which is the first argument provided to this function) inside of an internally managed translation Object. If you'd like to override to use custom text, simply pass this method your own custom formatting function.