DatePicker

Overview

import DatePicker from "react-widgets/DatePicker"; <DatePicker placeholder="m/dd/yy" />;

import DatePicker from "react-widgets/DatePicker";
<DatePicker placeholder="m/dd/yy" />;

Formatting

The format of dates can be adjusted per component. The exact type of a format is dependent on the configured localizer. It may be a string, as is the case for Luxon or DateFns, an options object passed to Intl directly. The default case uses the built-in Intl APIs.

<> <DatePicker defaultValue={new Date()} valueFormat={{ dateStyle: "medium" }} /> <br /> <DatePicker defaultValue={new Date()} valueFormat={{ month: "short", year: "numeric" }} calendarProps={{ views: ["year", "decade", "century"] }} /> </>;

<>
  <DatePicker
    defaultValue={new Date()}
    valueFormat={{ dateStyle: "medium" }}
  />
  <br />
  <DatePicker
    defaultValue={new Date()}
    valueFormat={{ month: "short", year: "numeric" }}
    calendarProps={{ views: ["year", "decade", "century"] }}
  />
</>;

Editing format

The best date format to read is not always the easier to input. You can provide differentiate between edit and display formats; the former is used while the input is focused.

<DatePicker defaultValue={new Date()} valueEditFormat={{ dateStyle: "short" }} valueDisplayFormat={{ dateStyle: "medium" }} />;

<DatePicker
  defaultValue={new Date()}
  valueEditFormat={{ dateStyle: "short" }}
  valueDisplayFormat={{ dateStyle: "medium" }}
/>;

Parsing date strings

When a user types a value into the textbox it need's to parsed into a proper Date object. The built-in parsing logic simply passes the value to new Date. This often works fine, but can produce confusing results given how varied of an input the Date constructor will accept. Localizer's may provide more structured parsing, if the backing library supports it. The parse prop provides another escape hatch for per component parse tweaking.

I18n: locales

The locale used by inputs is determined by the user's browser, you can manually configure it with the <Localization> Provider component.

const Locales = [ { label: "English: USA", culture: "en", firstOfWeek: 0, }, { label: "English: Great Britain", culture: "en-gb", firstOfWeek: 1, }, { label: "Spanish", culture: "es", firstOfWeek: 1, }, { label: "French", culture: "fr", firstOfWeek: 1, }, { label: "Arabic: U.A.E", culture: "ar-AE", firstOfWeek: 0, }, ]; const [current, setCurrent] = useState(Locales[1]); <Localization date={new DateLocalizer(current)}> <div className="mb-10 w-64"> <label>Select a locale:</label> <DropdownList textField="label" data={Locales} value={current} onChange={setCurrent} /> </div> <DatePicker defaultValue={new Date()} valueEditFormat={{ dateStyle: "short" }} valueDisplayFormat={{ dateStyle: "medium" }} /> </Localization>;

const Locales = [
  {
    label: "English: USA",
    culture: "en",
    firstOfWeek: 0,
  },
  {
    label: "English: Great Britain",
    culture: "en-gb",
    firstOfWeek: 1,
  },
  {
    label: "Spanish",
    culture: "es",
    firstOfWeek: 1,
  },
  {
    label: "French",
    culture: "fr",
    firstOfWeek: 1,
  },
  {
    label: "Arabic: U.A.E",
    culture: "ar-AE",
    firstOfWeek: 0,
  },
];
const [current, setCurrent] = useState(Locales[1]);
<Localization date={new DateLocalizer(current)}>
  <div className="mb-10 w-64">
    <label>Select a locale:</label>
    <DropdownList
      textField="label"
      data={Locales}
      value={current}
      onChange={setCurrent}
    />
  </div>
  <DatePicker
    defaultValue={new Date()}
    valueEditFormat={{ dateStyle: "short" }}
    valueDisplayFormat={{ dateStyle: "medium" }}
  />
</Localization>;

Date and time input

Date and time input is hard, and rarely does a single input meet all use cases well. To meet the variety of user needs, inputs can be combined and configured to support the input pattern that works best for your users.

