Components
Dates
Date Range Picker

Date Range Picker

DateRangePicker combine a DateField and a RangeCalendar overlay to allow users to enter or select a date and time range.

yyyy

default.tsx

<DateRangePicker />

Installation

CLI

Manual

npm

pnpm

yarn

bun

npx dotui-cli@latest add date-range-picker

Usage

Use a DateRangePicker to allow users to enter and edit time values.

Options

Label

A visual label can be provided for the DateRangePicker using the label prop or a hidden label using aria-label prop.

Trip

yyyy

label.tsx

<DateRangePicker label="Trip" />
<DateRangePicker aria-label="Trip" />

Size

Use the size prop to control the size of the DateRangePicker.
The default variant is "md".

small

yyyy

medium

yyyy

large

yyyy

sizes.tsx

<DateRangePicker label="small" size="sm" />
<DateRangePicker label="medium" size="md" />
<DateRangePicker label="large" size="lg" />

Prefix

To add additional context for the DateRangePicker, use the prefix prop.

yyyy

prefix.tsx

<DateRangePicker prefix={<PlaneIcon />} />

Description

A description can be supplied to DateRangePicker via the description prop. The description is always visible unless the isInvalid prop is true and an error message is provided.

Trip

yyyy

Please select a date range.

description.tsx

<DateRangePicker label="Trip" description="Please select a date range." />

Contextual help

A ContextualHelp element may be placed next to the label to provide additional information or help about a DateRangePicker.

Trip

yyyy

contextual-help.tsx

<DateRangePicker label="Appointment" contextualHelp={<ContextualHelp />} />

Error message

An errorMessage can be supplied to a DateRangePicker, which will be displayed when the isInvalid prop is set to true.

Trip dates

yyyy

Trip dates can't be scheduled in the past.

error-message.tsx

<DateRangePicker
  label="Trip dates"
  isInvalid
  errorMessage="Trip dates can't be scheduled in the past."
/>

Time zones

DateRangePicker is time zone aware when a ZonedDateTime object is provided as the value.

2021

UTC

2021

UTC

time-zones.tsx

<DateRangePicker
  defaultValue={{
    start: parseAbsoluteToLocal("2021-04-07T18:45:22Z"),
    end: parseAbsoluteToLocal("2021-04-08T20:00:00Z"),
  }}
/>

Granularity

The granularity prop allows you to control the smallest unit that is displayed by DateRangePicker.

Hour

2021

UTC

2021

UTC

Minute

2021

UTC

2021

UTC

Second

2021

UTC

2021

UTC

granularity.tsx

<DateRangePicker label="Hour" granularity="hour" defaultValue={dates} />
<DateRangePicker label="Minute" granularity="minute" defaultValue={dates} />
<DateRangePicker label="Second" granularity="second" defaultValue={dates} />

Placeholder value

Use the placeholderValue prop to control the default values of each segment. The default value is midnight.

Meeting date

yyyy

placeholder.tsx

<DateRangePicker label="Meeting date" placeholderValue={new CalendarDate(1980, 1, 1)} />

Hide time zone

Use the hideTimeZone prop to hide the time zone abbreviation.

Appointment time

2021

hide-time-zone.tsx

<DateRangePicker
  label="Appointment time"
  granularity="minute"
  defaultValue={{
    start: parseAbsoluteToLocal("2021-04-07T18:45:22Z"),
    end: parseAbsoluteToLocal("2021-04-08T20:00:00Z"),
  }}
  hideTimeZone
/>

Hour cycle

Use the hourCycle prop to control the hour cycle of the DateRangePicker.

yyyy

––

yyyy

––

hour-cycle.tsx

<DateRangePicker granularity="minute" hourCycle={24} />

Loading

Use the isLoading prop to control the loading state of the DateRangePicker.

yyyy

loading.tsx

<DateRangePicker isLoading />

Disabled

Use the isDisabled prop to disable the DateRangePicker.

Trip dates

yyyy

disabled.tsx

<DateRangePicker label="Trip dates" isDisabled />

ReadOnly

The isReadOnly boolean prop makes the DateRangePicker's text content immutable. Unlike isDisabled, the DateRangePicker remains focusable and the contents can still be copied.

Event date

2021

UTC

2021

UTC

read-only.tsx

<DateRangePicker
  label="Event date"
  value={{
    start: parseAbsoluteToLocal("2021-04-07T18:45:22Z"),
    end: parseAbsoluteToLocal("2021-04-08T20:00:00Z"),
  }}
  isReadOnly
/>

Required

Use the isRequired prop to mark the DateRangePicker as required. Use the necessityIndicator prop to control the visual style of the required state.

Event date

yyyy

Event date

yyyy

Event date

yyyy

Event date

yyyy

required.tsx

<DateRangePicker label="Event date" isRequired />
<DateRangePicker label="Event date" isRequired necessityIndicator="icon" />
<DateRangePicker label="Event date" isRequired necessityIndicator="label" />
<DateRangePicker label="Event date" necessityIndicator="label" />

Uncontrolled

An initial, uncontrolled value can be provided to the DateRangePicker using the defaultValue prop.

Controlled

2020

uncontrolled.tsx

<DateRangePicker
label="Controlled"
defaultValue={{
  start: parseDate("2020-02-03"),
  end: parseDate("2020-02-08"),
}}
/>

Controlled

Use the value and onChange props to control the value of the input.

Controlled

2024

Selected date: February 3 – 8, 2024

controlled.tsx

const [value, setValue] = React.useState({
start: parseDate("2024-02-03"),
end: parseDate("2024-02-08"),
});
return <DateRangePicker label="Controlled" value={value} onChange={setValue} />

Composition

