---
title: "Datepicker"
slug: datepicker
category: component
type: documentation
version: 20.0.0
tokens: 1922
source: https://ovh.github.io/design-system/v20.0.0/llms/react-components-datepicker--documentation.txt
---
# Datepicker
_A **Datepicker** component is used to allow users to select a date. They can navigate through days, months and years._
## Overview
Form Guidelines] }
figmaLink="https://www.figma.com/design/9jDDTcR4a9jPRFcdjawAlf/ODS---UI-Kit?node-id=26-7958"
githubUrl="https://github.com/ovh/design-system/tree/master/packages/ods-react/src/components/datepicker"
name="Datepicker">
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.
| | |
|---|---|
| Name | undefined |
| Also known as | Calendar |
## 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 shares the default width of every form field (280px, capped to its container), so it lines up with the other inputs of a form. To make it fill its container, give both the **Datepicker** and the **DatepickerControl** a `className` that sets `width: 100%`: the **Datepicker** wraps its control in an inline block, which a percentage on the control alone does not widen.
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 [Buttons](https://ovh.github.io/design-system/v20.0.0/components/button) to navigate through months
Selecting a month : By clicking on the month selection [Button](https://ovh.github.io/design-system/v20.0.0/components/button) 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 [Buttons](https://ovh.github.io/design-system/v20.0.0/components/button) to navigate through years
Selecting a year : By clicking on the month selection [Button](https://ovh.github.io/design-system/v20.0.0/components/button) 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 [Buttons](https://ovh.github.io/design-system/v20.0.0/components/button) to navigate through years
Selecting a decade : By clicking on the month selection [Button](https://ovh.github.io/design-system/v20.0.0/components/button) 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.
```tsx
Start date:
```
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.
```tsx
Start date:
Expected format: DD-MM-YYYY
```
Screen readers will announce the label, the field, its content and the helper.
```tsx
Start date:
```
Screen readers will announce the label, the field, its content and custom label of focused action.