<div className="flex flex-col items-start max-w-sm"> <label>A single "datetime" input</label> <DatePicker defaultValue={new Date()} includeTime /> <br /> <label>Paired picker and dropdown</label> <div className="flex space-x-2 w-full"> <DatePicker defaultValue={new Date()} className="w-3/5" /> <DropdownList data={getTimeList()} textField="label" className="w-2/5 mt-0" /> </div> <br /> <label>Paired picker and experimental time input</label> <div className="flex space-x-2 w-full"> <DatePicker defaultValue={new Date()} className="w-3/5" /> <TimeInput defaultValue={new Date()} className="w-2/5 mt-0" use12HourClock /> </div> </div>;

<div className="flex flex-col items-start max-w-sm">
  <label>A single "datetime" input</label>
  <DatePicker defaultValue={new Date()} includeTime />
  <br />
  <label>Paired picker and dropdown</label>
  <div className="flex space-x-2 w-full">
    <DatePicker
      defaultValue={new Date()}
      className="w-3/5"
    />
    <DropdownList
      data={getTimeList()}
      textField="label"
      className="w-2/5 mt-0"
    />
  </div>
  <br />
  <label>Paired picker and experimental time input</label>
  <div className="flex space-x-2 w-full">
    <DatePicker
      defaultValue={new Date()}
      className="w-3/5"
    />
    <TimeInput
      defaultValue={new Date()}
      className="w-2/5 mt-0"
      use12HourClock
    />
  </div>
</div>;

Keyboard Shortcuts

alt + down arrow

open calendar or time

alt + up arrow

close calendar or time

down arrow

move focus to next item

up arrow

move focus to previous item

home

move focus to first item

end

move focus to last item

enter

select focused item

any key

search list for item starting with key

API

autoFocus

Pass focus to the DatePicker when it mounts.

type: boolean

calendarProps

type: Partial<CalendarProps>

containerClassName

Adds a css class to the input container element.

type: string

currentDate

Default current date at which the calendar opens. If none is provided, opens at today's date or the value date (if any).

type: Date

defaultValue

type: Datenull

disabled

<DatePicker disabled defaultValue={new Date()} />

<DatePicker
  disabled
  defaultValue={new Date()}
/>

type: boolean

dropUp

Controls the opening direction of the DatePicker popup.

<DatePicker dropUp={true} />;

<DatePicker 
  dropUp={true}
/>;

type: boolean

formats

type: DateFormats<InferFormat<TLocalizer>>

default:{}

includeTime

Enable the time list component of the picker.

type: boolean

inputProps

An object of props that is passed directly to the underlying input component.

type: Partial<DatePickerInputProps>

max

The maximum Date that can be selected. Max only limits selection, it doesn't constrain the date values that can be typed or pasted into the widget. If you need this behavior you can constrain values via the onChange handler.

<DatePicker max={new Date()} />;

<DatePicker 
  max={new Date()}
/>;

type: Date

default:new Date(2099, 11, 31)

messages

Object hash containing display text and/or text for screen readers. Use the messages object to localize widget text or provide custom rendering.

type: intersection<CalendarProps['messages'], { dateButton?: string }>

min

The minimum Date that can be selected. Min only limits selection, it doesn't constrain the date values that can be typed or pasted into the widget. If you need this behavior you can constrain values via the onChange handler.

<DatePicker min={new Date()} />;

<DatePicker 
  min={new Date()}
/>;

type: Date

default:new Date(1900, 0, 1)

name

The HTML name attribute, passed directly to the input element.

type: string

onBlur

The native onBlur event, called when focus leaves the DatePicker entirely.

type: () => void

onChange

A callback fired when the current value changes.

function ChangeExample({ initialValue }) { const [value, setValue] = useState(initialValue) return ( <DatePicker value={value} onChange={value => setValue(value)} /> ) } <> <ChangeExample initialValue={new Date()} /> <ChangeExample initialValue={null} /> </>

function ChangeExample({ initialValue }) {
  const [value, setValue] = useState(initialValue)
  return (
    <DatePicker
      value={value}
      onChange={value => setValue(value)}
    />
  )
}
<>
  <ChangeExample initialValue={new Date()} />
  <ChangeExample initialValue={null} />
</>

type: (date: Datenullundefined, rawValue: string) => void

onCurrentDateChange

Change event Handler that is called when the currentDate is changed. The handler is called with the currentDate object.

type: () => void

onFocus

The native onFocus event, called when focus enters the DatePicker.

type: () => void

onKeyDown

The native onKeyDown event, called preventDefault will prevent any custom behavior, included keyboard shortcuts.

