Date range picker

Preview

Basic
With relative value

Usage

The value and relativeOptions properties must be set via JavaScript:

<cs-date-range-picker placeholder="Filter by date range"></cs-date-range-picker>

<script>
  const picker = document.querySelector('cs-date-range-picker');
  picker.value = {
    type: 'absolute',
    startDate: '2025-01-01',
    endDate: '2025-01-31',
  };
  picker.relativeOptions = [
    { key: 'last-7', amount: 7, unit: 'day', type: 'relative' },
    { key: 'last-30', amount: 30, unit: 'day', type: 'relative' },
  ];
</script>

Properties

absolute-formatDateRangePickerProps.AbsoluteFormat

Specifies the time format to use for displaying the absolute time range.

It can take the following values:

  • iso: ISO 8601 format, e.g.: 2024-01-30T13:32:32+01:00 (or 2024-01-30 when dateOnly is true)
  • long-localized: a more human-readable, localized format, e.g.: January 30, 2024, 13:32:32 (UTC+1) (or January 30, 2024 when dateOnly is true)
  • slashed: similar to ISO 8601 but with '/' in place of '-'. e.g.: 2024/01/30 (or 2024/01)
aria-labelstring default: null

Adds aria-label to the trigger and dropdown.

custom-absolute-range-controlDateRangePickerProps.AbsoluteRangeControl

Specifies an additional control displayed in the dropdown, located below the range calendar.

custom-relative-range-unitsDateRangePickerProps.TimeUnit[]

Specifies which time units to allow in the custom relative range control.

date-disabled-reasonDateRangePickerProps.DateDisabledReasonFunction

Provides a reason why a particular date in the calendar is not enabled (only when isDateEnabled returns false). If provided, the date becomes focusable.

date-input-formatDateRangePickerProps.DateInputFormat

Specifies the date format to use on the date inputs in the absolute dropdown.

The format of the input as it is being interacted with. It can take the following values:

  • iso: ISO 8601 format without time, e.g.: 2024-01-30 (or 2024-01)
  • slashed: similar to ISO 8601 but with '/' in place of '-'. e.g.: 2024/01/30 (or 2024/01)
date-onlyboolean

Hides time inputs and changes the input format to date-only, e.g. 2021-04-06.

Do not use dateOnly flag conditionally. The component does not trigger the value update when the flag changes which means the value format can become inconsistent.

This does not apply when the 'granularity' is set to 'month'

Default: false.

disabledboolean

Specifies that the component is disabled, preventing the user from modifying the value. A disabled component cannot receive focus.

expand-to-viewportboolean

By default, the dropdown height is constrained to fit inside the height of its next scrollable container element. Enabling this property will allow the dropdown to extend beyond that container by using fixed positioning and React Portals.

Set this property if the dropdown would otherwise be constrained by a scrollable container, for example inside table and split view layouts.

We recommend you use discretion, and don't enable this property unless necessary because fixed positioning results in a slight, visible lag when scrolling complex pages.

get-time-offsetDateRangePickerProps.GetTimeOffsetFunction

A function that defines timezone offset from UTC in minutes for selected dates. Use it to define time relative to the desired timezone.

The function is called for the start date and the end date and takes a UTC date corresponding the selected value as an argument.

Has no effect when dateOnly is true.

Default: the user's current time offset as provided by the browser.

granularityany

Specifies the granularity at which users will be able to select a date. Defaults to day.

hide-time-offsetboolean

Specifies whether to hide the time offset in the displayed absolute time range. Defaults to false.

i18n-stringsDateRangePickerProps.I18nStrings

An object containing all the necessary localized strings required by the component.

is-date-enabledDateRangePickerProps.IsDateEnabledFunction

A function that defines whether a particular date should be enabled in the calendar or not. Note that disabling a date in the calendar still allows users to enter this date via keyboard. We therefore recommend that you also validate these constraints client- and server-side, in the same way as for other form elements.

is-valid-rangeDateRangePickerProps.ValidationFunctionrequired

A function that defines whether a particular range is valid or not.

Ensure that your function checks for missing fields in the value.

localestring

The locale to be used for rendering month names and defining the starting date of the week. If not provided, it will be determined from the page and browser locales. Supported values and formats are as-per the JavaScript Intl API specification.

placeholderstring default: ''

Specifies the placeholder text that is rendered when the value is empty.

range-selector-modeDateRangePickerProps.RangeSelectorMode default: 'default'

Determines the range selector mode as follows:

  • default for combined absolute/relative range selector.
  • absolute-only for absolute-only range selector.
  • relative-only for relative-only range selector.

By default, the range selector mode is default.

read-onlyboolean

Specifies that the component is read-only, preventing the user from modifying the value. A read-only component can receive focus.

relative-optionsReadonlyArray<DateRangePickerProps.RelativeOption>required

A list of relative time ranges that are shown as suggestions.

render-relative-range-contentDateRangePickerProps.RelativeRangeControl

Specifies custom content to fully override the relative range tab. When provided, all default relative range functionality is replaced.

show-clear-buttonboolean

Specifies whether the component should show a button that allows the user to clear the selected value.

start-of-weeknumber default: 0

Starting day of the week. [0-6] maps to [Sunday-Saturday]. By default the starting day of the week is defined by the locale, but you can override it using this property.

time-input-formatDateRangePickerProps.TimeInputFormat

Specifies the format of the time input for absolute ranges.

Use to restrict the granularity of time that the user can enter.

Has no effect when dateOnly is true or granularity is set to 'month'.

time-offsetnumber

The time offset from UTC in minutes that should be used to display and produce values.

Has no effect when dateOnly is true.

Default: the user's current time offset as provided by the browser.

valuenull | DateRangePickerProps.Valuerequired

The current date range value. Can be either an absolute time range or a relative time range.

Events

blurCustomEvent<null>

Fired when keyboard focus is removed from the UI control.

changeCustomEvent<DateRangePickerProps.ChangeDetail>

Fired whenever a user changes the component's value. The event detail contains the current value of the field.

focusCustomEvent<null>

Fired when keyboard focus is set onto the UI control.