React Components

# Datepicker

_A **Datepicker** component is used to allow users to select a date. They can navigate through days, months and years._

## Overview

---

The Datepicker component is used for selecting dates in forms and applications. It provides a user-friendly interface for choosing dates, ensuring that the date format is consistent and valid. This component can include features such as disabled dates and custom formats.

<table class="_table_e3iru_2 _table--md_e3iru_59 _table--striped_e3iru_167 _identity-card__table_75e8e_7" data-ods="table" data-storybook="table"><tbody><tr><th scope="row">Name</th><td>Datepicker</td></tr><tr><th scope="row">Also known as</th><td>Calendar</td></tr><tr><th scope="row">Links</th><td><a class="_link_1qra4_2 _identity-card__app-link_75e8e_12" data-ods="link" href="https://www.figma.com/design/9jDDTcR4a9jPRFcdjawAlf/ODS---UI-Kit?node-id=26-7958" target="_blank">Design <span class="_icon_g76et_2 _icon--external-link_g76et_256" data-ods="icon" role="presentation"></span></a><a class="_link_1qra4_2 _identity-card__app-link_75e8e_12" data-ods="link" href="https://github.com/ovh/design-system/tree/master/packages/ods-react/src/components/datepicker" target="_blank">Github <span class="_icon_g76et_2 _icon--external-link_g76et_256" data-ods="icon" role="presentation"></span></a><a class="_link_1qra4_2 _identity-card__app-link_75e8e_12" data-ods="link" href="https://ovh.github.io/design-system/v18.6.4/?path=/docs/ods-components-form-elements-datepicker--documentation" target="_blank">Previous major version <span class="_icon_g76et_2 _icon--external-link_g76et_256" data-ods="icon" role="presentation"></span></a><a class="_link_1qra4_2" data-ods="link" href="#">Form Guidelines</a></td></tr></tbody></table>

## Usage

---

**Datepicker** is used to **allow a selection of a specific date** in the near future or even past. It is **useful for scheduling, or defining user dates**.

### Dos & Don'ts

| ✅ Do |
| --- |
| - Use a Datepicker when users need to select a specific date |
| - Choose a relevant default date when opening the calendar (e.g., default to the current year/month when not contextually set) |
| - Add a label alongside the input to clearly indicate the expected format, especially when the placeholder disappears on input |
| - Use a Datepicker when users need to select a single date or range of dates |
| - Use a Datepicker for recent or near future dates |
| - When the user has to pick dates in the distant past or future, do choose a more suitable day as Datepicker default date when it will open |

| ❌ Don't |
| --- |
| - Don't rely only on placeholders to communicate the date format. Users need persistent guidance (via a label or hint) |
| - Don't use a Datepicker when the user must select a date very far in the past or future (e.g., birthdate). Use a more accessible method like dropdowns or manual input |
| - Don't overload the interface with too many calendar options at once |
| - Don't default the calendar to an irrelevant month/year |

### Best Practices in Context

1.  **Datepicker**
2.  **Date field**
3.  **Icon button**
4.  **Dropdown calendar**
5.  **Month/Year button**
6.  **Previous/Next month buttons**
7.  **Week days**
8.  **Day**
9.  **Selected day**

## Placement

---

A **Datepicker** can be used in a page as long as there is a need to allow users to pick a date.

The date field has a fixed width by default but when used in a form its width should match the other inputs.

The **Datepicker** dropdown has a fixed width and is not adjustable.

## Behavior

---

**Opening the Datepicker**

By clicking on the **Datepicker** icon button.

**Closing the Datepicker**

-   By clicking outside the **Datepicker** dropdown
-   By selecting a date

**Date picking mode**

Navigating to previous/next month : By clicking on arrow icon  to navigate through months

Selecting a month : By clicking on the month selection  to switch to month picking mode

Picking a date : By clicking on a date

**Month picking mode**

Navigating to previous/next year : By clicking on arrow icon  to navigate through years

Selecting a year : By clicking on the month selection  to switch to year picking mode

Picking a month: By clicking on a month, the dropdown goes back to date picking mode

