Date Picker

Installation

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

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

Interactive demo

Single date

() => {
  const [startDate, setStartDate] = React.useState(null);
  return (
    <FormControl id="startDate" name="startDate" label="Start date">
      <DatePicker selected={startDate} onChange={date => setStartDate(date)} minDate={new Date()} />
    </FormControl>
  );
};

Date range

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

Single input

() => {
  const [dateRange, setDateRange] = React.useState([null, null]);
  const [startDate, endDate] = dateRange;
  return (
    <FormControl id="dateRange" name="dateRange" label="Date range">
      <DatePicker
        selectsRange={true}
        startDate={startDate}
        endDate={endDate}
        onChange={update => {
          setDateRange(update);
        }}
      />
    </FormControl>
  );
}

Multiple inputs

() => {
  const [startDate, setStartDate] = React.useState(new Date());
  const [endDate, setEndDate] = React.useState();
  return (
    <>
      <Columns space={4} collapseBelow="md">
        <Column>
          <FormControl id="startDate" name="startDate" label="Start date">
            <DatePicker selected={startDate} hasMask onChange={date => setStartDate(date)} selectsStart startDate={startDate} endDate={endDate} />
          </FormControl>
        </Column>
        <Column>
          <FormControl id="endDate" name="endDate" label="End date">
            <DatePicker selected={endDate} hasMask onChange={date => setEndDate(date)} selectsEnd startDate={startDate} endDate={endDate} minDate={startDate} />
          </FormControl>
        </Column>
      </Columns>
    </>
  );
};

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.

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.

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

Related components

• Date Textbox
• Form Control