Date range

Date range in Storybook

note

This component is being reworked. There will be a new version aligned with the latest guidelines in upcoming releases.

Usage

Overview

The date range component is used to input a range of date elements into a form, typically consisting of a start date and an end date.

Anatomy

The date range component consists of the following elements:

1. Start date: used to specify the start date.
2. End date: used to specify the end date.

Both elements include a field where users can manually input a date. There is also a calendar icon that, when clicked, triggers a dropdown menu and enables date selection.

Best practices

• Use the date range picker only when there is a need to display a start and end date.

• Use the standard date picker when users only need to specify a single date.

• The date labels can be customized depending on the use case.

Interactions

The individual date pickers have their own interaction states as shown below.

On selecting the date input field, the following interactions are enabled:

1. Text entry in the date field - the users may type in the date using the specified format.

   a. Only numeric text is accepted in the field.

   b. The separators, as dictated by the required date format, will be added automatically.

2. The calendar is displayed with the current date highlighted.

   a. On selecting the month control, a dropdown appears with the current month highlighted. The user may choose the required month from the list.

   

   b. On selecting the year control, a dropdown appears with the current year highlighted. The user may choose the required year from the list.

   

3. Dates selected via the calendar picker will override dates that have been manually typed.

4. All standard interaction patterns for dropdowns will apply here.

UX writing considerations

• Labels for the date range component should be clear, concise, and specify the use case (for example, "policy start date").

  • Labels appear above the date input field and are left-aligned.
  • Use sentence case for field labels.

• When representing the date as a numeric value or label, best practice is to use ISO Standard 8601: YYYY-MM-DD.

note

This component is being reworked. There will be a new version aligned with the latest guidelines in upcoming releases.

Code

The DateRangeField is used to select time range. It consists of two separate DateField inputs.

Implementation

DateRangeField passes most of the props to both internal DateField components.

• DateRangeField accepts same props as DateField with few differences
• minDate is passed to start input, and maxDate is passed to end input, rest of min/maxDate props are calculated according to user selections
• value, defaultValue prop do not accept date shape but its object defined as:

  {
    "startDate": dateShape,
    "endDate": dateShape
  }
• endLabel, endSecondaryLabel, endPlaceholder, endTooltip props are used to override props specified for end input
• callback props (onBlur, onFocus, onValidationChange) are passed to both start/end inputs and DateRangeField do not modify them
• onValueChange callback is overridden by DateRangeField - it adds to config object (third argument of callback) prop corresponding to trigger input - startDateChanged/endDateChanged

Layout

For desktop/tablet resolution and default label position (top) inputs are displayed horizontally in a 50%:50% proportion. For left label position inputs stack vertically and looks like two separate DateFields. On mobile inputs always display vertically.

Usage in metadata

Usage in metadata differs in how to declare the path property in the model compared to usual DateField components, because we need to store two date values as opposed to one.

• The startPath and endPath props are used to identify which keys the start and end values should be stored in in formData. This is similar to the usage of the path prop for regular DateField components.

• startPath and endPath both have default values. If you want to choose your own start/end values, pass in startPathValueProp and endPathValueProp respectively.

• It is still possible to just use path prop but value is treated as a date range object. Effectively its equivalent to using startPath/endPath with suffixes ${path}.startDate/${path}.endDate