Date range filter

Use the calendar range for booking periods, reporting windows, delivery dates, and other workflows where users choose a fixed start and end day. It shares RevoGrid Pro’s calendar navigation, range preview, keyboard focus, disabled-date behavior, and accessibility semantics.

Source code

TypeScriptts

grid.plugins = [AdvanceFilterPlugin];
grid.columns = [
  {
    prop: 'deliveryDate',
    name: 'Delivery date',
    filter: ['date', FILTER_CALENDAR_RANGE],
  },
];
grid.filter = true;

return [
  { deliveryDate: '2026-09-02' },
  { deliveryDate: '2026-09-03' },
  { deliveryDate: '2026-09-05' },
  { deliveryDate: '2026-09-06' },
];

Quick start

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

defineCustomElements();

const grid = document.createElement('revo-grid');
grid.plugins = [AdvanceFilterPlugin];
grid.columns = [
  { prop: 'order', name: 'Order' },
  {
    prop: 'deliveryDate',
    name: 'Delivery',
    filter: ['date', FILTER_CALENDAR_RANGE],
  },
];
grid.filter = true;
document.querySelector('#app')!.append(grid);
grid.source = [
  { order: 'A-100', deliveryDate: '2026-09-02' },
  { order: 'A-101', deliveryDate: '2026-09-14' },
  { order: 'A-102', deliveryDate: '2026-10-01' },
];

Operator and state

• Type ID: FILTER_CALENDAR_RANGE ('calendarRange')
• Operator ID: CALENDAR_RANGE_BETWEEN ('calendarRangeBetween')
• Value: inclusive ISO date-only bounds { from, to, inclusive: true }

Both dates use YYYY-MM-DD. Partial or invalid ranges are not committed. The lower bound must not be after the upper bound in restored state; the interactive editor normalizes a reversed selection.

Restore a range programmatically

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

grid.filter = defineAdvancedFilterConfig({
  multiFilterItems: {
    deliveryDate: [
      {
        id: 1,
        type: CALENDAR_RANGE_BETWEEN,
        value: { from: '2026-09-01', to: '2026-09-30', inclusive: true },
        relation: 'and',
      },
    ],
  },
});

Calendar configuration

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

const calendar = createCalendarRangeStructuredFilterType({
  weekStartsOn: 1,
  timeZone: 'Europe/Lisbon',
  locale: 'pt-PT',
  minDate: '2026-01-01',
  maxDate: '2026-12-31',
  disabledDates: ['2026-12-25'],
  showOperator: true,
  showSelectionSummary: true,
  showClearButton: true,
  showCalendar: true,
  calendar: {
    views: ['month', 'year'],
    defaultView: 'month',
    showHeader: true,
    showNavigation: true,
    showPreviousButton: true,
    showNextButton: true,
    showMonthLabel: true,
    showWeekdays: true,
    showOutsideDays: true,
    allowOutsideMonthSelection: false,
    fixedWeeks: true,
    showTodayButton: true,
    isMonthDisabled: month => month === '2026-07-01',
    dayClassName: date => date.endsWith('-25') ? 'holiday' : undefined,
  },
  rangeValidation: {
    minDays: 2,
    maxDays: 31,
    allowSameDay: false,
    allowDisabledDates: false,
    validate: (range, context) =>
      range.from.slice(0, 7) === range.to.slice(0, 7)
        || 'Choose dates within one month',
  },
  onInvalidRange: (range, reason) => {
    console.info('Range rejected', range, reason);
  },
  dateFormat: { day: '2-digit', month: 'short', year: 'numeric' },
  formatDate: (date, context) =>
    new Intl.DateTimeFormat(context.locale, context).format(
      new Date(`${date}T12:00:00Z`),
    ),
});

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

disabledDates can also be a callback receiving the ISO date and resolved locale/timezone context. When weekStartsOn or timeZone is omitted, it inherits the resolved date-filter policy for the column. The calendar renders a bounded month view, so a disabled-date callback does not scan grid rows.

Filter visibility

Option	Behavior
showOperator	Shows or hides the operator selector. The first configured operator remains active when hidden.
showSelectionSummary	Shows or hides the selected-range status chip.
showClearButton	Shows or hides the clear action.
showCalendar	Shows or hides the complete calendar body.
operators	Ordered allow-list for between and single-date operators.

Range validation

Validation runs before a completed range is committed. An invalid end date keeps the current start date, displays an accessible error, and leaves the previous filter condition unchanged.

