DocsComponents

Date picker

Choose a date from a familiar Material calendar.

Start date

Installation

Terminal

pnpm dlx shadcn@latest add https://react-toolbox.io/r/date-picker.json

New here? Set up your project first. Styles, fonts, and required components are included.

Usage

Values are JavaScript Date objects. Use minDate and maxDate to limit the range. The registry includes the input, dialog, and supporting components.

Use the Code tab above for a complete example. The import follows your configured UI alias. See Theming to customize colors, spacing, and style slots.

State and callbacks

The selected date is controlled: pass a Date as value and update it in onChange. There is no defaultValue API. The dialog keeps a draft selection until confirmation; autoOk confirms a day selection immediately.

The input manages opening and closing internally. Changes to active synchronize its open state; onDismiss reports dismissal. DatePickerDialog can be used directly when your application owns the whole dialog lifecycle.

API reference

Generated from the installed TypeScript source. Defaults are the values declared by each function; a dash means no parameter default is declared. Forwarded props can use the receiving component’s default. Callback types show the exact arguments passed to your handler.

`DatePicker`

Property	Type	Default
`error`	`React.ReactNode`	`—`
`floating`	`boolean`	`—`
`hint`	`React.ReactNode`	`—`
`icon`	`React.ReactNode`	`—`
`label`	`React.ReactNode`	`—`
`multiline`	`boolean`	`—`
`rows`	`number`	`—`
`ref`	`React.Ref<InputHandle>`	`—`
`minDate`	`Date`	`—`
`maxDate`	`Date`	`—`
`enabledDates`	`readonly Date[]`	`—`
`disabledDates`	`readonly Date[]`	`—`
`active`	`boolean`	`false`
`autoOk`	`boolean`	`—`
`cancelLabel`	`string`	`—`
`inputClassName`	`string`	`—`
`locale`	`DatePickerLocale`	`'en'`
`okLabel`	`string`	`—`
`readonly`	`boolean`	`—`
`sundayFirstDayOfWeek`	`boolean`	`false`
`classNames`	`DatePickerTheme` Classes for the component's rendered parts. Applied after legacy theme overrides.	`—`
`theme`Deprecated alias	`DatePickerTheme` Use classNames for style slots; use ThemeProvider for design tokens.	`—`
`value`	`Date \| string`	`—`

Callbacks

Property	Type	Default
`inputFormat`	`(date: Date, locale?: DatePickerLocale) => string`	`time.formatDate`
`onChange`	`(date: Date, event?: React.MouseEvent<HTMLElement> \| React.KeyboardEvent<HTMLElement>) => void`	`—`
`onDismiss`	`() => void`	`—`
`onEscKeyDown`	`(event: KeyboardEvent) => void`	`—`
`onOverlayClick`	`MouseEventHandler<HTMLDivElement>`	`—`

Also inherits Omit<Omit<React.InputHTMLAttributes<InputElement>, 'onChange' | 'size'>, 'value' | 'defaultValue' | 'onChange' | 'theme' | 'classNames'>, except the omissions and overrides in its exported props type below. Use the supported native aria-*, data-*, event, and element attributes as appropriate.

Style slots

Pass a map of Tailwind classes to classNames. Available keys:

active
button
calendar
calendarWrapper
container
date
day
days
dialog
disabled
header
input
inputElement
month
monthsDisplay
next
prev
slideLeftEnter
slideLeftEnterActive
slideLeftExit
slideLeftExitActive
slideRightEnter
slideRightEnterActive
slideRightExit
slideRightExitActive
title
week
year
years
yearsDisplay

theme is the deprecated compatibility alias. When both are provided, classNames wins conflicting utilities within each slot. See Theming for tokens and override rules.

`DatePickerDialog`

Property	Type	Default
`minDate`	`Date`	`—`
`maxDate`	`Date`	`—`
`enabledDates`	`readonly Date[]`	`—`
`disabledDates`	`readonly Date[]`	`—`
`active`	`boolean`	`false`
`autoOk`	`boolean`	`—`
`cancelLabel`	`string`	`'Cancel'`
`className`	`string`	`''`
`id`	`string`	`—`
`locale`	`DatePickerLocale`	`—`
`name`	`string`	`—`
`okLabel`	`string`	`'Ok'`
`sundayFirstDayOfWeek`	`boolean`	`—`
`classNames`	`DatePickerTheme` Classes for the component's rendered parts. Applied after legacy theme overrides.	`—`
`theme`Deprecated alias	`DatePickerTheme` Use classNames for style slots; use ThemeProvider for design tokens.	`—`
`value`	`Date`	`—`

Callbacks

