Date Time Picker

Basic Usage

The DateTimePicker component combines a text input with a popover containing a calendar and time picker for selecting date and time values.

Appointment

import { useState } from "react"
import { DateTimePicker } from "@epilot/volt-ui"

const MyComponent = () => {
  const [value, setValue] = useState<Date>(new Date())

  return (
    <DateTimePicker
      label="Appointment"
      value={value}
      onChange={setValue}
      locale="en"
    />
  )
}

Disable Past Dates

Use the disablePast prop to prevent selection of dates and times in the past.

Future Date Only

<DateTimePicker
  label="Future Date Only"
  value={value}
  onChange={setValue}
  disablePast
/>

With Error State

Pass an error prop to display validation errors.

Date & Time

Please select a valid date

<DateTimePicker
  label="Date & Time"
  value={value}
  onChange={setValue}
  error="Please select a valid date"
/>

Localization

The component supports multiple locales (en, de, fr) for month names, weekday labels, and date formatting.

Termin

<DateTimePicker
  label="Termin"
  value={value}
  onChange={setValue}
  locale="de"
  format="dd.MM.yyyy HH:mm"
  placeholder="tt.mm.jjjj hh:mm"
/>

With Today Button

Enable the "Today" button to allow users to quickly select the current date.

Select Date

<DateTimePicker
  label="Select Date"
  value={value}
  onChange={setValue}
  showTodayButton
  todayLabel="Today"
/>

Side Layout

Use timePickerPosition="side" to place the time picker next to the calendar instead of below it.

Side Layout

<DateTimePicker
  label="Side Layout"
  value={value}
  onChange={setValue}
  timePickerPosition="side"
/>

Side Layout with Today Button

When using timePickerPosition="side" together with showTodayButton, the time picker automatically adjusts its height to match the calendar including the Today button.

Side Layout + Today

<DateTimePicker
  label="Side Layout + Today"
  value={value}
  onChange={setValue}
  timePickerPosition="side"
  showTodayButton
  todayLabel="Today"
/>

API Reference

DateTimePicker

The main component that combines input, calendar, and time picker.

Prop	Type	Default	Description
`value`	`Date`	-	The selected date and time value.
`onChange`	`(date: Date) => void`	-	Callback fired when the date/time changes.
`onBlur`	`() => void`	-	Callback fired when the input loses focus.
`disabled`	`boolean`	`false`	When true, the picker is disabled.
`disablePast`	`boolean`	`false`	When true, past dates and times cannot be selected.
`label`	`string`	-	Label text displayed above the input.
`error`	`string`	-	Error message to display below the input.
`placeholder`	`string`	`"dd/mm/yyyy hh:mm"`	Placeholder text for the input.
`format`	`string`	`"dd/MM/yyyy HH:mm"`	Date format string (uses date-fns format tokens).
`locale`	`"en" \| "de" \| "fr"`	`"de"`	Locale for month/day names and formatting.
`className`	`string`	-	Additional CSS classes for the container.
`keyboardIcon`	`ReactNode`	`<CalendarIcon />`	Custom icon for the calendar button.
`okLabel`	`string`	`"OK"`	Label for the OK button.
`cancelLabel`	`string`	`"Cancel"`	Label for the Cancel button.
`inputAriaLabel`	`string`	`"change date and time"`	Aria-label for the input field.
`openPickerAriaLabel`	`string`	`"Open date picker"`	Aria-label for the calendar button.
`previousMonthLabel`	`string`	`"Previous month"`	Aria-label for the previous month button.
`nextMonthLabel`	`string`	`"Next month"`	Aria-label for the next month button.
`hoursLabel`	`string`	`"HH"`	Label for the hours column.
`minutesLabel`	`string`	`"MM"`	Label for the minutes column.
`showTodayButton`	`boolean`	`false`	When true, shows a "Today" button below the calendar.
`todayLabel`	`string`	`"Today"`	Label for the Today button.
`testId`	`string`	-	Test ID for the input (sets `data-testid`).
`currentTimeInTimezone`	`Date`	-	Override "now" for timezone-aware past checks.
`timePickerPosition`	`"bottom" \| "side"`	`"bottom"`	Position the time picker below or beside the calendar.

Standalone calendar component for date selection. The calendar supports drill-down navigation: click the month/year header to switch to a month picker, then click the year to switch to a decade/year picker. This allows quick navigation to any date without repeated arrow clicks.

Prop	Type	Default	Description
`value`	`Date`	-	The selected date.
`onChange`	`(date: Date) => void`	-	Callback fired when a date is selected.
`onDateSelect`	`() => void`	-	Callback fired after date selection (for closing picker).
`disablePast`	`boolean`	`false`	When true, past dates are disabled.
`locale`	`"en" \| "de" \| "fr"`	`"de"`	Locale for month/day names.
`previousMonthLabel`	`string`	`"Previous month"`	Aria-label for the previous month button.
`nextMonthLabel`	`string`	`"Next month"`	Aria-label for the next month button.
`showTodayButton`	`boolean`	`false`	When true, shows a "Today" button below the calendar.
`todayLabel`	`string`	`"Today"`	Label for the Today button.
`currentTimeInTimezone`	`Date`	-	Override "now" for timezone-aware past checks.

TimePicker

Standalone time picker component with scrollable hour and minute columns.

Prop	Type	Default	Description
`value`	`Date`	-	The date object containing the time to display.
`onChange`	`(date: Date) => void`	-	Callback fired when time changes.
`onTimeSelect`	`() => void`	-	Callback fired after time selection.
`disablePast`	`boolean`	`false`	When true, past times are disabled (only on current day).
`locale`	`"en" \| "de" \| "fr"`	`"de"`	Locale (reserved for future use).
`hoursLabel`	`string`	`"HH"`	Label for the hours column.
`minutesLabel`	`string`	`"MM"`	Label for the minutes column.
`currentTimeInTimezone`	`Date`	-	Override "now" for timezone-aware past checks.

Dependencies

This component uses date-fns for date manipulation and formatting, which is included as a dependency of @epilot/volt-ui.

Date Time Picker

On this page