--- title: Date time range picker description: Date Time Range Picker allows users to select a start and end date with time, including predefined time periods and timezone support. category: Forms related: [DatePicker, DateRangePicker, TextField, Label] commonPatterns: [query-time-range, log-time-range, predefined-time-periods] --- Source: https://clickhouse.design/click-ui/datetimerangepicker # Date time range picker Date Time Range Picker provides a tabbed calendar for selecting a start and end date with time. Use it for query windows, log search, and other ranges where the time of day matters. It supports predefined time periods, UTC or local time, seconds, and range validation. ## Example ## Props | Prop | Type | Default value | Description | | ------------------------ | ------------------------------------------------------------------------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | \*onSelectDateRange | `(startDate: Date, endDate: Date, predefinedDateLabel?: string) => void` | `undefined` | Called when both ends of the range are set. The optional third argument is the label of a predefined period, if one was selected. | | startDate | `Date` | `undefined` | Currently selected start date and time (controlled component) | | endDate | `Date` | `undefined` | Currently selected end date and time (controlled component) | | placeholder | `string` | `"start date – end date"` | Placeholder text displayed when no range is selected | | disabled | `boolean` | `false` | Whether the picker is disabled and cannot be interacted with | | futureDatesDisabled | `boolean` | `false` | Whether dates in the future should be disabled and unselectable | | futureStartDatesDisabled | `boolean` | `false` | Whether future dates can be selected as the start date (end date can still be future) | | maxRangeLength | `number` | `-1` | Maximum number of days allowed in the range. -1 means no limit. | | predefinedTimesList | `Array<{ label: string; dateRange: { startDate: Date; endDate: Date } }>` | `undefined` | Labeled relative time periods shown in a side list. When provided, the calendar opens from Custom time period. | | shouldShowSeconds | `boolean` | `false` | Whether time inputs and the trigger display seconds | | timezone | `"system" \| "UTC"` | `"system"` | Timezone used to display and interpret dates. system uses the local timezone. | | defaultActiveTab | `"startDate" \| "endDate"` | `"startDate"` | Which calendar tab is active when the picker opens | | closeOnDateRangeSelected | `boolean` | `false` | Whether the dropdown closes as soon as both start and end are selected | | shouldFireIfInvalid | `boolean` | `true` | Whether onSelectDateRange fires when the end is before the start. The picker still shows an error message either way. | | openDirection | `"left" \| "right"` | `"right"` | Preferred side for the custom calendar when predefined times are shown | | responsivePositioning | `boolean` | `true` | When true, the dropdown may flip to avoid collisions. Set false to keep it aligned with the input. | ```tsx import { DateTimeRangePicker } from '@clickhouse/click-ui' import { useState } from 'react' function Example() { const [startDate, setStartDate] = useState() const [endDate, setEndDate] = useState() return ( { setStartDate(start) setEndDate(end) }} placeholder="Select date and time range" /> ) } ``` ## Quick start ```tsx import { DateTimeRangePicker } from '@clickhouse/click-ui' import { useState } from 'react' function MyDateTimeRangePicker() { const [startDate, setStartDate] = useState() const [endDate, setEndDate] = useState() return ( { setStartDate(start) setEndDate(end) }} placeholder="Select date and time range" /> ) } ``` ## Related components - **DatePicker**: For selecting a single date without time. - **DateRangePicker**: For selecting a date range without time of day. - **TextField**: For text input, sometimes used alongside date time range pickers. - **Label**: Provides accessible labels for date time range pickers. ## Common use cases ### With seconds ```tsx import { DateTimeRangePicker } from '@clickhouse/click-ui' import { useState } from 'react' function DateTimeRangeWithSeconds() { const [startDate, setStartDate] = useState() const [endDate, setEndDate] = useState() return ( { setStartDate(start) setEndDate(end) }} placeholder="Select date and time range" shouldShowSeconds /> ) } ``` ### With predefined time periods Pass labeled ranges in `predefinedTimesList`. Selecting an item calls `onSelectDateRange` with that period's label as the third argument. Choose **Custom time period** to open the tabbed calendar. ```tsx import { DateTimeRangePicker } from '@clickhouse/click-ui' import { useState } from 'react' function DateTimeRangeWithPredefined() { const [startDate, setStartDate] = useState() const [endDate, setEndDate] = useState() const now = new Date() const predefinedTimesList = [ { label: 'Past 15 minutes', dateRange: { startDate: new Date(now.getTime() - 15 * 60 * 1000), endDate: now }, }, { label: 'Past hour', dateRange: { startDate: new Date(now.getTime() - 60 * 60 * 1000), endDate: now }, }, { label: 'Past day', dateRange: { startDate: new Date(now.getTime() - 24 * 60 * 60 * 1000), endDate: now }, }, ] return ( { setStartDate(start) setEndDate(end) }} placeholder="Select date and time range" predefinedTimesList={predefinedTimesList} /> ) } ``` ### UTC timezone `timezone="system"` (default) uses the local timezone. `timezone="UTC"` displays and interprets the same `Date` values in UTC. ```tsx import { DateTimeRangePicker, Container, Text } from '@clickhouse/click-ui' import { useState } from 'react' function DateTimeRangeTimezone() { const [startDate, setStartDate] = useState(new Date('2026-05-01T06:00:00Z')) const [endDate, setEndDate] = useState(new Date('2026-05-01T12:00:00Z')) return ( { setStartDate(start) setEndDate(end) }} timezone="system" /> { setStartDate(start) setEndDate(end) }} timezone="UTC" /> ) } ``` ### With future dates disabled ```tsx import { DateTimeRangePicker } from '@clickhouse/click-ui' import { useState } from 'react' function DateTimeRangeWithFutureDisabled() { const [startDate, setStartDate] = useState() const [endDate, setEndDate] = useState() return ( { setStartDate(start) setEndDate(end) }} placeholder="Select date and time range" futureDatesDisabled /> ) } ``` ### With maximum range length ```tsx import { DateTimeRangePicker } from '@clickhouse/click-ui' import { useState } from 'react' function DateTimeRangeWithMaxLength() { const [startDate, setStartDate] = useState() const [endDate, setEndDate] = useState() return ( { setStartDate(start) setEndDate(end) }} placeholder="Select date and time range" maxRangeLength={7} /> ) } ``` ### Validation By default `onSelectDateRange` still fires if the end is before the start. The picker shows **End date and time must be after start**. Set `shouldFireIfInvalid={false}` to skip the callback until the range is valid. ```tsx import { DateTimeRangePicker } from '@clickhouse/click-ui' import { useState } from 'react' function DateTimeRangeValidation() { const [startDate, setStartDate] = useState(new Date('2026-07-20T14:00:00')) const [endDate, setEndDate] = useState(new Date('2026-07-20T10:00:00')) return ( { setStartDate(start) setEndDate(end) }} shouldFireIfInvalid={false} /> ) } ``` ### Disabled state ```tsx import { DateTimeRangePicker } from '@clickhouse/click-ui' import { useState } from 'react' function DisabledDateTimeRangePicker() { const [startDate, setStartDate] = useState() const [endDate, setEndDate] = useState() return ( { setStartDate(start) setEndDate(end) }} placeholder="Select date and time range" disabled /> ) } ```