Datepicker Field

Overview

When to use

• When asking the user for a date in the recent past, near future, or today
• When it is useful to have a calendar or days of the week for reference (for instance, when a user needs to interpret a customer talking about ‘last Tuesday’)
• When dates are likely to be copied and pasted from another source

For older dates, such as a date of birth, use the Date Field.

Anatomy

1. Datepicker field: Based on Text Field. Contains label, hint text, input and error state.
2. Calendar button: Pressing the calendar opens the calendar popover.
3. Month and year controls: Moves the date forwards and backwards. Single chevrons change the month, and double chevrons change the year.
4. Days of the week: Uses Monday as the first day of the week.
5. Selected date
6. Today's date
7. Today button: Selects today's date and closes the calendar popover.
8. Clear button: Clears the current entry and closes the calendar popover.
9. Calendar popover: The menu where the date is selected. The calendar popover is always a fixed width, and always aligned to the left edge of the datepicker field.

Basic usage

Edit live code

Date format and validation

DatepickerField uses the dd/mm/yyyy format for dates and will use this format when selecting dates from the calendar. The calendar will attempt to parse the input date in order to show which date is selected.

The input itself is a TextInput that the user can freely enter text into and you should always validate user input when the form is submitted.

Content

Writing labels

The Datepicker Field label should always be a noun that describes the date. It should be no more than two or three words.

Don't try to make the label and date function as a sentence, such as 'Bill from {date input}'. This is harder for users to follow, and harder to communicate errors, for instance 'Enter a valid bill from; does not make sense as an error message.

Don't:

• Bill from
• Date meter reading submitted
• The date you want to install
• Ending on

Do:

• Billing start date
• Reading date
• Installation date
• End date

Writing hints

Hint text may be used to help the user understand additional validation constraints on the date. The Datepicker Field has placeholder text that specifies the format of a valid date, so it is not necessary to include the format as a hint.

Keep any extra guidance short, and avoid trying to write full sentences. Where possible, hint text should describe a valid date, not an invalid date.

Hint text can also give more information about the date if it is not possible with a short label, for instance if a label could be interpreted in multiple ways. Always try to write a clearer label before relying on hint text.

Don't:

• Date
  Weekends unavailable
• Move out date
  Please put a date no more than 28 days from today
• Date
  Peak reading

Do:

• Date
  Monday to Friday (excl. public holidays)
• Move out date
  Within 28 days
• Peak reading date

Variations

Validation Error

Edit live code

Input size

Datepicker input size is determined by a combination of the fullWidth and characters properties. By default, datepicker inputs are an appropriate width for the expected input and stretch to full width below the smallest breakpoint.

Generally it is recommended to use the default behaviour, but in some cases you may want to set the width of the input to a specific size.

The responsive full width behaviour can be overridden by setting fullWidth="always" and fullWidth="never".

Edit live code

The default width itself can be overridden using the characters property, which approximates how many characters should fit into the input.

Edit live code

Unavailable dates

It is possible to mark certain dates as unavailable in the calender. Provide a callback to the isDateUnavailable property to test if a given date should be unavailable.

Note that this will not prevent the user from manually entering these dates so it is important to validate the input when the form is submitted.

Edit live code

Date ranges

The Datepicker Field doesn't yet support selecting date ranges in a single field. Until it does, use two Datepicker Fields side-by-side.

To create a relationship between the two fields, use the isDateUnavailable property. Set dates before the start date as unavailable in the end date field. Reset the end date when the start date is changed to avoid the user getting stuck.

Align side-by-side Datepicker Fields to the bottom of the container, so that when fields have different heights (for instance when one field has hint text or an error message) the inputs remain aligned.

Edit live code

Avoid additional, overarching labels for date ranges. Instead, make the label for the start and end fields clear.

Don't:

Edit live code

Do:

Edit live code

Uncontrolled vs Controlled

It is recommended to use uncontrolled form inputs where possible (opens in new window) . When using an uncontrolled DatepickerField you can pass a defaultValue.

Edit live code

Alternatively, you can control the input by passing value and onChange.

Edit live code

OverlayProvider

This component is built using the React Aria (opens in new window) . The OverlayProvider context provider is required to hide the content outside of the calendar popover from screen readers.

import { OverlayProvider } from '@react-aria/overlays';

const MyApp = () => <OverlayProvider>Welcome to my app!</OverlayProvider>
import { OverlayProvider } from '@react-aria/overlays';

const MyApp = () => <OverlayProvider>Welcome to my app!</OverlayProvider>

Properties

Tokens

Theme tokens

Related

• Form Guidelines
• Date Field
• Text Fields