Property	Type	Default
`onDismiss`	`() => void`	`—`
`onEscKeyDown`	`(event: KeyboardEvent) => void`	`—`
`onOverlayClick`	`MouseEventHandler<HTMLDivElement>`	`—`
`onSelect`	`(date: Date, event?: React.MouseEvent<HTMLElement> \| React.KeyboardEvent<HTMLElement>) => void`	`—`

Style slots

Pass a map of Tailwind classes to classNames. Available keys:

active
button
calendar
calendarWrapper
container
date
day
days
dialog
disabled
header
input
inputElement
month
monthsDisplay
next
prev
slideLeftEnter
slideLeftEnterActive
slideLeftExit
slideLeftExitActive
slideRightEnter
slideRightEnterActive
slideRightExit
slideRightExitActive
title
week
year
years
yearsDisplay

theme is the deprecated compatibility alias. When both are provided, classNames wins conflicting utilities within each slot. See Theming for tokens and override rules.

`Calendar`

Property	Type	Default
`minDate`	`Date`	`—`
`maxDate`	`Date`	`—`
`enabledDates`	`readonly Date[]`	`—`
`disabledDates`	`readonly Date[]`	`—`
`display`	`'months' \| 'years'`	`'months'`
`locale`	`DatePickerLocale`	`—`
`selectedDate`	`Date`	`—`
`sundayFirstDayOfWeek`	`boolean`	`—`
`classNames`	`DatePickerTheme` Classes for the component's rendered parts. Applied after legacy theme overrides.	`—`
`theme`Deprecated alias	`DatePickerTheme` Use classNames for style slots; use ThemeProvider for design tokens.	`—`

Callbacks

Property	Type	Default
`handleSelect`	`(event: React.KeyboardEvent<HTMLElement>) => void`	`—`
`onChange`	`(date: Date, dayClick: boolean) => void`	`—`

Style slots

Pass a map of Tailwind classes to classNames. Available keys:

active
button
calendar
calendarWrapper
container
date
day
days
dialog
disabled
header
input
inputElement
month
monthsDisplay
next
prev
slideLeftEnter
slideLeftEnterActive
slideLeftExit
slideLeftExitActive
slideRightEnter
slideRightEnterActive
slideRightExit
slideRightExitActive
title
week
year
years
yearsDisplay

theme is the deprecated compatibility alias. When both are provided, classNames wins conflicting utilities within each slot. See Theming for tokens and override rules.

Exported TypeScript types

Expand a type to inspect its full declaration, including generic constraints, union branches, callback arguments, ref handles, and inherited props. Import these types from @/components/ui/material/date-picker.

DatePickerTheme

tsx

type DatePickerTheme = Partial<
  Record<
    | 'container'
    | 'active'
    | 'button'
    | 'calendar'
    | 'calendarWrapper'
    | 'date'
    | 'day'
    | 'days'
    | 'dialog'
    | 'disabled'
    | 'header'
    | 'input'
    | 'inputElement'
    | 'month'
    | 'monthsDisplay'
    | 'next'
    | 'prev'
    | 'slideLeftEnter'
    | 'slideLeftEnterActive'
    | 'slideLeftExit'
    | 'slideLeftExitActive'
    | 'slideRightEnter'
    | 'slideRightEnterActive'
    | 'slideRightExit'
    | 'slideRightExitActive'
    | 'title'
    | 'week'
    | 'year'
    | 'years'
    | 'yearsDisplay',
    string
  >
>;

DatePickerClassNames

tsx

type DatePickerClassNames = DatePickerTheme;

DatePickerProps

tsx

interface DatePickerProps
  extends Omit<InputProps, 'value' | 'defaultValue' | 'onChange' | 'theme' | 'classNames'>,
    DateConstraints {
  active?: boolean;
  autoOk?: boolean;
  cancelLabel?: string;
  inputClassName?: string;
  inputFormat?: (date: Date, locale?: DatePickerLocale) => string;
  locale?: DatePickerLocale;
  okLabel?: string;
  onChange?: (date: Date, event?: DatePickerSelectEvent) => void;
  onDismiss?: () => void;
  onEscKeyDown?: DatePickerDialogProps['onEscKeyDown'];
  onOverlayClick?: DatePickerDialogProps['onOverlayClick'];
  readonly?: boolean;
  sundayFirstDayOfWeek?: boolean;
  /** Classes for the component's rendered parts. Applied after legacy theme overrides. */
  classNames?: DatePickerTheme;
  /** @deprecated Use classNames for style slots; use ThemeProvider for design tokens. */
  theme?: DatePickerTheme;
  value?: Date | string;
}

DatePickerLocale

tsx

type DatePickerLocale = string | DateLocale;

Material guidelines

Use a calendar when the relationship between days helps someone choose a date. Distinguish today from the selected day.
Keep selection provisional until confirmation, with clear Cancel and OK actions. Disable unavailable dates consistently.

Material Design 1: Pickers