# DateRangeFilter

**Category:** Features/Filter/Components

## Design

### Overview

Use `DateRangeFilter` for rendering a date range.

> Note: Use this filter only in a "filters panel", and not in the toolbar itself.
> This filter will always be displayed inside the side panel.

### Timezone shifting

The dates that passed to `fetchData(query.filters)` are in the timezone of the user's browser.

If you want to shift the dates to a different timezone (usually UTC), you can use a utility function, for example:

> Note: use date-fns-tz@^2.0.0
> Always test your code in a few timezones

```js
import { zonedTimeToUtc } from 'date-fns-tz';

const fetchData = async (query) => {
  const {
    filters: { updatedAt },
  } = query;
  const { items, total } = await fetch(
    queryItems({
      updatedAt: {
        start: updatedAt.from && zonedTimeToUtc(updatedAt.from, 'UTC'),
        end: updatedAt.to && zonedTimeToUtc(updatedAt.to, 'UTC'),
      },
    }),
  );

  return {
    items,
    total,
  };
};
```


```tsx
import { DateRangeFilter } from '@wix/patterns';
```

---

### Examples

### Basic - By default `mode` property equals `COMBINE`

```tsx
import React from 'react';
import { dateRangeFilter, DateRangeFilter } from '@wix/patterns';

function BasicDateRangeFilter() {
  const [filter] = React.useState(() => dateRangeFilter());

  return <DateRangeFilter filter={filter} />;
}
```

---

### Only with custom dates

```tsx
import React from 'react';
import { dateRangeFilter, DateRangeFilter } from '@wix/patterns';

function OnlyCustomDateRangeFilter() {
  const [filter] = React.useState(() => dateRangeFilter());

  return <DateRangeFilter filter={filter} mode="ONLY_CUSTOM" />;
}
```

---

### Only with predefined dates

```tsx
import React from 'react';
import { dateRangeFilter, DateRangeFilter } from '@wix/patterns';

function OnlyPredefinedDateRangeFilter() {
  const [filter] = React.useState(() => dateRangeFilter());

  return <DateRangeFilter filter={filter} mode="ONLY_PREDEFINED" />;
}
```

---

### With override presets in combine mode

```tsx
import React from 'react';
import { dateRangeFilter, DateRangeFilter } from '@wix/patterns';

function OverridePresetsCombineDateRangeFilter() {
  const [filter] = React.useState(() => dateRangeFilter());

  return (
    <DateRangeFilter
      filter={filter}
      mode="COMBINE"
      dateRangeOptions={['FOURTEEN_DAYS', 'MONTH']}
    />
  );
}
```

---

### With override presets in predefined mode

```tsx
import React from 'react';
import { dateRangeFilter, DateRangeFilter } from '@wix/patterns';

function OverridePresetsPredefinedDateRangeFilter() {
  const [filter] = React.useState(() => dateRangeFilter());

  return (
    <DateRangeFilter
      filter={filter}
      mode="ONLY_PREDEFINED"
      dateRangeOptions={['SEVEN_DAYS', 'MONTH']}
    />
  );
}
```

---

### Future timeframes

```tsx
import React from 'react';
import { dateRangeFilter, DateRangeFilter } from '@wix/patterns';

function OverridePresetsFutureDateRangeFilter() {
  const [filter] = React.useState(() => dateRangeFilter());

  return (
    <DateRangeFilter
      filter={filter}
      mode="COMBINE"
      dateRangeOptions={[
        'TODAY',
        'TOMORROW',
        'NEXT_THREE_DAYS',
        'NEXT_SEVEN_DAYS',
        'NEXT_THIRTY_DAYS',
      ]}
    />
  );
}
```

---

### With time resolution

```tsx
import React from 'react';
import { dateRangeFilter, DateRangeFilter } from '@wix/patterns';

function WithTimeResolution() {
  const [filter] = React.useState(() => dateRangeFilter());

  return <DateRangeFilter filterByTime={true} filter={filter} />;
}
```

