Skip to content
RevoGrid [Pro]

Timeline Brush Filter

Use the timeline brush when users need to see where date or datetime values are concentrated before choosing a range. It bins parsed column values by day, week, or month and keeps the committed condition independent from the chart UI.

Source code
TypeScriptts
grid.plugins = [AdvanceFilterPlugin];
grid.columns = [
  {
    prop: 'occurredAt',
    name: 'Occurred at',
    filter: ['datetime', FILTER_TIMELINE_BRUSH],
    size: 240,
  },
];
grid.filter = { date: { timezoneMode: 'utc' } };

return [
  { occurredAt: '2026-08-03T08:00:00Z' },
  { occurredAt: '2026-08-04T14:30:00Z' },
  { occurredAt: '2026-08-07T18:15:00Z' },
  { occurredAt: '2026-08-10T09:45:00Z' },
  { occurredAt: '2026-08-11T16:20:00Z' },
  { occurredAt: '2026-08-14T12:00:00Z' },
  { occurredAt: '2026-08-17T21:10:00Z' },
  { occurredAt: '2026-08-18T07:25:00Z' },
  { occurredAt: '2026-08-21T15:40:00Z' },
  { occurredAt: '2026-08-24T11:05:00Z' },
];

Quick start

Section titled “Quick start”
import {
  AdvanceFilterPlugin,
  FILTER_TIMELINE_BRUSH,
} from '@revolist/revogrid-pro';
import '@revolist/revogrid-pro/dist/revogrid-pro.css';


grid.plugins = [AdvanceFilterPlugin];
grid.columns = [
  {
    prop: 'createdAt',
    name: 'Created',
    filter: ['datetime', FILTER_TIMELINE_BRUSH],
  },
];
grid.source = [
  { createdAt: '2026-08-20T09:30:00Z' },
  { createdAt: '2026-08-24T16:15:00Z' },
];
grid.filter = true;

Use 'date' instead of 'datetime' for ISO date-only values such as 2026-08-20. Selecting the complete displayed domain is a no-op and removes the timeline condition.

Operator and saved state

Section titled “Operator and saved state”
  • Structured type: FILTER_TIMELINE_BRUSH ('timelineBrush')
  • Operator: TIMELINE_BETWEEN ('timelineBetween')
  • Value: { from, to, inclusive: true }

Date columns store inclusive ISO dates. Datetime columns store inclusive ISO instants.

grid.filter = {
  multiFilterItems: {
    createdAt: [
      {
        id: 1,
        type: 'timelineBetween',
        value: {
          from: '2026-08-20T00:00:00.000Z',
          to: '2026-08-24T23:59:59.999Z',
          inclusive: true,
        },
        relation: 'and',
      },
    ],
  },
};

This is also the programmatic restore shape. Keep the operator ID in type; the structured type ID belongs in the column definition.

Configure the timeline

Section titled “Configure the timeline”

Replace the built-in registration with a configured instance. The stable ID stays the same, so every column using FILTER_TIMELINE_BRUSH receives these options.

import {
  createTimelineBrushStructuredFilterType,
  defineAdvancedFilterConfig,
} from '@revolist/revogrid-pro';


const timeline = createTimelineBrushStructuredFilterType({
  granularity: 'week', // 'day' | 'week' | 'month'
  binCap: 48,
  timeZone: 'Europe/Lisbon',
  locale: 'en-GB',
  format: { day: '2-digit', month: 'short', year: 'numeric' },
  chart: {
    type: 'area', // 'bar' | 'line' | 'area'; default is 'bar'
    height: 72,
    showPoints: true,
    formatTooltip: (bin, { fromLabel, toLabel, selected }) => ({
      title: fromLabel === toLabel ? fromLabel : `${fromLabel} – ${toLabel}`,
      details: [`${bin.count} events`, selected ? 'Selected' : 'Outside selection'],
    }),
  },
});


grid.filter = defineAdvancedFilterConfig({
  structuredFilterTypes: [timeline],
  date: { weekStartsOn: 1 },
});

timeZone and weekStartsOn inherit the column’s resolved filter.date settings when the factory does not override them. Dense spans are deterministically coarsened to stay within binCap.

The chart is a reusable presentation control; the dual-range slider remains independent. Its default tooltips are keyboard reachable and localize through timelineBrushChart, timelineBrushItem, timelineBrushItems, timelineBrushSelected, and timelineBrushOutsideSelection captions. Use formatTooltip for domain-specific rows or terminology.

For a partially loaded remote source, provide complete temporal aggregates or exported TimelineBrushPreparedData; otherwise the distribution can only describe rows loaded in the browser.

Common mistakes

Section titled “Common mistakes”
  • Do not restore type: 'timelineBrush'; conditions use type: 'timelineBetween'.
  • Do not mix date-only and datetime values in one column. Declare the base family explicitly.
  • Do not pass display-formatted dates unless a cellParser converts them into valid date or instant values.
  • Do not expect a full-domain selection to remain in state; it intentionally clears the no-op condition.
  • For remote pagination, do not present page-local bins as the complete dataset distribution.
Section titled “Related guides”