Use Datepicker when the user has to select a date or date range.

Props

Name
Type
Default
id
Required
string
-
onChange
Required
({event: SyntheticInputEvent<>, value: Date }) => void
-
boolean
-
string
-
Array<Date>
-

Array of disabled dates.

string
-

More information about how to complete the date picker field.

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

Preferred direction for the calendar popover to open.

Array<Date>
-

Array of enabled dates.

label
string
-
date-fns locale objects
-

DatePicker accepts imported locales from the open source date utility library date-fns.

Date
-

Disable dates outside a max date.

Date
-

Disable dates outside a min date.

React.ElementRef
-

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

placeholder
string
"date format for locale"
Date
-

Required for date range selection. End date on a date range selection.

"start"|"end"
-

Required for date range selection. Defines the datepicker start/end role in a date range selection.

Date
-

Required for date range selection. Start date on a date range selection.

React.ElementRef
-

Required for date range selection. Pass a ref object to DatePicker to autofocus on the unselected date range field.

Date
-

Pre-selected date value.

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.

Select a wonderfully sunny wedding date.

Example: Error Message

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

This field can't be blank!

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"