Date range

Date range in Storybook

Examples

Check out the Usage section for details about how to design a DateRangePicker properly, and the different configuration options we provide.

Basic Example

You can add an input that allows a user to enter a date range either manually or through calendar modals.

<DateRangePicker
  label={{ start: "Choose start date", end: "Choose end date" }}
  onChange={(event, value) => console.log('The dates chosen are', value.start, value.end)}
/>

Min/Max example

You can limit the range of dates a user can select.

note

This does not include validation, it only limits the options in the calendar modal. A user can type any date into the input.

<DateRangePicker
  label={{ start: "Choose start date", end: "Choose end date" }}
  minDate={{ day: 1, month: 1, year: 2024 }}
  maxDate={{ day: 31, month: 12, year: 2024 }}
/>

Validation Example

You can use the onChange property to call a function that updates stateMessages to display errors to the user. The following example displays errors for invalid dates or dates that are not in 2024.

note

As mentioned in the previous example, a user can type any date into the input regardless of the minDate and maxDate properties.

import React, { useState } from 'react';
import { DateRangePicker } from '@jutro/components/new';

export function DateRangePickerError() {
  const [stateMessages, setStateMessages] = useState({});

  const parseErrorCode = (sideErrorObject) => {
    let errorCode = sideErrorObject.errorCode
    if (errorCode === 'INVALID_DATE') {
      return {error: ["Please enter a valid date."]}
      };

    if (errorCode === 'MIN_EXCEEDED' || errorCode === 'MAX_EXCEEDED') {
      return {error: ["Please enter a valid date."]}
    }
  }

  const handleChange = (event, value, errorObject) => {
    let parsedMessages: {start?:{error: string[]}, end?:{error: string[]}} = {}
    // check start
    let start_error = errorObject?.start
    if (start_error){
      parsedMessages.start = parseErrorCode(start_error)
    }

    // check end
    let end_error = errorObject?.end
    if (end_error){
      parsedMessages.end = parseErrorCode(end_error)
    }
    console.log(parsedMessages)
    setStateMessages(parsedMessages)

  }

  return (
    <DateRangePicker
      label={{ start: "Choose start date", end: "Choose end date" }}
      minDate={{ day: 1, month: 1, year: 2024 }}
      maxDate={{ day: 31, month: 12, year: 2024 }}
      onChange={handleChange}
      stateMessages={stateMessages}
    />
  );

  }

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.

Code

<DateRangePicker
  label={{ start: "Choose start date", end: "Choose end date" }}
  onChange={(event, value) => console.log('The dates chosen are', value.start, value.end)}
/>

Import statement

import { DateRangePicker } from '@jutro/components/new';

Component contract

Make sure to understand the Design System components API surface, and the implications and trade-offs. Learn more in our introduction to the component API.

Properties

labelrequired

Type

{ start: intlMessageShape, end: intlMessageShape }

Description

Labels associated with the input fields, also passed as a default value to 'aria-label'. Must be in object format: start - label for the start date picker, end - label for the end date picker.

className

Type

string

Description

CSS class passed to the root element of the component.

disabled

Type

bool

Description

If true, the component is rendered in disabled state.

displayFormat

Type

'vshort' 'short' 'long' 'abbreviated' 'full'

Description

The date format. This value along with locale will determine how the date is displayed to the user.

displayOnly

Type

bool

Description

If true, displays the component value as a plain text. Consider using readonly instead, if possible, because plain text has much worse accessibility than readonly inputs.

hideLabel

Type

{ start: bool, end: bool }

Description

If true, the label is not visible. Must be in object format: start - hideLabel for the start date picker, end - hideLabel for the end date picker.

hideTodayButton

Type

bool

Description

Hides the Today button in the calendar.

initialValue

Type

{start: JutroDate, end: JutroDate}

Description

Initial value of the input. Must be in object format: start - initialValue for the start date picker, end - initialValue for the end date picker. Value must be in object format with day, month and year property where the month is indexed from 1. If the value prop is specified along with this prop, this prop's value is discarded.

labelPosition

Type

'top'|'left'

Description

Allows selection of label position.

maxDate

Type

JutroDate

Description

Maximum allowed date value.

minDate

Type

JutroDate

Description

Minimum allowed date value.

onBlur

Type

React.FocusEventHandler<HTMLInputElement>

Description

Callback when the field loses focus.

onChange

Type

(event: DateChangeEvent, value: {start: JutroDate, end: JutroDate}, options: {errorCode?: "INVALID_DATE" | "MIN_EXCEEDED" | "MAX_EXCEEDED" | undefined;})

