Stable

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.

GitHub, opens in a new tab·Storybook, opens in a new tab·Playroom, opens in a new tab·Figma, opens in a new tab

Installation

bash

npm install @nib-components/date-picker

Our date picker is built on the React Aria framework and enhanced with Mesh Components to meet our specific requirements and standards. The date picker is fully integrated with our form control functionalities, providing a seamless user experience. Unlike traditional form inputs, it operates independently, eliminating the need to encapsulate it within a Form Control. This design simplifies implementation and enhances usability.

Usage

There are two exported components from the package, DatePicker and DateRangePicker depending on your needs:

jsx

import {DatePicker, DateRangePicker} from '@nib-components/date-picker';

Interactive demo

Single date

jsx

() => {
  const [startDate, setStartDate] = React.useState(null);
  return <DatePicker label="Choose a date" />;
};

() => {
  const [startDate, setStartDate] = React.useState(null);
  return <DatePicker label="Choose a date" />;
};

Single date with granularity

jsx

() => {
  const [startDate, setStartDate] = React.useState(null);
  return <DatePicker label="Choose a date" granularity="second" />;
};

() => {
  const [startDate, setStartDate] = React.useState(null);
  return <DatePicker label="Choose a date" granularity="second" />;
};

Date range

The DateRangePicker component allows users to select date ranges by entering dates manually or by utilizing an intuitive calendar popup. This design enhances usability and ensures accurate date selection.

jsx

() => {
  return <DateRangePicker label="Choose a date range" />;
};

() => {
  return <DateRangePicker label="Choose a date range" />;
};

Props

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

As the <DatePicker /> component does not need to be wrapped in a FormControl, it still supports all the props from FormControl.

The following props, which are either part of the fromControl or the react-aria DatePicker/DateRangePicker component, are required for proper integration and functionality.

Prop	Type	Default	Description
`label` (required)	string		A label displayed to the user. All inputs must have a label for improved a11y.
`info`	string		An informational message displayed to the user when a field is valid. The message is displayed if set to any non-empty string.
`help`	string		Extra supporting text for the field.
`disabled`	boolean		Whether the DatePicker and its underlying input should be disabled.
`formControlType`	string		This property determines if the field is required or optional. It will specify whether to render an `Optional` or `Required` tag. Must be one of `"optional"` or `"required"`.
`validated`	boolean		Whether the input field has been validated. Usually you want to set this if the user has interacted and left the field, or on form submit.
`valid`	boolean		Whether the value(s) within the control are valid.
`error`	string		An error displayed to the user. The error is displayed if set to any non-empty string.
`granularity`	string	day	It determines the granularity of the Datepicker. Must be `day`, `hour`, `minute` or `second`
`minValue`	DateValue		The minimum allowed date that a user may select.
`maxValue`	DateValue		The maximum allowed date that a user may select.
`isCompact`	boolean	`false`	Add compact styles. This should only be used for internal/dashboard/portal style applications.

Note: Refer to the React Aria documentation for detailed information on the DateValue type, as well as guidance on setting the minValue and maxValue properties.

Behaviour

DatePicker comes with date-segments where you can enter the dates manually using your keyboard or you can open calendar dialog by clicking the calendar icon button, and choosing the desired date/range.

Values

A DatePicker displays a placeholder by default. An initial, uncontrolled value can be provided to the DatePicker using the defaultValue prop. Alternatively, a controlled value can be provided using the value prop.

Date values are provided using objects in the @internationalized/date package. This library handles correct international date manipulation across calendars, time zones, and other localization concerns.

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.

Choose a date

2020

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.

Choose a date

yyyy

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.

jsx

import {I18nProvider} from 'react-aria';

function InternationalDatePicker() {
  const [startDate, setStartDate] = React.useState(null);
  return (
    <I18nProvider locale="hi-IN-u-ca-indian">
      <DatePicker label="Choose a date" value={startDate} onChange={setStartDate} />
    </I18nProvider>
  );
}

Accessibility

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

Tab: Use Tab to navigate through Date segment and to focus the calendar button
Enter/Space: Once Calendar Icon is focused, Press Enter/Space to open the calendar dialog.
Tab: Use Tab to navigate between the previous month button, next month button, and date inside the calendar
Left: Once the date inside calendar dialog is focused, use Left arrow to navigate to previous dates.
Right: Once the date inside calendar dialog is focused, use Right arrow to navigate to next dates.
Up: Once the date inside calendar dialog is focused, use Up arrow to navigate to previous week.
Down: Once the date inside calendar dialog is focused, use Down arrow to navigate to next week.
Enter/Space: Once the date is focused, press Enter/Space to choose the desired date.

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.

Edit this page