**Year picking mode**

Navigating to previous/next range of years : By clicking on arrow icon  to navigate through years

Selecting a decade : By clicking on the month selection  to switch to year picking mode

Picking a month: By clicking on a month, the dropdown goes back to date picking mode

**Locale**

Locale determines how the week days will be displayed according to the localization. The **Datepicker** supports the following locales: English (default), German, Spanish, French, Italian, Dutch, Polish and Portuguese.

## Navigation

---

### Focus Management

The **Datepicker** icon button can receive the focus.

When the dropdown calendar opens, the focus is moved to the currently selected date, or to today's date if none is selected.

When the dropdown is closed (via Escape or blur), focus returns to the Datepicker trigger (the input field).

### General Keyboard Shortcuts

Pressing Escape closes the Datepicker dropdown without selecting a date.

Pressing Tab or Shift + Tab moves focus through dropdown controls when open.

### Navigating days

-   Arrow Left: Move to the previous day
-   Arrow Right: Move to the next day
-   Arrow Up: Move to the same weekday of the previous week
-   Arrow Down: Move to the same weekday of the next week

### Jumping within the calendar

-   Home: Move to the first day of the current month
-   End: Move to the last day of the current month
-   Page Up: Move to the same date of the previous month
-   Page Down: Move to the same date of the next month

### Selecting a date or changing view

-   Enter: Select the currently focused date and close the dropdown
-   Typing a valid date format (e.g., yyyy-mm-dd) in the input and pressing Enter will also select the date

### Navigating to month/year view

-   Ctrl / Cmd + Arrow Up (first press): Switches to month selection view
-   Ctrl / Cmd + Arrow Up (second press): Switches to year selection view
-   Use Arrow keys to move within month/year grids
-   Press Enter to confirm selection and return to the previous view
-   Ctrl / Cmd + Arrow Left / Arrow Right: Quickly navigate to the previous or next month from date view

## Accessibility

---

To ensure proper accessibility, the **Datepicker** must be correctly labeled, provide clear guidance on date format and meaningful context when a clearable button is used.

### Always provide an explicit label

Every **Datepicker** must have a clear and explicit label to ensure that users (especially screen reader users) understand its purpose using either **FormField** or a native label tag.

```jsx
{
  globals: {
    imports: `import { Datepicker, DatepickerContent, DatepickerControl, FormField, FormFieldLabel } from '@ovhcloud/ods-react';`
  },
  tags: ['!dev'],
  render: ({}) => <FormField>
      <FormFieldLabel>
        Start date:      </FormFieldLabel>
      <Datepicker>
        <DatepickerControl />
        <DatepickerContent />
      </Datepicker>
    </FormField>
}
```

Screen readers will announce the label, the field and its content.

### Provide guidance on date format

Since screen readers can only interact with the **Datepicker** input field, it’s important to provide guidance on the expected date format to ensure correct input.

```jsx
{
  globals: {
    imports: `import { TEXT_PRESET, Datepicker, DatepickerContent, DatepickerControl, FormField, FormFieldHelper, FormFieldLabel, Text } from '@ovhcloud/ods-react';`
  },
  tags: ['!dev'],
  render: ({}) => <FormField>
      <FormFieldLabel>
        Start date:      </FormFieldLabel>
      <Datepicker>
        <DatepickerControl placeholder="DD-MM-YYYY" />
        <DatepickerContent />
      </Datepicker>
      <FormFieldHelper>
        <Text preset={TEXT_PRESET.caption}>
          Expected format: DD-MM-YYYY        </Text>
      </FormFieldHelper>
    </FormField>
}
```

Screen readers will announce the label, the field, its content and the helper.

Start date:

```jsx
<FormField>
  <FormFieldLabel>
    Start date:  </FormFieldLabel>
  <Datepicker i18n={{
  [INPUT_I18N.clearButton]: 'Clear date'
}}>
    <DatepickerControl clearable />
    <DatepickerContent />
  </Datepicker>
</FormField>
```

Screen readers will announce the label, the field, its content and custom label of focused action.