Description

Callback invoked when the input value is changed. Gets event as first argument, parsed input value as a second argument and error codes as a third argument.

onFocus

Type

React.FocusEventHandler<HTMLInputElement>

Description

Callback when the field gains focus.

placeholder

Type

{ start: intlMessageShape, end: intlMessageShape }

Description

Placeholder to display on an empty component. Must be in object format: start - initialValue for the start date picker, end - initialValue for the end date picker. If the value prop is specified along with this prop, this prop's value is discarded.

readOnly

Type

bool

Description

If true, the component is rendered in read-only state. For value as a plain text, consider using displayOnly.

required

Type

bool

Description

If true, the component is rendered as required and the label has an asterisk.

secondaryLabel

Type

{ start: intlMessageShape, end: intlMessageShape }

Description

Secondary label text to display. Must be in object format: start - secondaryLabel for the start date picker, end - secondaryLabel for the end date picker.

stateMessages

Type

{ start: {error: string[]}, end: {error: string[]} }

Description

Object with input state and messages that should be shown for the current state. Must be in object format: start - stateMessages for the start date picker, end - stateMessages for the end date picker.

tooltip

Type

{ start: {text: intlMessageShape, trigger: string}, end: {text: intlMessageShape, trigger: string} }

Description

Tooltip props object: text - text to be displayed in the tooltip, trigger - the events (each separated by a space) which cause the tooltip to appear. Must be in object format: start - tooltip for the start date picker, end - tooltip for the end date picker.

value

Type

{start: JutroDate, end: JutroDate}

Description

Value of the input. Takes precedence over initialValue. Must be in object format: start - the value for the start date picker, end - the value for the end date picker. Value must be in object format with day, month and year property where the month is indexed from 1. If this prop is passed, the component works in controlled mode and its value will change only if this prop changes.

Custom behaviors

DateInput validation

The DateRangePicker component provides a validation mechanism using the onChange prop. This prop accepts the event, value, and errorCode parameters. These contain seperate start and end properties to distinguish which input is being referred to. The errorCode values can be:

• INVALID_DATE: The date format is incorrect, for example, entering a month value greater than 12.
• MIN_EXCEEDED: The input value is lower than the minimum value defined by the minDate prop.
• MAX_EXCEEDED: The input value is greater than the maximum value defined by the maxDate prop.

You can check the Validation example to see how the validation works.

Display format

You can use the displayFormat prop to modify the format of the dates when using the readOnly or displayOnly props. There are five different alternatives:

• vshort: 6/20/2024
• short: Jun 20, 2024
• long: June 20, 2024
• abbreviated: Thu, Jun 20, 2024
• full: Thursday, June 20, 2024

Hooks

No hooks are available for DateRangePicker.

Translation keys

DateRangePicker component defines two translation keys for the aria-label:

Key	Used for
jutro-components.fields.DatePicker.chooseStartDate	Start date aria-label
jutro-components.fields.DatePicker.chooseEndDate	End date aria-label

DateRangePicker also inherits the following translations:

Key	Used for
jutro-components.DateCalendar.previousMonth	The label text for the Previous month button.
jutro-components.DateCalendar.nextMonth	The label text for the next month button.
jutro-components.DateCalendar.currentDay	The label text for go to the current date button.
jutro-components.DateCalendar.currentDayAriaLabel	The label text for the button to select the current date as the value.
jutro-components.MonthSkeleton.previousYear	The label text for the previous year button.
jutro-components.MonthSkeleton.nextYear	The label text to go to the next year button.
jutro-components.MonthSkeleton.currentMonth	The label text to go to the current month button.
jutro-components.MonthSkeleton.currentMonthAriaLabel	The label text for the button to select the current month as the value.
jutro-components.YearCalendar.previousYears	The label text for the previous year range button.
jutro-components.YearCalendar.currentYear	The label text for the go to current year button.
jutro-components.YearCalendar.currentYearAriaLabel	The label text for the button to select the current year as the value.

Escape hatches

For more information, see our documentation about escape hatches.

Legacy information

Are you using the legacy version of this component?

• To view docs for the old component, switch to a version of the docs older than 10.5.x.
• the legacy component is also available in Storybook:
  • DateRangeField

Changelog

10.5.0

New @jutro/components/new/DateRangePicker component introduced that replaces DateRangeField.

DateRangeField can still be imported from @jutro/components/DateRangeField, but you will get a warning that it is deprecated when doing so.