Time Matrix Filter

Use the time matrix for activity schedules, support coverage, usage windows, or any timestamp question expressed as weekday plus hour. Users can select individual cells or start from Business hours, Weekends, and Nights presets.

Source code

TypeScriptts

grid.plugins = [AdvanceFilterPlugin];
grid.columns = [
  { prop: 'activity', name: 'Activity' },
  {
    prop: 'occurredAt',
    name: 'Activity time',
    filter: ['datetime', FILTER_TIME_MATRIX],
    size: 210,
  },
];
grid.filter = { date: { timezoneMode: 'utc' } };

return [
  { activity: 'Monday opening', occurredAt: '2026-08-24T08:15:00Z' },
  { activity: 'Tuesday afternoon', occurredAt: '2026-08-25T15:30:00Z' },
  { activity: 'Friday evening', occurredAt: '2026-08-28T19:45:00Z' },
  { activity: 'Saturday morning', occurredAt: '2026-08-29T10:00:00Z' },
  { activity: 'Monday night', occurredAt: '2026-08-31T22:00:00Z' },
];

Quick start

import {
  AdvanceFilterPlugin,
  FILTER_TIME_MATRIX,
} from '@revolist/revogrid-pro';
import '@revolist/revogrid-pro/dist/revogrid-pro.css';

grid.plugins = [AdvanceFilterPlugin];
grid.columns = [
  {
    prop: 'occurredAt',
    name: 'Activity time',
    filter: ['datetime', FILTER_TIME_MATRIX],
  },
];
grid.source = [
  { occurredAt: '2026-08-24T09:30:00Z' },
  { occurredAt: '2026-08-25T22:15:00Z' },
];
grid.filter = true;

Row values must resolve to instants (Date, an ISO timestamp, or a numeric timestamp). The filter converts each instant to weekday and hour in the condition’s timezone.

Operator and saved state

• Structured type: FILTER_TIME_MATRIX ('timeMatrix')
• Operator: TIME_MATRIX_OPERATOR ('timeMatrix')
• Value: { version: 1, timeZone, ranges }

Each range uses Sunday-based weekday (0 is Sunday), an inclusive startHour, and an exclusive endHour.

grid.filter = {
  multiFilterItems: {
    occurredAt: [
      {
        id: 1,
        type: 'timeMatrix',
        value: {
          version: 1,
          timeZone: 'Europe/Lisbon',
          ranges: [
            { weekday: 1, startHour: 9, endHour: 17 },
            { weekday: 2, startHour: 9, endHour: 17 },
          ],
        },
        relation: 'and',
      },
    ],
  },
};

Use that JSON-safe value for programmatic restore. Adjacent selected hours are compacted into ranges. Selecting no cells or every hour of every day removes the no-op condition.

Configure schedule presentation

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

const activityTime = createTimeMatrixStructuredFilterType({
  timeZone: 'Europe/Lisbon',
  locale: 'en-GB',
  weekStartsOn: 1,
  useAmPm: false,
  // Context shading in the matrix.
  workingHours: { startHour: 8, endHour: 18 },
  weekendDays: [5, 6],
  // Shortcut buttons are configured independently.
  presets: {
    businessHours: {
      days: [1, 2, 3, 4],
      startHour: 9,
      endHour: 17,
      label: 'Core hours',
      description: 'Monday–Thursday, 09:00–17:00',
    },
    weekends: {}, // Inherits weekendDays ([5, 6]).
    nights: {
      days: [0, 1, 2, 3, 4, 5, 6],
      startHour: 20,
      endHour: 6, // An end before the start creates an overnight window.
    },
  },
});

grid.filter = defineAdvancedFilterConfig({
  structuredFilterTypes: [activityTime],
});

workingHours and weekendDays shade schedule context; selected cells alone determine filtering. Defaults are 06:00–22:00 and Sunday/Saturday. If timeZone or weekStartsOn is omitted, it inherits the column’s resolved date-filter settings.

The built-in shortcut defaults remain Business hours (Monday–Friday, 08:00–20:00), Weekends (the configured weekendDays, all day), and Nights (every day, 22:00–06:00).

Option	Purpose
workingHours	Start/end boundaries for outside-working-hours shading.
weekendDays	Sunday-based days used for weekend shading and, by default, the Weekends shortcut.
workingHours: false	Disable outside-working-hours shading and remove that legend item.
weekendDays: []	Disable weekend shading and remove that legend item.
showLegend: false	Hide the complete schedule-context legend.
presets.businessHours	Configure days, startHour, endHour, label, and description, or use false to hide it.
presets.weekends	Configure days, label, and description, or use false to hide it. An empty object inherits weekendDays.
presets.nights	Configure days, an overnight-capable hour window, label, and description, or use false to hide it.
presets: false	Hide the complete shortcut row while retaining direct matrix selection.

All days use Sunday-based numbering (0–6), and all hour boundaries are whole hours (0–24). A preset window whose endHour is earlier than startHour wraps across midnight. Invalid days or hour windows fall back to that preset’s defaults.

For example, keep Business hours and hide the other shortcuts:

const activityTime = createTimeMatrixStructuredFilterType({
  presets: {
    weekends: false,
    nights: false,
  },
});

Localization

TIME_MATRIX_LOCALIZATION exports the complete English fallback and stable keys. Override the operator through filterNames and authored UI/accessibility text through captions.

grid.filter = defineAdvancedFilterConfig({
  structuredFilterTypes: [activityTime],
  localization: {
    filterNames: {
      timeMatrix: 'Matches schedule',
    },
    captions: {
      timeMatrixTitle: 'Coverage schedule',
      timeMatrixDescription: 'Select included weekday and hour combinations.',
      timeMatrixClear: 'Clear schedule',
      'timeMatrixPreset.businessHours': 'Office hours',
      'timeMatrixPresetDescription.businessHours':
        'Monday–Friday office coverage',
    },
  },
});

Other stable captions cover the grid and legend, selected/unselected cell states, summaries, and all preset labels/descriptions. Per-instance label and description values on a preset take precedence over localization captions. Dynamic messages use named placeholders including {day}, {start}, {end}, {state}, {hours}, {days}, and {timeZone}. Weekday and clock text comes from locale and useAmPm, not fixed translated strings.

Common mistakes

• Do not store local clock text such as '09:30'; the predicate needs an instant.
• Do not treat endHour as inclusive. { startHour: 9, endHour: 17 } covers 09:00 through 16:59.
• Do not use locale weekday numbering in saved state; persisted weekday is always Sunday-based.
• Do not expect workingHours or weekendDays shading to add selected cells. Configure shortcut selections through presets.
• Use a valid IANA timezone. Invalid timeZone configuration throws.

Related guides

• Structured Filter Types
• Date and Datetime Filters
• Canonical Filter AST
• Custom and Remote Structured Filters