Design Tokens for Mesh have just been released!
Skip to content

Date Picker

A simple, accessible and reusable date picker component. The date picker allows users to enter a date by either choosing from the calendar, or typing directly in the textbox. The date picker is composed of a textbox that shows a calendar prompt when focused.

Installation

bash
npm install @nib-components/date-picker

As a form input, @nib-components/form-control must wrap this component to provide an accessible label, help text, and validation styling. Note: You will also need to install the peerDependencies @nib/icons and @nib-components/theme.

Usage

jsx
import DatePicker from '@nib-components/date-picker';

Interactive demo

Single date

jsx

Date range

Our DatePicker component supports date ranges, either as a single input or multiple:

Single input

jsx

Multiple inputs

jsx

Props

Our date picker is a (very) thin wrapper around the open source package, react-datepicker. Be sure to check out their docs site for a full list of available props.

As the <DatePicker/> is wrapped in a <FormControl/>, all FormControl props such as valid, validated, and disabled will be passed down to this component. This includes the id, name and label which will align with the for attribute on the <label>.

All props passed directly to <DatePicker/> will be applied to the underlying <input> as attributes.

PropTypeDefaultDescription
value (required)stringThe input value.
checkedbooleanfalseWhether the input is selected.
hasMaskbooleanfalseWhether the input uses text-mask.

Behaviour

By clicking/tapping on the calendar icon, it opens the calendar view. The current date is indicated by colour and font weight. Selecting the previous or next arrows moves the calendar through the months. When changing a previously selected date, the currently selected date is highlighted.

The calendar view is closed when the user clicks/taps outside the calendar, when tabbing out of the text field, or when part of the page outside of the calendar view is selected.

If the user chooses to type the date, the input field supports - (hyphen), / (forward slash), `` (blank space) between characters.

Applying text mask

If the user chooses to type the date, the input field supports / (forward slash) autocomplete between characters, by setting the prop hasMask to true.

Validation and errors

Form validation should happen in real-time so the user can fix form input errors when they occur. The success state should appear when the input is valid and the error state should appear when the input is invalid.

The success state is denoted with a green border on the bottom of the input field and a green success icon.

The error state is denoted with a red border, a red error icon and a red error message below the input field. A good error message clearly describes how to address the input error. The error state only appears when the user clicks/taps away from the date input field. Once the user corrects the error, the error state is replaced with the success state.

Please enter your estimated cover start date.

Accessibility best practices for validation and errors

  • Validation states must not rely on colour alone to convey the error information as users with visual impairments may skip over this information. Using colour and an appropriate icon is recommended.
  • To help screen reader users, the error message should include a hidden ‘Error:’ before the error message. These users will hear, for example, “Error: Please enter your estimated cover start date.”.

Labels

Both date and time pickers are accompanied by labels, and follow the same accessibility guidelines for all forms.

Internationalisation

The date picker can be configured to support internationalisation. E.g MM/DD/YYYY. See the open source date picker code documentation for more info.

Accessibility

Once the date picker has focus, there are a number of keyboard controls available to navigate the calendar:

  • Left: Move to the previous day.
  • Right: Move to the next day.
  • Up: Move to the previous week.
  • Down: Move to the next week.
  • PgUp: Move to the previous month.
  • PgDn: Move to the next month.
  • Home: Move to the previous year.
  • End: Move to the next year.
  • Enter/Esc/Tab: Close the calendar.

Mobile

The datepicker opens as a popup under the text input. However this is not ideal for touch devices that don't have as much screen real estate and need bigger click targets. Test with your users whether they would prefer to use their devices native date picker over this.