## API

### Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `mode` | `"ONLY_PREDEFINED" \| "ONLY_CUSTOM" \| "COMBINE"` | No | - | There are 3 possible modes: - `ONLY_PREDEFINED`: show only predefined dates options - `ONLY_CUSTOM`: show only custom date pickers - `COMBINE`: default, combines both predefined and custom |
| `dateRangeOptions` | `DateRangeOptions` | No | ``['SEVEN_DAYS', 'FOURTEEN_DAYS', 'MONTH']`` | An optional array of 3 possible options: `'SEVEN_DAYS', 'FOURTEEN_DAYS', 'MONTH'`. |
| `filterByTime` | `boolean` | No | - | If to include time resolution |
| `filter` | `Filter<RangeItem<Date>>` | Yes | - | A filter state object such as [ArrayFilter](./?path=/story/features-filter-factories--arrayfilter) |
| `fieldType` | `"SHORT_TEXT" \| "LONG_TEXT" \| "NUMBER" \| "BOOLEAN" \| "DATE" \| "DATE_TIME" \| "DATETIME" \| "TIME" \| "URL" \| "EMAIL" \| "IMAGE" \| "MEDIA_GALLERY" \| "AUDIO" \| "DOCUMENT" \| "MULTI_DOCUMENT" \| "RICH_TEXT" \| "RICH_CONTENT" \| "REFERENCE" \| "MULTI_REFERENCE" \| "OBJECT" \| "ARRAY" \| "ADDRESS" \| "COLOR" \| "INTEGER" \| "DECIMAL" \| "CHECKBOX" \| "DROPDOWN" \| "FILES" \| "MULTI_SELECT"` | No | - | The field type string used to resolve a prefix icon for the filter. Cairo maps this to the appropriate icon internally. |
| `layout` | `"button"` | No | - | Padding settings. If this prop it omitted, padding will exist on the sides of the filter.<br> <br> Supported values: <br> - `"button"`: Removes padding from the sides of the filter. |
| `toolbarItemProps` | `{ label?: ReactNode; }` | No | - | Customizes the filter in the toolbar.<br> <br> Supported properties: <br> - `label`: [string] Prefix for the filter element. |
| `toolbarTagProps` | `{ label?: string; }` | No | - | Customizes the filter tag in the toolbar.<br> <br> Supported properties: <br> - `label`: [string] Overrides the default filter name when filtered tag is shown. |
| `initiallyOpen` | `boolean` | No | - | Indicates whether the filter should be visible by default in the filters panel |
| `accordionItemProps` | `(AccordionItemType & { label?: string; })` | No | - | Customizes the filter [accordion](https://www.docs.wixdesignsystem.com/?path=/story/components-lists--accordion).<br> <br> Supported properties: <br> - `label`: [string] Accordion item title. You can also use `AccordionProps['items'][number].title` for more flexibility. <br> - Extends [AccordionProps['items'[number]](https://www.docs.wixdesignsystem.com/?path=/story/components-lists--accordion). |
| `popoverProps` | `PopoverCommonProps` | No | - | @deprecated |
| `onAppliedFilterTagRemove` | `((item: RangeItem<Date>) => unknown)` | No | - | Callback that's run when a filter is removed by a visitor from the sub-toolbar. @param item |
| `renderToolbarTag` | `((item: RangeItem<Date>) => Partial<TagListTag>)` | No | - | Customizes how the tag list in the sub-toolbar is rendered. <br><br> Extends [`TagListProps['tags'][number]`](https://www.docs.wixdesignsystem.com/?path=/story/components-lists-table--taglist). |
| `sectionTitle` | `string` | No | - | Title for the section in the accordion. |
| `className` | `string` | No | - | Specifies a CSS class name to be appended to the component’s root element. |
| `customInput` | `ReactNode` | No | - | Override a field with a custom input element. If you only need to pass custom props to the `<Input/>`, then use `inputProps` instead. |
| `inputProps` | `Partial<InputProps>` | No | - | Allows you to pass default Input component properties |
| `inputRef` | `Ref<HTMLInputElement>` | No | - | Ref to the underlying `<input>` DOM element. Accepts callback and object refs. Use for input masking libraries. Memoize callback refs to avoid reattaching. |
| `locale` | `"id" \| "en" \| "en-US" \| "en-GB" \| "en-AU" \| "en-CA" \| "ar" \| "bg" \| "ca" \| "zh" \| "zh-TW" \| "zh-HK" \| "zh-MO" \| "cs" \| "da" \| "nl" \| "fi" \| "fr" \| "fr-CA" \| "fr-CH" \| "fr-BE" \| "de" \| "de-CH" \| "de-AT" \| "el" \| "he" \| "hi" \| "hu" \| "it" \| "ja" \| "ko" \| "lt" \| "ms" \| "no" \| "nb" \| "nn" \| "pl" \| "pt-BR" \| "pt" \| "ro" \| "ru" \| "sk" \| "sl" \| "es" \| "es-419" \| "es-AR" \| "es-MX" \| "es-US" \| "sv" \| "tl" \| "th" \| "tr" \| "uk" \| "vi"` | No | - | Specify date picker instance locale |
| `dateStyle` | `"medium" \| "short" \| "long"` | No | `'short'` | Sets date format of locale |
| `disabled` | `boolean` | No | `false` | Specify whether a field should be disabled or not |
| `inputDataHook` | `string` | No | - | Applies a data-hook HTML attribute for date picker input |
| `calendarDataHook` | `string` | No | - | Applies a data-hook HTML attribute for date picker calendar view |
| `placeholderText` | `string` | No | - | Defines a placeholder of the field |
| `rtl` | `boolean` | No | `false` | Specify whether RTL mode is enabled or not. When true, the keyboard navigation will be changed, meaning pressing on the right arrow will navigate to the previous day, and pressing on the left arrow will navigate to the next day. |
| `value` | `Date` | No | - | Defines the selected date |
| `initialOpen` | `boolean` | No | - | Specify whether the calendar will be initially visible or not |
| `status` | `"error" \| "warning" \| "loading"` | No | - | Controls the status of a field |
| `statusMessage` | `ReactNode` | No | - | Defines the status message to be displayed on status icon hover. If not given or empty, the tooltip won’t be shown. |
| `width` | `string \| number` | No | `'150px'` | Sets the width of picker input in pixels or percentage |
| `zIndex` | `number` | No | - | Set a desired z-index for date picker popover |
| `firstDayOfWeek` | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6` | No | - | Specify the starting day of a week, allowing only from 0 to 6 (Sunday to Saturday). The default value is 1 which means Monday. |
| `size` | `"small" \| "medium" \| "large"` | No | - | Specifies the size of the input |
| `readOnly` | `boolean` | No | - | Specify whether date picker input is readOnly or not |
| `clearButton` | `boolean` | No | - | Display a clear button (x) on a non-empty field |
| `onClear` | `MouseEventHandler<HTMLInputElement>` | No | - | Displays clear button (X) on a non-empty input and calls callback with no arguments |
| `disableKeyboardType` | `boolean` | No | `false` | Disable typing the in the input. When true, choosing a date is possible only by picking from the calendar. Default: false. |
| `validate` | `boolean` | No | - | Enables internal input validation |
| `onValidate` | `(({ validationType, format, value, }: { format?: string; validationType: "outOfBoundsError" \| "formatError" \| "valid"; value: string; }) => void)` | No | - | Defines a callback function which is called on cases when date is validated. - {validationType: 'outOfBoundsError' \| 'formatError' \| 'valid', format: string, value: string } - `validationType` - type 'formatError' is set when validated date is in the wrong date format - type 'outOfBoundsError' is set when 'excludePastDates' is true and date input is before today - type 'valid' is set when entered date is valid - `format` - is set to valid date format - `value` - is set to current input value |
| `clearButtonTooltipContent` | `ReactNode` | No | - | When provided, hover will display a tooltip |
| `clearButtonAriaLabel` | `string` | No | - | Aria label for the clear button |
| `clearButtonTooltipProps` | `TooltipCommonProps` | No | - | Tooltip props |
| `onOpen` | `(() => void)` | No | - | Defines a callback function which is called when date picker is opened. |
| `renderFooter` | `(() => ReactNode)` | No | - | Function which renders a provided node at the bottom of the Calendar. |
| `calendarProps` | `{ size?: "small" \| "medium"; }` | No | - | Defines the size of calendar opened |
| `dataHook` | `string` | No | - | Applies as data-hook HTML attribute that can be used in the tests |
| `onClose` | `(() => void)` | No | - | Defines a callback function that is called whenever a user presses escape, clicks outside of the element or a date is selected and `shouldCloseOnSelect` is set. Receives an event as a first argument. |
| `autoFocus` | `boolean` | No | `true` | Focus selected day automatically when component mounts or updates |
| `onChange` | `((date: Date) => void)` | No | - | Provides a callback function when day in selected in the calendar |
| `onKeyDown` | `((event: KeyboardEvent<Element>) => void)` | No | - | Provides a callback function when any key is clicked in the calendar |
| `numOfMonths` | `1 \| 2` | No | `1` | Allows to display multiple months at once. Currently it shows 1 or 2 months only. |
| `onMonthChange` | `((monthStart: Date) => void)` | No | - | Defines a callback function that is called with the date of the first day of the month whenever the user selects a month in the calendar |
| `excludePastDates` | `boolean` | No | `false` | Specify whether past dates should be selectable or not |
| `filterDate` | `((date: Date) => boolean)` | No | - | ##### Specify selectable dates: * `param` {Date} `date` - a date to check * `return` {boolean} - true if `date` should be selectable, false otherwise |
| `selectionMode` | `"day" \| "range"` | No | `'day'` | Whether the user should be able to select a date range, or just a single day |
| `showYearDropdown` | `boolean` | No | `false` | Displays a selectable yearDropdown |
| `showMonthDropdown` | `boolean` | No | `false` | Displays a selectable monthDropdown |
| `shouldCloseOnSelect` | `boolean` | No | `true` | Specify whether the calendar closes on day selection |
| `dateIndication` | `FC<dateIndicationProps>` | No | - | ##### Add an indication under a specific date. Function returns the indication node of a specific date or null if this day doesn't have an indication. - `param` {date: Date, isSelected: boolean } - `date` - a date - `isSelected` - whether this date is the selected date - `return` {React.node} - the indication node of a specific date or null if this day doesn't have an indication. |
| `today` | `Date` | No | - | Sets today's date. The today indication is added automatically according to the user timezone but in some cases, we need the ability to add the today indication based on the business timezone. |
| `containFocus` | `boolean` | No | - | Whether focus should be contained within the calendar |
| `leftArrowAriaLabel` | `string` | No | - | Defines a string value that labels the left arrow in calendar header |
| `leftArrowAriaLabelledBy` | `string` | No | - | Identifies the element that labels the left arrow in calendar header |
| `rightArrowAriaLabel` | `string` | No | - | Defines a string value that labels the right arrow in calendar header |
| `rightArrowAriaLabelledBy` | `string` | No | - | Identifies the element that labels the right arrow in calendar header |
| `monthDropdownAriaLabel` | `string` | No | - | Defines a string value that labels the months dropdown in calendar header |
| `monthDropdownAriaLabelledBy` | `string` | No | - | Identifies the element that labels the months dropdown in calendar header |
| `yearDropdownAriaLabel` | `string` | No | - | Defines a string value that labels the years dropdown in calendar header |
| `yearDropdownAriaLabelledBy` | `string` | No | - | Identifies the element that labels the years dropdown in calendar header |