# Date Picker

A `DatePicker` is used to allow a user to select a date from a visual calendar
interface.

While this component can be used in isolation, the intention is that in many
cases it will supplement an input component to provide the user with a
multi-mode opportunity to select a date.

## Design & usage guidelines

Use DatePicker when you are looking to provide the user with a highly visual
interface for intuitive date selections.

A classic use case for a standalone DatePicker would be as a means to navigate
within a larger calendar interface.

It may be beneficial to supplement the DatePicker with alternate means of
entering their date selection, such as providing a `date` input.

### Inline

Use an inline DatePicker when you have sufficient space in the interface to have
a permanent date selection fixture, or when date selection is the primary
function of the interface, such as a stepped flow where the user is asked a
series of scheduling questions individually, in sequence.

In cases like complex scheduling forms where all the factors of a schedule such
as times, repeating frequency, and duration are being asked, consider using the
default popover-type behaviour for those use cases to reduce an overwhelming
volume of UI elements to process at once. See
[Inline](/storybook/web/?path=/story/components-selections-datepicker--inline)
example.

## Accessibility

At this point, the `DatePicker` component is a wrapped version of
[React DatePicker](https://reactdatepicker.com/). This means that the
accessibility of the component is handled by the `React DatePicker` component.

Users can operate all of the controls by keyboard, including the `tab` to cycle
between Next/Previous month and the calendar, arrow keys to navigate between
dates, and `space` and/or `return` to make selections. Pressing `escape` will
close the DatePicker.

The date available for selection is read aloud to assistive technology in the
format "Choose {date} (button)". For example, "Choose December 1st, 2021
(button)".

If using a custom activator, ensure that the activator is keyboard-operable.

## Related components

* If you are looking to use the `DatePicker` in a `Form`, consider the
  [InputDate](../InputDate/InputDate.md) component.
* For a time input, use [InputTime](../InputTime/InputTime.md)
* To present dates that have already been selected in a consistent format, use
  [FormatDate](../FormatDate/FormatDate.md)
* To represent past or future dates and times, use
  [FormatRelativeDateTime](../FormatRelativeDateTime/FormatRelativeDateTime.md)