type: (e: ReactKeyboardEvent<HTMLDivElement>) => void

onKeyPress

The native onKeyPress event, called preventDefault will stop any custom behavior.

type: (e: ReactKeyboardEvent<HTMLDivElement>) => void

onSelect

This handler fires when an item has been selected from the list. It fires before the onChange handler and fires regardless of whether the value has actually changed.

let alertWhenSelected = () => alert('selected!'); let alertWhenChanged = () => alert('changed!'); <DatePicker onSelect={alertWhenSelected} onChange={alertWhenChanged} data={['Orange', 'Red', 'Blue', 'Purple']} />

let alertWhenSelected = () => alert('selected!');
let alertWhenChanged = () => alert('changed!');
<DatePicker
  onSelect={alertWhenSelected}
  onChange={alertWhenChanged}
  data={['Orange', 'Red', 'Blue', 'Purple']}
/>

type: (date: Datenull, rawValue: string) => void

onToggle

A callback fired with the DatePicker's popup visibility is about to change.

Use in conjunction with the open prop to manually control the popup visibility.

type: (isOpen: boolean) => void

open

Controls the visibility of the DatePicker popup. Use defaultOpen to set an initial value for uncontrolled widgets.

type: boolean

parse

Determines how the widget parses the typed date string into a Date object. You can provide an array of formats to try, or provide a function that returns a date to handle parsing yourself. When parse is unspecified and the format prop is a string parse will automatically use that format as its default.

let formats = [ 'MMM d yyyy', 'MMM d yy', 'd' ]; <> <DatePicker parse={formats}/> {/* the naive approach: just use the Date constructor */} <DatePicker parse={str => new Date(str)}/> <span>Try typing a date using the specified formats</span> </>

let formats = [
  'MMM d yyyy',
  'MMM d yy',
  'd'
];
<>
  <DatePicker parse={formats}/>
  {/* the naive approach: just use the Date constructor */}
  <DatePicker parse={str => new Date(str)}/>
  <span>Try typing a date using the specified formats</span>
</>

type: stringunknown

placeholder

Text to display in the input when the value is empty.

type: string

popupComponent

type: ReactComponentType<PopupProps>

popupProps

type: object

popupTransition

A Transition component from react-transition-group. The provided component will be used instead of the default SlideDownTransition for fully customizable animations. The transition component is also injected with a dropUp prop indicating the direction it should open.

type: ReactComponentType<TransitionProps>

readOnly

Controls the read-only state of the DatePicker.

<DatePicker readOnly defaultValue={new Date()} />

<DatePicker
  readOnly
  defaultValue={new Date()}
/>

type: boolean

selectIcon

Specify the element used to render the calendar dropdown icon.

type: ReactReactNode

default:calendar

step

The amount of minutes between each entry in the time list.

<DatePicker step={90} />;

<DatePicker 
  step={90}
/>;

type: number

timeInputProps

type: Partial<TimeInputProps>

timePrecision

type: 'minutes''seconds''milliseconds'

value

Controls the current value of the DatePicker.

<> <DatePicker defaultValue={new Date()} /> <DatePicker defaultValue={null} /> </>

<>
  <DatePicker defaultValue={new Date()} />
  <DatePicker defaultValue={null} />
</>

type: Datenull

valueDisplayFormat

A formatting options used to display the date value. For more information about formats visit the Localization page

<DatePicker defaultValue={new Date()} valueDisplayFormat={{ dateStyle: "medium" }} />

<DatePicker
  defaultValue={new Date()}
  valueDisplayFormat={{ dateStyle: "medium" }}
/>

type: InferFormat<TLocalizer>

valueEditFormat

A formatting options used while the date input has focus. Useful for showing a simpler format for inputing. For more information about formats visit the Localization page

<DatePicker defaultValue={new Date()} valueEditFormat={{ dateStyle: "short" }} valueDisplayFormat={{ dateStyle: "medium" }} />

<DatePicker
  defaultValue={new Date()}
  valueEditFormat={{ dateStyle: "short" }}
  valueDisplayFormat={{ dateStyle: "medium" }}
/>

type: InferFormat<TLocalizer>

valueFormat

A formatting options used to display the date value. This is a shorthand for setting both valueDisplayFormat and valueEditFormat.

type: InferFormat<TLocalizer>