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

Responsive:

Ready

Adaptive:

N/A

Props

Component props
Name	Type	Default
`id` Required	`string`	-
	A unique identifier for the input.
`onChange` Required	`(arg1: { event: React.ChangeEvent<HTMLInputElement>; value: Date \| null }) => 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.
`disableMobileUI`	`boolean`	`false`
	DatePicker can adapt to mobile devices to SheetMobile. Mobile adaptation is disabled by default. Set to 'false' to enable SheetMobile in mobile devices. See the mobile variant 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 disable selected 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 disable selected dates example to learn more.
`label`	`string`	-
	Provide a label to identify the DatePicker field.
`localeData`	`Locale`	-
	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 disable future and past example to learn more.
`minDate`	`Date`	-
	Disable dates outside a min date. See the disable future and past example to learn more.
`mobileOnAnimationEnd`	`(arg1: { animationState: "in" \| "out" }) => void`	-
	Callback fired when SheetMobile's in & out animations end. See SheetMobile's animation variant to learn more.
`mobileZIndex`	`Indexable`	-
	An object representing the zIndex value of the SheetMobile where DatePicker is built upon on mobile. Learn more about zIndex classes
`name`	`string`	-
	A unique name for the input.
`nextRef`	`{ current: null \| 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 \| null`	-
	Required for date range selection. End date on a date range selection. See the date range 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 \| null`	-
	Required for date range selection. Start date on a date range selection. See the date range picker example to learn more.
`readOnly`	`boolean`	-
	Indicate if the input is readOnly. See the readOnly example for more details.
`ref`	`ReactElement`	-
	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.
`size`	`"md" \| "lg"`	-
	Defines the height of the Datepicker: md: 40px (default), lg: 48px. See the size variant for more details.
`value`	`Date \| null`	-
	DatePicker can be a controlled component. `value` sets the current value of the input. See the controlled component 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

Localization

Be sure to localize all text strings. Note that localization can lengthen text by 20 to 30 percent.

Date format locales

DatePicker supports multiple locales. Adjust the date format to each date-fns locale.

The following locale examples show the different locale format variants.

Note that 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}/>

Use the SelectList to try out different locales by passing in the localeData prop.

Country

English (US)

Variants

Controlled component

DatePicker is a controlled component. Use value, onChange, onClearInput and onError to implement it correctly.

DatePicker is controlled when value is not "undefined". When value is "undefined", it stays uncontrolled.

Empty input. If DatePicker doesn't present pre-selected date values, initialize value with "null" so the component is controlled.
Pre-selected date values. If DatePicker presents pre-selected date values, initialize value with the pre-selected date so the component is controlled.

Empty input

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

export default function Example() {
  const [dateValue, setDateValue] = useState(null);

  return (
    <Flex alignItems="start" height="100%" justifyContent="center" width="100%">
      <Box padding={2}>
        <DatePicker
          id="example-basic"
          label="Select a date"
          onChange={({ value }) => setDateValue(value)}
          value={dateValue}
        />
      </Box>
    </Flex>
  );
}

Pre-selected date values

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

export default function Example() {
  const [dateValue, setDateValue] = useState(new Date(1985, 6, 4));

  return (
    <Flex alignItems="start" height="100%" justifyContent="center" width="100%">
      <Box padding={2}>
        <DatePicker
          id="example-basic"
          label="Select a date"
          onChange={({ value }) => {
            setDateValue(value);
          }}
          value={dateValue}
        />
      </Box>
    </Flex>
  );
}

Size

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

export default function Example() {
  const [dateValueMd, setDateValueMd] = useState(null);
  const [dateValueLg, setDateValueLg] = useState(null);

  return (
    <Box padding={8} width="100%">
      <Flex direction="column" gap={4}>
        <DatePicker
          id="example-errorMessage-md-nolabel"
          onChange={({ value }) => setDateValueMd(value)}
          size="md"
          value={dateValueMd}
        />
        <DatePicker
          id="example-errorMessage-md-nolabel"
          onChange={({ value }) => setDateValueLg(value)}
          size="lg"
          value={dateValueLg}
        />
        <DatePicker
          id="example-errorMessage-md"
          label="Schedule your training"
          onChange={({ value }) => setDateValueMd(value)}
          size="md"
          value={dateValueMd}
        />
        <DatePicker
          id="example-errorMessage-md"
          label="Schedule your training"
          onChange={({ value }) => setDateValueLg(value)}
          size="lg"
          value={dateValueLg}
        />
      </Flex>
    </Box>
  );
}