If you need to customize things further, you can drop down to the composition level.

Meeting date

yyyy

Please select a date.

composition.tsx

<DatePickerRoot>
<Label>Meeting date</Label>
<InputRoot suffix={<Button><CalendarIcon /></Button>}>
  <DateInput slot="start">{(segment) => <DateSegment segment={segment} />}</DateInput>
  <span>–</span>
  <DateInput slot="end">{(segment) => <DateSegment segment={segment} />}</DateInput>
</InputRoot>
<Description>Please select a date.</Description>
<FieldError />
<Overlay type="popover" mobileType="drawer">
  <DialogContent>
    <RangeCalendar />
  </DialogContent>
</Overlay>
</DatePickerRoot>

API Reference

Prop	Type	Default	Description
`pageBehavior`	`'single' \| 'visible'`	`'visible'`	Controls the behavior of paging. Pagination either works by advancing the visible page by visibleDuration (default) or one unit of visibleDuration.
`minValue`	`DateValue`	-	The minimum allowed date that a user may select.
`maxValue`	`DateValue`	-	The maximum allowed date that a user may select.
`isDateUnavailable`	`(date: DateValue) => boolean`	-	Callback that is called for each date of the calendar. If it returns true, then the date is unavailable.
`placeholderValue`	`DateValue`	-	A placeholder date that influences the format of the placeholder shown when no value is selected. Defaults to 12:00 AM or 00:00 depending on the hour cycle.
`hourCycle`	`12 \| 24`	-	Whether to display the time in 12 or 24 hour format. By default, this is determined by the user's locale.
`granularity`	`'hour' \| 'minute' \| 'second'`	-	Determines the smallest unit that is displayed in the date picker. By default, this is "day" for dates, and "minute" for times.
`hideTimeZone`	`boolean`	`false`	Whether to hide the time zone abbreviation.
`shouldForceLeadingZeros`	`boolean`	-	Whether to always show leading zeros in the hour field. By default, this is determined by the user's locale.
`isDisabled`	`boolean`	-	Whether the input is disabled.
`isReadOnly`	`boolean`	-	Whether the input can be selected but not changed by the user.
`isRequired`	`boolean`	-	Whether user input is required on the input before form submission.
`isInvalid`	`boolean`	-	Whether the input value is invalid.
`autoFocus`	`boolean`	-	Whether the element should receive focus on render.
`isOpen`	`boolean`	-	Whether the overlay is open by default (controlled).
`defaultOpen`	`boolean`	-	Whether the overlay is open by default (uncontrolled).
`allowsNonContiguousRanges`	`boolean`	-	When combined with isDateUnavailable, determines whether non-contiguous ranges, i.e. ranges containing unavailable dates, may be selected.
`startName`	`string`	-	The name of the start date input element, used when submitting an HTML form.
`endName`	`string`	-	The name of the end date input element, used when submitting an HTML form.
`validate`	`(value: RangeValue<MappedDateValue<DateValue>>) => ValidationError \| true \| null \| undefined`	-	A function that returns an error message if a given value is invalid. Validation errors are displayed to the user when the form is submitted if validationBehavior="native". For realtime validation, use the isInvalid prop instead.
`value`	`RangeValue<DateValue> \| null`	-	The current value (controlled).
`defaultValue`	`RangeValue<DateValue> \| null`	-	The default value (uncontrolled).
`shouldCloseOnSelect`	`boolean \| () => boolean`	`true`	Determines whether the date picker popover should close automatically when a date is selected.
`validationBehavior`	`'native' \| 'aria'`	`'aria'`	Whether to use native HTML form validation to prevent form submission when the value is missing or invalid, or mark the field as required or invalid via ARIA.
`children`	`ReactNode \| (values: DatePickerRenderProps & {defaultChildren: ReactNode \| undefined}) => ReactNode`	-	The children of the component. A function may be provided to alter the children based on component state.
`className`	`string`	-	The CSS className for the element.
`style`	`CSSProperties \| (values: DatePickerRenderProps & {defaultStyle: CSSProperties}) => CSSProperties`	-	The inline style for the element. A function may be provided to compute the style based on component state.

Event	Type	Description
`onFocus`	`(e: FocusEvent<Target>) => void`	Handler that is called when the element receives focus.
`onBlur`	`(e: FocusEvent<Target>) => void`	Handler that is called when the element loses focus.
`onFocusChange`	`(isFocused: boolean) => void`	Handler that is called when the element's focus status changes.
`onKeyDown`	`(e: KeyboardEvent) => void`	Handler that is called when a key is pressed.
`onKeyUp`	`(e: KeyboardEvent) => void`	Handler that is called when a key is released.
`onOpenChange`	`(isOpen: boolean) => void`	Handler that is called when the overlay's open state changes.
`onChange`	`(value: MappedDateValue<DateValue>) => void`	Handler that is called when the value changes.

Data attribute	Description
`[data-focus-within]`	Whether an element within the date picker is focused, either via a mouse or keyboard.
`[data-focus-visible]`	Whether an element within the date picker is keyboard focused.
`[data-disabled]`	Whether the date picker is disabled.
`[data-invalid]`	Whether the date picker is invalid.
`[data-open]`	Whether the date picker is open.

Last updated on 10/11/2024

Date Picker Color Area

Buttons

Inputs

Menus and selection

Dates

Colors

Drag and drop

Feedback

Layout

Data display

Navigation

Overlay

Date Range Picker

Installation

Usage

Options

Label

Size

Prefix

Description

Contextual help

Error message

Time zones

Granularity

Placeholder value

Hide time zone

Hour cycle

Loading

Disabled

ReadOnly

Required

Uncontrolled

Controlled

Composition

API Reference