> Documentation index: https://www.gooddata.ai/docs/gooddata-ui/llms.txt lists every page of these docs as Markdown.

# Date filter

> Configure DateFilter with filter options, granularities, and a date format, and handle the applied selection.

API reference: [DateFilter](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-filters/sdk-ui-filters.datefilter/index.md) (variable), [IDateFilterProps](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-filters/sdk-ui-filters.idatefilterprops/index.md) (interface)

[`DateFilter`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-filters/sdk-ui-filters.datefilter/index.md) is a dropdown that lists date filter options. You pass the options to offer (`filterOptions`) and an `onApply` callback. When a user clicks **Apply**, the callback receives the selected option and the exclude-current-period flag.

![DateFilter dropdown open with All time, Static period, Relative period, and presets grouped by year, quarter, month, and day](https://www.gooddata.ai/docs/gooddata-ui/gd-ui/date_filter.png)

## [Structure](https://www.gooddata.ai/docs/gooddata-ui/latest/filters/date-filter/#structure)

```tsx
import "@gooddata/sdk-ui-filters/styles/css/main.css";
import { DateFilter } from "@gooddata/sdk-ui-filters";

<DateFilter
    filterOptions={<date-filter-options>}
    selectedFilterOption={<selected-option>}
    excludeCurrentPeriod={<boolean>}
    availableGranularities={<granularities>}
    dateFilterMode={<"active" | "readonly" | "hidden">}
    onApply={<on-apply-callback>}
/>;
```

## [Example](https://www.gooddata.ai/docs/gooddata-ui/latest/filters/date-filter/#example)

The filter starts on **All time**. When a user clicks **Apply**, the component stores the selected option and the exclude-current-period flag in state.

```tsx
import { useState } from "react";
import { DateFilter, defaultDateFilterOptions, type DateFilterOption } from "@gooddata/sdk-ui-filters";
import type { DateFilterGranularity } from "@gooddata/sdk-model";

import "@gooddata/sdk-ui-filters/styles/css/main.css";

const availableGranularities: DateFilterGranularity[] = [
    "GDC.time.month",
    "GDC.time.year",
    "GDC.time.quarter",
    "GDC.time.date",
];

// Provide your own date filter options (IDateFilterOptionsByType), or use the defaults
const dateFilterOptions = defaultDateFilterOptions;

export const DateFilterExample = () => {
    const [selectedFilterOption, setSelectedFilterOption] = useState<DateFilterOption>(
        dateFilterOptions.allTime!,
    );
    const [excludeCurrentPeriod, setExcludeCurrentPeriod] = useState(false);

    return (
        <div style={{ width: 300 }}>
            <DateFilter
                excludeCurrentPeriod={excludeCurrentPeriod}
                selectedFilterOption={selectedFilterOption}
                filterOptions={dateFilterOptions}
                availableGranularities={availableGranularities}
                customFilterName="Date filter name"
                dateFilterMode="active"
                dateFormat="M/d/yy"
                onApply={(option, exclude) => {
                    setSelectedFilterOption(option);
                    setExcludeCurrentPeriod(exclude);
                }}
            />
        </div>
    );
};
```

To turn the selected option into a filter for a visualization, call `DateFilterHelpers.mapOptionToAfm(option, dateDataSetRef, excludeCurrentPeriod)`. It returns an [`IDateFilter`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-model/sdk-model.idatefilter/index.md), or `null` for **All time**.

## [Granularities](https://www.gooddata.ai/docs/gooddata-ui/latest/filters/date-filter/#granularities)

`availableGranularities` sets the granularities users can pick in the relative period form.

> **Removed option:**
> The `availableGranularities` option of `relativeForm` in the filter options was removed. Use the `availableGranularities` prop of [`DateFilter`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-filters/sdk-ui-filters.datefilter/index.md) instead.

## [Date format](https://www.gooddata.ai/docs/gooddata-ui/latest/filters/date-filter/#date-format)

`dateFormat` sets how dates are displayed. Use any format that the [date-fns](https://date-fns.org/docs/format) library supports.

![Two DateFilter dropdowns side by side, one showing dates in dd/MM/yyyy format and one in M/d/yy format](https://www.gooddata.ai/docs/gooddata-ui/gd-ui/date_filter_international_date_format.png)

## [Time filtering](https://www.gooddata.ai/docs/gooddata-ui/latest/filters/date-filter/#time-filtering)

To let users pick a time in addition to a date in the static period form, set `isTimeForAbsoluteRangeEnabled` to `true`. Only GoodData Cloud and GoodData.CN support it.

![DateFilter static period form with date and time inputs for the range start and end](https://www.gooddata.ai/docs/gooddata-ui/gd-ui/date_filter_time.png)

## [Dashboard date filter presets](https://www.gooddata.ai/docs/gooddata-ui/latest/filters/date-filter/#dashboard-date-filter-presets)

The presets that dashboards show in their date filters come from the `dateFilterConfig` organization or workspace setting, not from [`DateFilter`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-filters/sdk-ui-filters.datefilter/index.md) props. See [Customize the date filter presets](https://www.gooddata.ai/docs/gooddata-ui/latest/filters/customize-date-filter-presets/index.md).

## [Props](https://www.gooddata.ai/docs/gooddata-ui/latest/filters/date-filter/#props)

| Prop | Type | Required | Description | Inherited from |
|------|------|----------|-------------|----------------|
| [`availableGranularities`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-filters/sdk-ui-filters.idatefilterownprops/index.md#idatefilterownpropsavailablegranularities) | [`DateFilterGranularity`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-model/sdk-model.datefiltergranularity/index.md)`[]` | Yes | — | [`IDateFilterOwnProps`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-filters/sdk-ui-filters.idatefilterownprops/index.md) |
| [`dateFilterMode`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-filters/sdk-ui-filters.idatefilterownprops/index.md#idatefilterownpropsdatefiltermode) | [`VisibilityMode`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-filters/sdk-ui-filters.visibilitymode/index.md) | Yes | — | [`IDateFilterOwnProps`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-filters/sdk-ui-filters.idatefilterownprops/index.md) |
| [`excludeCurrentPeriod`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-filters/sdk-ui-filters.idatefilterstatepropsintersection/index.md#idatefilterstatepropsintersectionexcludecurrentperiod) | `boolean` | Yes | — | [`IDateFilterStatePropsIntersection`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-filters/sdk-ui-filters.idatefilterstatepropsintersection/index.md) |
| [`filterOptions`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-filters/sdk-ui-filters.idatefilterownprops/index.md#idatefilterownpropsfilteroptions) | [`IDateFilterOptionsByType`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-filters/sdk-ui-filters.idatefilteroptionsbytype/index.md) | Yes | — | [`IDateFilterOwnProps`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-filters/sdk-ui-filters.idatefilterownprops/index.md) |
| [`onApply`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-filters/sdk-ui-filters.idatefiltercallbackprops/index.md#idatefiltercallbackpropsonapply) | `(dateFilterOption:` [`DateFilterOption`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-filters/sdk-ui-filters.datefilteroption/index.md)`, excludeCurrentPeriod: boolean) => void` | Yes | — | [`IDateFilterCallbackProps`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-filters/sdk-ui-filters.idatefiltercallbackprops/index.md) |
| [`selectedFilterOption`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-filters/sdk-ui-filters.idatefilterstatepropsintersection/index.md#idatefilterstatepropsintersectionselectedfilteroption) | [`DateFilterOption`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-filters/sdk-ui-filters.datefilteroption/index.md) | Yes | — | [`IDateFilterStatePropsIntersection`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-filters/sdk-ui-filters.idatefilterstatepropsintersection/index.md) |
| [`activeCalendars`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-filters/sdk-ui-filters.idatefilterownprops/index.md#idatefilterownpropsactivecalendars) | [`IActiveCalendars`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-model/sdk-model.iactivecalendars/index.md) | No | _(Alpha)_ Active calendars configuration from workspace settings. Controls which calendar types (standard/fiscal) are available in the filter. | [`IDateFilterOwnProps`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-filters/sdk-ui-filters.idatefilterownprops/index.md) |
| [`ButtonComponent`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-filters/sdk-ui-filters.idatefilterownprops/index.md#idatefilterownpropsbuttoncomponent) | `ComponentType<`[`IDateFilterButtonProps`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-filters/sdk-ui-filters.idatefilterbuttonprops/index.md)`>` | No | _(Alpha)_ Specify custom button component | [`IDateFilterOwnProps`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-filters/sdk-ui-filters.idatefilterownprops/index.md) |
| [`customFilterName`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-filters/sdk-ui-filters.idatefilterownprops/index.md#idatefilterownpropscustomfiltername) | `string` | No | — | [`IDateFilterOwnProps`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-filters/sdk-ui-filters.idatefilterownprops/index.md) |
| [`customIcon`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-filters/sdk-ui-filters.idatefilterownprops/index.md#idatefilterownpropscustomicon) | [`IFilterButtonCustomIcon`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-filters/sdk-ui-filters.ifilterbuttoncustomicon/index.md) | No | _(Alpha)_ Represents a custom icon with associated tooltip information. | [`IDateFilterOwnProps`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-filters/sdk-ui-filters.idatefilterownprops/index.md) |
| [`customRangeHint`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-filters/sdk-ui-filters.idatefilterownprops/index.md#idatefilterownpropscustomrangehint) | `ReactNode` | No | _(Alpha)_ Custom content rendered at the end of the hint area of the static period (absolute range) form, after the default date/time format hints. | [`IDateFilterOwnProps`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-filters/sdk-ui-filters.idatefilterownprops/index.md) |
| [`dateFormat`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-filters/sdk-ui-filters.idatefilterownprops/index.md#idatefilterownpropsdateformat) | `string` | No | — | [`IDateFilterOwnProps`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-filters/sdk-ui-filters.idatefilterownprops/index.md) |
| [`enableEmptyDateValues`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-filters/sdk-ui-filters.idatefilterownprops/index.md#idatefilterownpropsenableemptydatevalues) | `boolean` | No | _(Alpha)_ Enables empty date values UI (e.g. “Other → Empty values” preset, empty-values handling controls). | [`IDateFilterOwnProps`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-filters/sdk-ui-filters.idatefilterownprops/index.md) |
| [`FilterConfigurationComponent`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-filters/sdk-ui-filters.idatefilterownprops/index.md#idatefilterownpropsfilterconfigurationcomponent) | `ComponentType<`[`IFilterConfigurationProps`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-filters/sdk-ui-filters.ifilterconfigurationprops/index.md)`>` | No | _(Alpha)_ Represents a custom component for configuration. | [`IDateFilterOwnProps`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-filters/sdk-ui-filters.idatefilterownprops/index.md) |
| [`hideDisabledExclude`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-filters/sdk-ui-filters.idatefilterownprops/index.md#idatefilterownpropshidedisabledexclude) | `boolean` | No | _(Alpha)_ When true, the "Exclude current period" toggle is hidden when it is disabled for the currently selected option. | [`IDateFilterOwnProps`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-filters/sdk-ui-filters.idatefilterownprops/index.md) |
| [`isAbsoluteDateFilterGranularityEnabled`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-filters/sdk-ui-filters.idatefilterownprops/index.md#idatefilterownpropsisabsolutedatefiltergranularityenabled) | `boolean` | No | _(Alpha)_ Enables Day/Week/Month/Quarter/Year granularity switching for the absolute (static) date filter. | [`IDateFilterOwnProps`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-filters/sdk-ui-filters.idatefilterownprops/index.md) |
| [`isEditMode`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-filters/sdk-ui-filters.idatefilterownprops/index.md#idatefilterownpropsiseditmode) | `boolean` | No | — | [`IDateFilterOwnProps`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-filters/sdk-ui-filters.idatefilterownprops/index.md) |
| [`isSecondsForAbsoluteRangeEnabled`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-filters/sdk-ui-filters.idatefilterownprops/index.md#idatefilterownpropsissecondsforabsoluterangeenabled) | `boolean` | No | If enabled, the absolute date filter form time inputs allow second-level precision (HH:mm:ss) instead of minute precision (HH:mm). Only takes effect together with `isTimeForAbsoluteRangeEnabled`. | [`IDateFilterOwnProps`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-filters/sdk-ui-filters.idatefilterownprops/index.md) |
| [`isTimeForAbsoluteRangeEnabled`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-filters/sdk-ui-filters.idatefilterownprops/index.md#idatefilterownpropsistimeforabsoluterangeenabled) | `boolean` | No | — | [`IDateFilterOwnProps`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-filters/sdk-ui-filters.idatefilterownprops/index.md) |
| [`locale`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-filters/sdk-ui-filters.idatefilterownprops/index.md#idatefilterownpropslocale) | `string` | No | — | [`IDateFilterOwnProps`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-filters/sdk-ui-filters.idatefilterownprops/index.md) |
| [`onCancel`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-filters/sdk-ui-filters.idatefiltercallbackprops/index.md#idatefiltercallbackpropsoncancel) | `() => void` | No | — | [`IDateFilterCallbackProps`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-filters/sdk-ui-filters.idatefiltercallbackprops/index.md) |
| [`onClose`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-filters/sdk-ui-filters.idatefiltercallbackprops/index.md#idatefiltercallbackpropsonclose) | `() => void` | No | — | [`IDateFilterCallbackProps`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-filters/sdk-ui-filters.idatefiltercallbackprops/index.md) |
| [`onOpen`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-filters/sdk-ui-filters.idatefiltercallbackprops/index.md#idatefiltercallbackpropsonopen) | `() => void` | No | — | [`IDateFilterCallbackProps`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-filters/sdk-ui-filters.idatefiltercallbackprops/index.md) |
| [`onSelect`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-filters/sdk-ui-filters.idatefiltercallbackprops/index.md#idatefiltercallbackpropsonselect) | `(dateFilterOption:` [`DateFilterOption`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-filters/sdk-ui-filters.datefilteroption/index.md)`, excludeCurrentPeriod: boolean) => void` | No | — | [`IDateFilterCallbackProps`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-filters/sdk-ui-filters.idatefiltercallbackprops/index.md) |
| [`openOnInit`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-filters/sdk-ui-filters.idatefilterownprops/index.md#idatefilterownpropsopenoninit) | `boolean` | No | — | [`IDateFilterOwnProps`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-filters/sdk-ui-filters.idatefilterownprops/index.md) |
| [`overlayPositionType`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-filters/sdk-ui-filters.idatefilterownprops/index.md#idatefilterownpropsoverlaypositiontype) | `OverlayPositionType` | No | Specifies the overlay position type for the date filter dropdown. | [`IDateFilterOwnProps`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-filters/sdk-ui-filters.idatefilterownprops/index.md) |
| [`showDropDownHeaderMessage`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-filters/sdk-ui-filters.idatefilterownprops/index.md#idatefilterownpropsshowdropdownheadermessage) | `boolean` | No | — | [`IDateFilterOwnProps`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-filters/sdk-ui-filters.idatefilterownprops/index.md) |
| [`weekStart`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-filters/sdk-ui-filters.idatefilterownprops/index.md#idatefilterownpropsweekstart) | [`WeekStart`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-model/sdk-model.weekstart/index.md) | No | The day weeks start on in the calendars and in the list of weeks. Defaults to Sunday. | [`IDateFilterOwnProps`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-filters/sdk-ui-filters.idatefilterownprops/index.md) |
| [`withoutApply`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-filters/sdk-ui-filters.idatefilterownprops/index.md#idatefilterownpropswithoutapply) | `boolean` | No | _(Alpha)_ This enables filter mode without apply button. If true, it is responsibility of a client, to appy filters when needed. Typically uses onSelect callback to catch filter state. Note, onApply callback is not called when this is true. | [`IDateFilterOwnProps`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-filters/sdk-ui-filters.idatefilterownprops/index.md) |
| [`workingExcludeCurrentPeriod`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-filters/sdk-ui-filters.idatefilterownprops/index.md#idatefilterownpropsworkingexcludecurrentperiod) | `boolean` | No | _(Deprecated)_ _(Alpha)_ Working filter exclude current period used for synchronization inner filter state with outer given state. Makes a controlled component state out of this. | [`IDateFilterOwnProps`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-filters/sdk-ui-filters.idatefilterownprops/index.md) |
| [`workingSelectedFilterOption`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-filters/sdk-ui-filters.idatefilterownprops/index.md#idatefilterownpropsworkingselectedfilteroption) | [`DateFilterOption`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-filters/sdk-ui-filters.datefilteroption/index.md) | No | _(Deprecated)_ _(Alpha)_ Working filter option used for synchronization inner filter state with outer given state. Makes a controlled component state out of this. | [`IDateFilterOwnProps`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-filters/sdk-ui-filters.idatefilterownprops/index.md) |