Option	Behavior
rangeValidation.minDays	Minimum inclusive number of selected calendar days.
rangeValidation.maxDays	Maximum inclusive number of selected calendar days.
rangeValidation.allowSameDay	Allows a one-day range. Defaults to true.
rangeValidation.allowDisabledDates	Allows unavailable dates inside a range. Defaults to true for compatibility. Endpoints must always be selectable.
rangeValidation.validate	Final application validator. Return true, false, or a user-facing error string.
onInvalidRange	Receives the normalized attempted range, reason, and resolved column/locale/timezone context.

Invalid, zero, or negative minDays and maxDays values are ignored. Restored conditions remain a data contract: selection UI validation prevents new invalid interactions but does not silently delete saved filters.

Independent Calendar component

The visual calendar is an independent Pro UI component exported from @revolist/revogrid-pro. Date parsing and calendar arithmetic remain in the dates module, but calendar rendering is no longer owned or exported by plugins/dates/calendar.

The filter’s nested calendar object accepts the reusable component’s presentation and interaction options:

Option	Behavior
views	Available month and/or year views.
defaultView	Initial view when it is included in views.
showHeader	Hides the complete heading/navigation row.
showNavigation	Convenience switch for both navigation actions.
showPreviousButton, showNextButton	Independently control navigation actions.
showMonthLabel	Hides the month/year heading while preserving navigation geometry.
showWeekdays	Shows or hides weekday labels.
showOutsideDays	Renders adjacent-month days.
allowOutsideMonthSelection	Allows rendered adjacent-month days to be selected.
fixedWeeks	Uses a stable six-week grid when true.
showTodayButton	Shows the Today shortcut.
isMonthDisabled	Disables complete months in navigation and year view.
dayClassName, renderDay	Customize day presentation from ISO date and state context.
formatMonth, formatWeekday, formatDayLabel	Customize visible and accessible date text.
translations	Overrides any subset of calendar interface labels.
validateSelection, onInvalidSelection	Validates individual selections before onSelect.
onViewChange	Reports month/year view changes.

The standalone component is controlled: consumers provide month, focusedDate, optional selection/preview, and the corresponding change callbacks. Bounds (minDate, maxDate) and isDateDisabled apply to mouse, keyboard, Today, navigation, and year-view interactions.

The previous flat showOutsideDays, allowOutsideMonthSelection, fixedWeeks, and showTodayButton filter options remain compatibility aliases. Nested calendar values take precedence.

Localization

Date text uses the configured locale. Interface and accessibility text use the normal advanced-filter localization contract. CALENDAR_RANGE_LOCALIZATION exports the complete English fallback and stable keys:

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

grid.filter = defineAdvancedFilterConfig({
  localization: {
    filterNames: {
      calendarRangeBetween: 'Está no intervalo',
    },
    captions: {
      calendarRangeTitle: 'Intervalo de datas',
      calendarRangeBetween: 'entre',
      calendarRangeChooseEnd: 'Escolha a data final',
      calendarRangeEmpty: 'Nenhum intervalo selecionado',
      calendarRangeClear: 'Limpar intervalo de datas',
      calendarRangePreviousMonth: 'Mês anterior',
      calendarRangeNextMonth: 'Mês seguinte',
      calendarRangeCalendar: 'Calendário',
      calendarRangeToday: 'Hoje',
      calendarRangeInvalid: 'Escolha um intervalo válido',
      calendarRangeSameDay: 'Escolha duas datas diferentes',
      calendarRangeTooShort: 'Escolha um intervalo maior',
      calendarRangeTooLong: 'Escolha um intervalo menor',
      calendarRangeContainsDisabledDate: 'O intervalo contém uma data indisponível',
    },
  },
});

The independent Calendar also exports CalendarTranslations and DEFAULT_CALENDAR_TRANSLATIONS; its translations property accepts a partial override. Application-provided custom validation messages are displayed as supplied, so localize those strings in the application.

Common mistakes

• Passing datetimes or locale-formatted strings in restored state; use ISO date-only values.
• Omitting inclusive: true; other values are rejected.
• Configuring only locale and expecting it to set timezone policy; locale formats text, while timeZone decides the civil date.
• Assuming disabled dates change source data or reject every programmatic condition; they primarily constrain calendar selection.
• Replacing grid.filter for localization without also retaining a configured structuredFilterTypes registration.

Related guides

• Date and Datetime Filters
• Relative or Rolling Window
• Structured Filter Types
• Blank Values