DatePicker

DatePicker is used when the user has to select a date or date range.
DatePicker is distributed in its own package and must be installed separately.

also known as Calendar

Figma:

Ready

Web:

iOS:

Android:

A11y:

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.
`name`	`string`	-
	A unique name for the input.
`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.
`selectLists`	`$ReadOnlyArray<"month" \| "year">`	-
	Show a select list for quick selection of year and/or month. See the selectLists variant 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”.

Accessibility

Ready

Variants

Basic Date Picker

Use DatePicker to select date inputs.

function DatePickerExample() {
  const handleChange = (value) => value;

  return (
    <DatePicker
      id="example-basic"
      label="Select a date"
      onChange={({value}) => handleChange(value)}
    />
  )
}

function DatePickerExample() {
  const handleChange = (value) => value;

  return (
    <DatePicker
      id="example-basic"
      label="Select a date"
      onChange={({value}) => handleChange(value)}
    />
  )
}

Preselected Date

Provide pre-selected date values to DatePicker.

function DatePickerExample() {
  const handleChange = (value) => value;

  return (
    <DatePicker
      id="example-preselected value"
      label="Alberto's birth date"
      onChange={({value}) => handleChange(value)}
      value={new Date(1985,6,4)}
    />
  )
}

function DatePickerExample() {
  const handleChange = (value) => value;

  return (
    <DatePicker
      id="example-preselected value"
      label="Alberto's birth date"
      onChange={({value}) => handleChange(value)}
      value={new Date(1985,6,4)}
    />
  )
}

Date Range Picker

Use DatePicker to select date range inputs.

function DatePickerRangeExample() {
  const [startDate, setStartDate] = React.useState(undefined);
  const [endDate, setEndDate] = React.useState(undefined);
  const endDateInput = React.useRef(null)
  const startDateInput = React.useRef(null)

  return (
    <Flex gap={{ column: 0, row: 2 }}>
      <DatePicker
        rangeStartDate={startDate}
        rangeEndDate={endDate}
        id="example-start-date"
        label="Check In"
        nextRef={endDateInput}
        onChange={({ event, value }) => {
          setStartDate(value);
        }}
        rangeSelector="start"
        value={startDate}
        ref={startDateInput}
      />
      <DatePicker
        rangeStartDate={startDate}
        rangeEndDate={endDate}
        id="example-end-date"
        label="Check Out"
        nextRef={startDateInput}
        onChange={({ event, value }) => setEndDate(value)}
        rangeSelector="end"
        value={endDate}
        ref={endDateInput}
      />
    </Flex>
  );
}

function DatePickerRangeExample() {
  const [startDate, setStartDate] = React.useState(undefined);
  const [endDate, setEndDate] = React.useState(undefined);
  const endDateInput = React.useRef(null)
  const startDateInput = React.useRef(null)

  return (
    <Flex gap={{ column: 0, row: 2 }}>
      <DatePicker
        rangeStartDate={startDate}
        rangeEndDate={endDate}
        id="example-start-date"
        label="Check In"
        nextRef={endDateInput}
        onChange={({ event, value }) => {
          setStartDate(value);
        }}
        rangeSelector="start"
        value={startDate}
        ref={startDateInput}
      />
      <DatePicker
        rangeStartDate={startDate}
        rangeEndDate={endDate}
        id="example-end-date"
        label="Check Out"
        nextRef={startDateInput}
        onChange={({ event, value }) => setEndDate(value)}
        rangeSelector="end"
        value={endDate}
        ref={endDateInput}
      />
    </Flex>
  );
}

Disabled

function DatePickerExample() {
  const [date, setDate] = React.useState(new Date());

  return (
    <DatePicker
      disabled
      id="example-disabled"
      label="User Activation Date"
      onChange={({value}) => setDate(value)}
      value={date}
    />
  )
}

function DatePickerExample() {
  const [date, setDate] = React.useState(new Date());

  return (
    <DatePicker
      disabled
      id="example-disabled"
      label="User Activation Date"
      onChange={({value}) => setDate(value)}
      value={date}
    />
  )
}

Delimited selection period

Disable dates outside of a min and max date range.

function DatePickerExample() {
  const handleChange = (value) => value;

  return (
    <DatePicker
      id="example-maxMinDates"
      minDate={new Date(2020, 6, 6)}
      maxDate={new Date(2020, 6, 10)}
      label="Select a date"
      onChange={({value}) => handleChange(value)}
    />
  )
}

function DatePickerExample() {
  const handleChange = (value) => value;

  return (
    <DatePicker
      id="example-maxMinDates"
      minDate={new Date(2020, 6, 6)}
      maxDate={new Date(2020, 6, 10)}
      label="Select a date"
      onChange={({value}) => handleChange(value)}
    />
  )
}

Enabled dates

Enable an array of dates.

function DatePickerExample() {
  const handleChange = (value) => value;

  return (
    <DatePicker
      id="example-include"
      includeDates={[new Date(2020,2,11), new Date(2020,2,15)]}
      label="Select Your Appointment"
      onChange={({value}) => handleChange(value)}
    />
  )
}

function DatePickerExample() {
  const handleChange = (value) => value;

  return (
    <DatePicker
      id="example-include"
      includeDates={[new Date(2020,2,11), new Date(2020,2,15)]}
      label="Select Your Appointment"
      onChange={({value}) => handleChange(value)}
    />
  )
}

Disabled dates

Disable an array of dates.

function DatePickerExample() {
  const handleChange = (value) => value;

  return (
    <DatePicker
      id="example-exclude"
      excludeDates={[new Date(2020,2,11), new Date(2020,2,12)]}
      label="Select Your Appointment"
      onChange={({value}) => handleChange(value)}
      value={new Date(2020,2,9)}
    />
  )
}

function DatePickerExample() {
  const handleChange = (value) => value;

  return (
    <DatePicker
      id="example-exclude"
      excludeDates={[new Date(2020,2,11), new Date(2020,2,12)]}
      label="Select Your Appointment"
      onChange={({value}) => handleChange(value)}
      value={new Date(2020,2,9)}
    />
  )
}

Helper Text

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

function DatePickerExample() {
  return (
    <DatePicker
      helperText="Select a wonderfully sunny wedding date."
      id="example-helperText"
      label="Wedding Date"
      onChange={() => {}}
      value={new Date()}
    />
  )
}

function DatePickerExample() {
  return (
    <DatePicker
      helperText="Select a wonderfully sunny wedding date."
      id="example-helperText"
      label="Wedding Date"
      onChange={() => {}}
      value={new Date()}
    />
  )
}

Error Message

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

function DatePickerExample() {
  const [date, setDate] = React.useState(undefined);

  return (
    <DatePicker
      errorMessage={!date ? "This field can't be blank!" : null}
      helperText="Select a preferred day for your training."
      id="example-errorMessage"
      label="Schedule Your Training"
      onChange={({value}) => setDate(value)}
    />
  )
}

function DatePickerExample() {
  const [date, setDate] = React.useState(undefined);

  return (
    <DatePicker
      errorMessage={!date ? "This field can't be blank!" : null}
      helperText="Select a preferred day for your training."
      id="example-errorMessage"
      label="Schedule Your Training"
      onChange={({value}) => setDate(value)}
    />
  )
}

selectLists

Provide select lists for quickly changing year and month

import { useState } from 'react';
import { Flex, SegmentedControl } from 'gestalt';
import { DatePicker } from 'gestalt-datepicker';

export default function Example() {
  const mapOptions = { 0: ['month'], 1: ['year'], 2: ['year', 'month'] };
  const items = ['Month', 'Year', 'Month & Year'];
  const [itemIndex, setItemIndex] = useState(0);

  return (
    <Flex direction="column" gap={4} width="100%">
      <SegmentedControl
        items={items}
        selectedItemIndex={itemIndex}
        onChange={({ activeIndex }) => setItemIndex(activeIndex)}
      />
      <DatePicker
        id="selectLists"
        label="Alberto's birth date"
        onChange={() => {}}
        value={new Date(1985, 6, 4)}
        selectLists={mapOptions[itemIndex.toString()]}
      />
    </Flex>
  );
}

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"

Direction down

idealDirection="left"

Direction left

idealDirection="right"

Direction right

idealDirection="up"

Direction up

Supporting 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="af"

Afrikaans

localeDataCode="ar-SA"

Arabic (Saudi Arabia)

localeDataCode="bg"

Bulgarian

localeDataCode="cs-CZ"

Czech

localeDataCode="da-DK"

Danish

localeDataCode="de"

German

localeDataCode="el-GR"

Greek

localeDataCode="en-GB"

English (British)

localeDataCode="en-US"

English (US)

localeDataCode="es"

Spanish

localeDataCode="fi-FI"

Finnish

localeDataCode="fr"

French

localeDataCode="he"

Hebrew

localeDataCode="hi-IN"

Hindi

localeDataCode="hr"

Croatian

localeDataCode="hu-HU"

Hungarian

localeDataCode="id-ID"

Indonesian

localeDataCode="it"

Italian

localeDataCode="ja"

Japanese

localeDataCode="ko-KR"

Korean

localeDataCode="ms-MY"

Malay

localeDataCode="nb-NO"

Norwegian (Bokmål)

localeDataCode="nl"

Dutch

localeDataCode="pl-PL"

Polish (Poland)

localeDataCode="pt-BR"

Portuguese (Brazilian)

localeDataCode="pt-PT"

Portuguese (Portugal)

localeDataCode="ro-RO"

Romanian

localeDataCode="ru-RU"

Russian

localeDataCode="sk-SK"

Slovak

localeDataCode="sv-SE"

Swedish

localeDataCode="th-TH"

Thai

localeDataCode="tr"

Turkish

localeDataCode="uk-UA"

Ukrainian

localeDataCode="vi-VN"

Vietnamese

localeDataCode="zh-CN"

Chinese (Simplified)

localeDataCode="zh-TW"

Chinese (Traditional)

Component quality checklist

Component quality checklist
Quality item	Status	Status description
Figma Library	Ready	Component is available in Figma across all platforms.
Responsive Web	Ready	Component is available in code for web and mobile web.
iOS		Component is not currently available in code for iOS.
Android		Component is not currently available in code for Android.

Edit page on GitHub

; Opens a new tab