DatePicker is used when the user has to select a date or date range.

Props

Component props
Name
Type
Default
id
Required
string
-

A unique identifier for the input.

onChange
Required
({| event: SyntheticInputEvent<HTMLInputElement>, value: Date, |}) => void
-

Callback triggered when the user selects a date.

disabled
boolean
-

When disabled, DatePicker looks inactive and cannot be interacted with. See the disabled example to learn more.

errorMessage
string
-

Provide feedback when an error on selection occurs. See the error message example to learn more.

excludeDates
$ReadOnlyArray<Date>
-

Array of disabled dates. Datepicker can be interacted with except for the dates passed which look inactive and cannot be selected. See the disabled dates example to learn more.

helperText
string
-

More information about how to complete the DatePicker field. See the helper text example to learn more.

idealDirection
"up" | "right" | "down" | "left"
"down"

Preferred direction for the calendar popover to open. See the ideal direction example to learn more.

includeDates
$ReadOnlyArray<Date>
-

Array of enabled dates. Datepicker can be interacted with only on the dates passed, all other dates look inactive and cannot be selected. See the disabled dates example to learn more.

label
string
-

Provide a label to identify the DatePicker field.

localeData
{| code?: string, formatDistance?: (...args: $ReadOnlyArray<any>) => any, formatRelative?: (...args: $ReadOnlyArray<any>) => any, localize?: {| ordinalNumber: (...args: $ReadOnlyArray<any>) => any, era: (...args: $ReadOnlyArray<any>) => any, quarter: (...args: $ReadOnlyArray<any>) => any, month: (...args: $ReadOnlyArray<any>) => any, day: (...args: $ReadOnlyArray<any>) => any, dayPeriod: (...args: $ReadOnlyArray<any>) => any, |}, formatLong?: {| date: (...args: $ReadOnlyArray<any>) => any, time: (...args: $ReadOnlyArray<any>) => any, dateTime: (...args: $ReadOnlyArray<any>) => any, |}, match?: {| ordinalNumber: (...args: $ReadOnlyArray<string>) => any, era: (...args: $ReadOnlyArray<any>) => any, quarter: (...args: $ReadOnlyArray<any>) => any, month: (...args: $ReadOnlyArray<any>) => any, day: (...args: $ReadOnlyArray<any>) => any, dayPeriod: (...args: $ReadOnlyArray<any>) => any, |}, options?: {| weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6, firstWeekContainsDate?: 1 | 2 | 3 | 4 | 5 | 6 | 7, |}, |}
-

DatePicker accepts imported locales from the open source date utility library date-fns. See the locales example to learn more.

maxDate
Date
-

Disable dates outside a max date. See the delimited selection period example to learn more.

minDate
Date
-

Disable dates outside a min date. See the delimited selection period example to learn more.

nextRef
{| current: ?HTMLInputElement |}
-

Required for date range selection. Pass the complimentary range date picker ref object to DatePicker to autofocus on the unselected date range field. See the date range picker example to learn more.

placeholder
string
-

Placeholder text shown if the user has not yet input a value. The default placeholder value shows the date format for each locale, e.g. MM/DD/YYYY.

rangeEndDate
Date
-

Required for date range selection. End date on a date range selection. See the date range picker example to learn more.

rangeSelector
"start" | "end"
-

Required for date range selection. Defines the datepicker start/end role in a date range selection.See the date range picker example to learn more.

rangeStartDate
Date
-

Required for date range selection. Start date on a date range selection. See the date range picker example to learn more.

ref
React.Element<"input">
-

Required for date range selection. Pass a ref object to DatePicker to autofocus on the unselected date range field. See the date range picker example to learn more.

value
Date
-

Pre-selected date value. See the preselected date example to learn more.

Usage guidelines

When to Use
  • Allowing users to choose a date or date range by clicking through the calendar popup or typing in the text field.
  • Limiting date options to a specific range of dates.
When Not to Use
  • When the native date picking experience is preferred (typically mobile and mWeb experiences). In this case, use TextField with type=”date”.

Example: Basic Date Picker

Use DatePicker to select date inputs.

Example: Preselected Date

Provide pre-selected date values to DatePicker.

Example: Date Range Picker

Use DatePicker to select date range inputs.

Example: Disabled

Example: Delimited selection period

Disable dates outside of a min and max date range.

Example: Enabled dates

Enable an array of dates.

Example: Disabled dates

Disable an array of dates.

Example: Helper Text

Display a helper message for cases where you want to provide more information about the date field.

Example: Error Message

Display an error message. Error message overrides the helper text.

Example: Ideal Direction

Define the preferred direction for the DatePicker popover to open. If that placement doesn't fit, the opposite direction will be used.

idealDirection="down"
idealDirection="left"
idealDirection="right"
idealDirection="up"

Example: Locales

Adjust the date format to each date-fns locale (https://date-fns.org/v2.14.0/docs/Locale).
The following locale examples show the different locale format variants.
IMPORTANT: Locale data from date-fns is external to gestalt-datepicker, it's not an internal dependency. Add date-fns to your app's dependencies.

import DatePicker from 'gestalt-datepicker';
import { it } from 'date-fns/locale';
<DatePicker localeData={it}/>
localeDataCode="ar-SA"
localeDataCode="cs-CZ"
localeDataCode="da-DK"
localeDataCode="de"
localeDataCode="el-GR"
localeDataCode="en-GB"
localeDataCode="en-US"
localeDataCode="es"
localeDataCode="fi-FI"
localeDataCode="fr"
localeDataCode="hi-IN"
localeDataCode="hu-HU"
localeDataCode="id-ID"
localeDataCode="it"
localeDataCode="ja"
localeDataCode="ko-KR"
localeDataCode="ms-MY"
localeDataCode="nb-NO"
localeDataCode="nl"
localeDataCode="pl-PL"
localeDataCode="pt-BR"
localeDataCode="pt-PT"
localeDataCode="ro-RO"
localeDataCode="ru-RU"
localeDataCode="sk-SK"
localeDataCode="sv-SE"
localeDataCode="th-TH"
localeDataCode="tr"
localeDataCode="uk-UA"
localeDataCode="vi-VN"
localeDataCode="zh-CN"
localeDataCode="zh-TW"