DatePicker

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

Props

Component props
Name	Type	Default
`id` Required	`string`	-
`onChange` Required	`({event: SyntheticInputEvent<>, value: Date }) => void`	-
`disabled`	`boolean`	-
`errorMessage`	`string`	-
`excludeDates`	`Array<Date>`	-
	Array of disabled dates.
`helperText`	`string`	-
	More information about how to complete the date picker field.
`idealDirection`	`"up"\|"right"\|"down"\|"left"`	`"down"`
	Preferred direction for the calendar popover to open.
`includeDates`	`Array<Date>`	-
	Array of enabled dates.
`label`	`string`	-
`localeData`	`date-fns locale objects`	-
	DatePicker accepts imported locales from the open source date utility library date-fns.
`maxDate`	`Date`	-
	Disable dates outside a max date.
`minDate`	`Date`	-
	Disable dates outside a min date.
`nextRef`	`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"`
`rangeEndDate`	`Date`	-
	Required for date range selection. End date on a date range selection.
`rangeSelector`	`"start"\|"end"`	-
	Required for date range selection. Defines the datepicker start/end role in a date range selection.
`rangeStartDate`	`Date`	-
	Required for date range selection. Start date on a date range selection.
`ref`	`React.ElementRef`	-
	Required for date range selection. Pass a ref object to DatePicker to autofocus on the unselected date range field.
`value`	`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.

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)}
    />
  )
}

Example: 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)}
    />
  )
}

Example: 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={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={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>
  );
}

Example: 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}
    />
  )
}

Example: 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)}
    />
  )
}

Example: 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)}
    />
  )
}

Example: 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)}
    />
  )
}

Example: 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()}
    />
  )
}

Example: 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)}
    />
  )
}

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"

Direction down

idealDirection="left"

Direction left

idealDirection="right"

Direction right

idealDirection="up"

Direction 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"

Arabic (Saudi Arabia)

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="hi-IN"

Hindi

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)

Edit page on GitHub