States

Enabled
The enabled state of Textfield that represents it can be interacted with.
Disabled
TextFields cannot be interacted with using the mouse or keyboard. They also do not need to meet contrast requirements, so do not use them to present info to the user (use "readOnly" instead).
Error
TextField can display an error message. Simply pass in an errorMessage when there is an error present and TextField will handle the rest.
Read-only
Read-only TextFields are used to present information to the user without allowing them to edit the content. Typically they are used to show content or information that the user does not have permission or access to edit.

Enabled

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

export default function Example() {
  const [dateValue, setDateValue] = useState(new Date(1985, 6, 4));

  return (
    <Flex alignItems="start" height="100%" justifyContent="center" width="100%">
      <Box padding={2}>
        <DatePicker
          id="example-enabled"
          label="User Activation Date"
          onChange={({ value }) => setDateValue(value)}
          value={dateValue}
        />
      </Box>
    </Flex>
  );
}

Disabled

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

export default function Example() {
  const [dateValue, setDateValue] = useState(new Date(1985, 6, 4));

  return (
    <Flex alignItems="start" height="100%" justifyContent="center" width="100%">
      <Box padding={2}>
        <DatePicker
          disabled
          id="example-disabled"
          label="User Activation Date"
          onChange={({ value }) => setDateValue(value)}
          value={dateValue}
        />
      </Box>
    </Flex>
  );
}

Error

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

export default function Example() {
  const [dateValueMd, setDateValueMd] = useState(null);
  const [dateValueLg, setDateValueLg] = useState(null);

  return (
    <Box padding={8} width="100%">
      <Flex direction="column" gap={4}>
        <DatePicker
          errorMessage={dateValueMd ? undefined : "This field can't be blank!"}
          helperText="Select a preferred day for your training."
          id="example-errorMessage"
          label="Schedule your training"
          onChange={({ value }) => setDateValueMd(value)}
          size="md"
        />
        <DatePicker
          errorMessage={dateValueLg ? undefined : "This field can't be blank!"}
          helperText="Select a preferred day for your training."
          id="example-errorMessage"
          label="Schedule your training"
          onChange={({ value }) => setDateValueLg(value)}
          size="lg"
        />
      </Flex>
    </Box>
  );
}

Read-only

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

export default function Example() {
  const [dateValue, setDateValue] = useState(new Date(1985, 6, 4));

  return (
    <Flex alignItems="start" height="100%" justifyContent="center" width="100%">
      <Box padding={2}>
        <DatePicker
          id="example-readonly"
          label="User Activation Date"
          onChange={({ value }) => setDateValue(value)}
          readOnly
          value={dateValue}
        />
      </Box>
    </Flex>
  );
}

Helper text

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

export default function Example() {
  const [dateValueMd, setDateValueMd] = useState(null);
  const [dateValueLg, setDateValueLg] = useState(null);

  return (
    <Box padding={8} width="100%">
      <Flex direction="column" gap={4}>
        <DatePicker
          helperText="Select from the next available dateValueDisablePast"
          id="heleprText"
          label="Customer service appointment"
          minDate={new Date()}
          onChange={({ value }) => setDateValueMd(value)}
          size="md"
          value={dateValueMd}
        />
        <DatePicker
          helperText="Select from the next available dateValueDisablePast"
          id="heleprText"
          label="Customer service appointment"
          minDate={new Date()}
          onChange={({ value }) => setDateValueLg(value)}
          size="lg"
          value={dateValueLg}
        />
      </Flex>
    </Box>
  );
}

Date range

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

export default function Example() {
  const [startDate, setStartDate] = useState(null);
  const [endDate, setEndDate] = useState(null);
  const endDateInput = useRef(null);
  const startDateInput = useRef(null);

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

Disabled dates

DatePicker supports disabling future & past dates as well as an array of selected dates.

Disable past & future dates

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

export default function Example() {
  const [dateValueDisableFuture, setDateValueDisableFuture] = useState(null);
  const [dateValueDisablePast, setDatealueDisablePast] = useState(null);

  return (
    <Flex
      alignItems="start"
      gap={4}
      height="100%"
      justifyContent="center"
      width="100%"
    >
      <Box padding={4}>
        <DatePicker
          helperText="Enter your date of birth"
          id="disableFuture"
          label="Date of birth"
          maxDate={new Date()}
          onChange={({ value }) => setDateValueDisableFuture(value)}
          value={dateValueDisableFuture}
        />
      </Box>
      <Box padding={4}>
        <DatePicker
          helperText="Enter an activation date for your campaign"
          id="disablePast"
          label="Campaign activation date"
          minDate={new Date()}
          name="bday_datefield"
          onChange={({ value }) => setDatealueDisablePast(value)}
          value={dateValueDisablePast}
        />
      </Box>
    </Flex>
  );
}

Disable selected dates

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

export default function Example() {
  const [dateValue, setDateValue] = useState(new Date(2020, 2, 9));

  return (
    <Flex alignItems="start" height="100%" justifyContent="center" width="100%">
      <Box padding={4}>
        <DatePicker
          excludeDates={[new Date(2020, 2, 11), new Date(2020, 2, 12)]}
          helperText="Enter an activation date for your campaign"
          id="disableSelecxted"
          label="Select Your Appointment"
          minDate={new Date()}
          name="bday_datefield"
          onChange={({ value }) => setDateValue(value)}
          value={dateValue}
        />
      </Box>
    </Flex>
  );
}

Select list

Provide select lists for quickly selecting year and month

import { useState } from 'react';
import { Box, 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);
  const [dateValue, setDateValue] = useState(new Date(1985, 6, 4));

  return (
    <Flex alignItems="start" height="100%" justifyContent="center" width="100%">
      <Box padding={2}>
        <Flex direction="column" gap={4} width="100%">
          <SegmentedControl
            items={items}
            onChange={({ activeIndex }) => setItemIndex(activeIndex)}
            selectedItemIndex={itemIndex}
          />
          <DatePicker
            id="selectLists"
            label="Alberto's birth date"
            onChange={({ value }) => setDateValue(value)}
            selectLists={mapOptions[itemIndex.toString()]}
            value={dateValue}
          />
        </Flex>
      </Box>
    </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.

Direction down

idealDirection="down"

Direction left

idealDirection="left"

Direction right

idealDirection="right"

Direction up

idealDirection="up"

Mobile

DatePicker requires DeviceTypeProvider to enable its mobile user interface. The example below shows the mobile platform UI and its implementation.

For mobile, DatePicker is displayed in a SheetMobile.

import { useState } from 'react';
import { DeviceTypeProvider } from 'gestalt';
import { DatePicker } from 'gestalt-datepicker';

export default function Example() {
  const [dateValue, setDateValue] = useState(new Date(1985, 6, 4));
  return (
    <DeviceTypeProvider deviceType="mobile">
      <DatePicker
        disableMobileUI={false}
        helperText="Select a date"
        id="main"
        label="Delivery date"
        onChange={({ value }) => setDateValue(value)}
        value={dateValue}
      />
    </DeviceTypeProvider>
  );
}

External handlers

Experimental

DatePicker consumes external handlers from GlobalEventsHandlerProvider.

Handlers:

onRender: executed when DateField mounts for the first time

See GlobalEventsHandlerProvider for more information.

Component quality checklist

Component quality checklist
Status	Status description
Figma Library	Ready	Component is available in Figma for web and mobile web.
Responsive Web	Ready	Component responds to changing viewport sizes in web and mobile web.
Issues		This component has known issues.

Internal documentation

PDocs available

Edit page on GitHub