Migration Information

For teams migrating from the V1 to V2 component, please refer to the migration guide for changes to the component.

Component Guide

import { DateInputRange } from '@uhg-abyss/web/ui/DateInputRange';

label

subText

errorMessage

successMessage

dateFormat

hideLabel

isClearable

isDisabled

highlighted

matchAnchorWidth

() => {
  const [values, setValues] = useState({
    from: dayjs().format('MM/DD/YYYY'),
    to: dayjs().add(5, 'day').format('MM/DD/YYYY'),
  });

  return (
    <DateInputRange
      label="DateInputRange Sandbox"
      values={values}
      onChange={setValues}
    />
  );
};

Day.js

DateInputRange relies on the Day.js library to handle date operations. Several inputs to the DateInputRange are Dayjs objects.

Abyss includes a Day.js tool, which includes a number of preset Day.js plugins, but you can also install Day.js separately.

import { dayjs } from '@uhg-abyss/web/tools/dayjs';

Variants

Inputs with calendar

The default variant for DateInputRange shows two input fields, each with a button to open a calendar.

Inputs only

Use the inputOnly prop when the dates can be easily entered without a calendar.

useForm (recommended)

Using useForm and FormProvider simplifies form management by providing out-of-the-box validation, form state handling, and performance optimizations, leveraging the power of react-hook-form.

useState

Using the useState hook gets values from the component state.

Display properties

Label

Use the label prop to display a label above the inputs. To hide the label, set hideLabel to true.

Use isRequired and isOptional for further customization.

Note: If using useForm, do not use isRequired. The same functionality can be achieved with required: true in validators.

Helper

Use the helper prop to display a help icon next to the label. Simply passing a string value will render the default helper, a Tooltip containing that string. The helper can be customized by passing in a node. It is recommended to use either a Tooltip or a Popover. See When should I use a Tooltip vs. a Popover? for more information on best practices regarding the two.

Subtext

Use the subText prop to display helpful information related to the input fields.

Date format

Use the dateFormat prop to specify the format of the date displayed in the input fields. The value given will also change the fields' formatting hints and input masks. The default format is 'MM/DD/YYYY'.

Note: The format must be compatible with the Day.js library. Due to the input mask used, DateInputRange does not support any substrings that would require non-numeric characters. Of the available formatting substrings, only the following are supported:

Format	Description
'YY'	Two-digit year
'YYYY'	Four-digit year
'M'	The month, beginning at 1
'MM'	The month, 2-digits
'D'	The day of the month
'DD'	The day of the month, 2-digits
'd'	The day of the week, with Sunday as 0

Note: The initial/default value(s), provided either through useForm or useState, must also be in the specified date format.

Hide placeholders

By default, the inputs will contain a formatting placeholder that matches the specified date format. Use the hidePlaceholders prop to control the placeholders' visibility. The default value is false.

Note: The formatting masks are unaffected by this prop. The placeholders are only visible if there is no text in the input.

Width

Use the width prop to set the width of the input fields.

Match anchor width

By default, the calendar will match the width of the input fields. To disable this behavior, set the matchAnchorWidth prop to false. The calendar will then take up the minimum width required.

Note: If the input field width is less than the minimum width of the calendar (340px), the value of matchAnchorWidth will be ignored to prevent the calendar from overflowing the container.

Validation

Validators (useForm)

Form Compatibility

useState

useForm

Use the validators prop to set validation rules for the field when using useForm. See the examples below for implementation on various types of validation.

Note: The default error message when required is true is minimally acceptable for accessibility. It is highly recommended to customize it to be more specific to the use of the field and form.

Error message (useState)

Form Compatibility

useState

useForm

Use the errorMessage prop to display a custom error message below the input fields when using useState.

Success message

Form Compatibility

useState

useForm

Use the successMessage prop to display a custom success message below the input field. To provide a single success message across all form input components using useForm/FormProvider, you can provide successMessage to FormProvider as shown here.

Highlighted

Form Compatibility

useState

useForm

Use the highlighted prop to enable a distinct background color when fields are required. To supply this across all form input components using useForm/FormProvider, you can provide highlighted to FormProvider as shown here.

Minimum and maximum dates

Use the minDate and maxDate props to only allow dates within a given range to be selected in the calendar. Both props accept a Dayjs object. These values are inclusive endpoints, meaning that the date(s) provided can be selected. Learn more about these values in the Calendar documentation.

In the example below, only the dates from one month before today's date to one month after can be selected.

Note: The input fields will still allow users to enter dates outside of the defined minDate and maxDate values, so manual validation is required.

Exclude dates

Use the excludeDate prop to prevent certain dates from being selected in the calendar. excludeDate accepts a predicate function and checks each date in the current month against it. If the function returns true, the matching date will be disabled.

In the example below, the excludeDate function disables all Sundays and Saturdays.

Note: The excludeDate function does not prevent the excluded dates from being contained within a range, only from being selected as endpoints. Additionally, the input fields will still allow users to enter dates that are excluded, so manual validation is required.

Validation below menu

Form Compatibility

useState

useForm

Set the validationBelowMenu prop to true to relocate the error and success message validation to below the menu, when open.

The default is false and the validation message will always remain displayed below the selection container, even when the calendar is open.

Interactivity

Clearable

Set the isClearable prop to true to display a clear button in the input fields. The optional onClear callback prop can be used to trigger additional actions when the clear button is clicked.

Disabled

Set the isDisabled prop to true to disable the input fields, preventing user interaction. The inputs will still display the current values, but users cannot change them.

Enable outside scroll

Set the enableOutsideScroll prop to true to allow the page to be scrolled while the calendar is open. The default value is false.

Confirm selection

By default, selecting a date range in the calendar will set the range and close the calendar. By setting the confirmSelection prop to true, the calendar will display "Apply" and "Cancel" buttons and the user will have to press the "Apply" button to confirm the selection and close the calendar.

Use the onApply and onCancel props to add extra behavior to execute when the "Apply" and "Cancel" buttons are clicked, respectively. onApply will receive the selected dates as an object of the form:

{
  from: dayjs.Dayjs;
  to: dayjs.Dayjs;
}

Individual DateInput props

The DateInput components that make up DateInputRange can be customized to a degree. The following props can be passed to either the fromFieldConfig or toFieldConfig object to customize the respective DateInput:

• ref
• label
• hideLabel
• subText
• onFocus
• onBlur
• onPaste
• successMessage
• errorMessage
• onClear
• inputLeftElement
• onPickerButtonClick

See the DateInput docs for more information on the usage of these props.

Note: When using DateInputRange with useForm, the overall component's validation is used as described in the Validation section above, but the individual DateInput components will still use the successMessage and errorMessage props to display messages below the respective input fields.

Responsiveness

On screens 420px wide or smaller, the inputs will stack vertically and the calendar will be placed in a full-screen takeover instead of a popup. Resize the window to see the changes!

DateInputRange Props

Name	Type	Default	Required	Description
className	string	-	-	CSS class name to apply to each element within the component
confirmSelection	boolean	false	-	If true, the Calendar will only close when the user presses the "Apply" button
css	Abyss.CSSProperties | Partial<Record<`abyss-${T}`, Abyss.CSSProperties>>	-	-	Object containing CSS styling to apply; uses the classes listed in the "Integration" tab of the component's documentation See CSS Prop Styling for more information
data-testid	string	-	-	Suffix used to create a unique ID used for automated testing See Component Testing for more information
dateFormat	string	'MM/DD/YYYY'	-	A string representing the date format to be used in the input; must be compatible with the Day.js library.
disableDefaultProviderProps	boolean	false	-	If set to true, the component will not use the DefaultPropsProvider values. If you aren’t using the DefaultPropsProvider, this prop can be ignored.
enableOutsideScroll	boolean	false	-	If true, the page will remain scrollable when the popover is open
errorMessage	string | never	-	-	Error message to display for the input. Only used when not in a FormProvider. errorMessage should not exist in useForm mode.
excludeDate	(date: Dayjs) => boolean	-	-	Predicate function to exclude matching dates from the Calendar. This applies even to dates within the minDate and maxDate range, if applicable.
fromFieldConfig	DateInputRangeFieldProps	-	-	Props for the "From" date field
helper	React.ReactNode	-	-	Helper element next to label
hideLabel	boolean	false	-	If true, the label will be visually hidden
hidePlaceholders	boolean	false	-	If true, the placeholders in the inputs will be hidden
highlighted	boolean	false	-	If true, the input field will be highlighted
inputOnly	boolean	false	-	If true, only the input field will be rendered without the picker button and popover calendar
isClearable	boolean	-	-	If true, the input will display a clear button
isDisabled	boolean	false	-	If true, the input will be disabled
isOptional	boolean	false	-	If true, the label will be appended with "(Optional)"
isRequired	boolean | never	-	-	Whether the input is required. Only used when not in a FormProvider. isRequired should not exist in useForm mode.
label	string	-		The label for the input
matchAnchorWidth	boolean | undefined	true	-	If true, the Calendar will match the width of the input
maxDate	Dayjs	-	-	If present, the Calendar will only display dates of this value's month and earlier
minDate	Dayjs	-	-	If present, the Calendar will only display dates of this value's month and later
model	never | string	-	-	model should not exist in useState mode. Model name for form validation. Only used when in a FormProvider.
onApply	(selectedDates: { from?: Dayjs | undefined; to?: Dayjs | undefined; }) => void	-	-	Callback executed when the "Apply" button is clicked. Only used when confirmSelection is true.
onBlur	React.FocusEventHandler<HTMLInputElement>	-	-	Callback function executed when the input is blurred
onCancel	() => void	-	-	Callback executed when the "Cancel" button is clicked. Only used when confirmSelection is true.
onChange	(values: DateRange) => void	-	-	Callback function executed when the input value changes
onClear	() => void	-	-	Callback function executed when the input is cleared
onFocus	React.FocusEventHandler<HTMLInputElement>	-	-	Callback function executed when the input is focused
openPosition	"default" | "top" | "bottom" | undefined	'default'	-	Determines where the Calendar will open relative to the input
subText	string	-	-	Additional descriptive text for the input
successMessage	string	-	-	Success message to display for the input
toFieldConfig	DateInputRangeFieldProps	-	-	Props for the "To" date field
validationBelowMenu	boolean	false	-	If true, displays error and success validation messages below the menu
validators	DateInputRangeValidators	-	-	Enhanced validators that can return field-specific error messages for date input range validation
values	DateRange	-	-	The values of the input. Only used when not in a FormProvider.

Below are the link(s) to the relevant GitHub type files:

Abyss.d.ts

DateInputRange.types.ts

DateInput.types.ts

DateInputRange Classes

Class Name	Description
.abyss-date-input-range-root	The root container of the date input range
.abyss-date-input-range-input-label-wrapper	The wrapper for the input label
.abyss-date-input-range-range-label	The range label
.abyss-date-input-range-input-sub-text	The input sub text
.abyss-date-input-range-inputs-wrapper	The wrapper for the from and to inputs
.abyss-date-input-range-from-field	The from date input field
.abyss-date-input-range-to-field	The to date input field
.abyss-date-input-range-descriptors	The descriptors container
.abyss-date-input-descriptors	The descriptors for the individual date inputs
.abyss-date-input-range-label-wrapper	The wrapper for the takeover header label
.abyss-date-input-range-label	The takeover header label
.abyss-date-input-range-sub-text	The takeover header sub text
.abyss-date-input-range-format-text	The takeover header format text
.abyss-date-input-range-takeover-selection-display-container	The container for the selection display in the takeover
.abyss-date-input-range-from-selection-display-text	The from date selection display text
.abyss-date-input-range-to-selection-display-text	The to date selection display text
.abyss-date-input-range-takeover-calendars-container	The container for the calendars in the takeover
.abyss-date-input-range-takeover-calendar	The calendar component within the virtual list item

DateInput Classes

Class Name	Description
.abyss-date-input-input	The date input element
.abyss-date-input-calendar	The calendar
.abyss-date-input-root	Root element of PickerInput
.abyss-date-input-wrapper	Main wrapper for PickerInput content
.abyss-date-input-label-wrapper	Wrapper for label and subtext
.abyss-date-input-label	Label element for PickerInput
.abyss-date-input-sub-text	Subtext element (above or below input)
.abyss-date-input-format-text	Format text element (e.g. date format)
.abyss-date-input-field-wrapper	Wrapper for the input field and button
.abyss-date-input-focus-wrapper	Focus ring and input/clear button container
.abyss-date-input-input-wrapper	Wrapper for the input field and adjacent elements
.abyss-date-input-elements-container	Container for input elements
.abyss-date-input-left-element	Left element (e.g. icon) inside the input
.abyss-date-input-clear	Clear button for input
.abyss-date-input-picker-button	Popover open button
.abyss-date-input-icon	Icon inside the popover button
.abyss-date-input-descriptors	Validation or descriptor messages
.abyss-date-input-portal-container	Portal container for popover
.abyss-date-input-dismissable-layer	Dismissable layer for picker
.abyss-date-input-popover-wrapper	Popover wrapper for picker content
.abyss-date-input-takeover	Takeover container for mobile view
.abyss-date-input-takeover-selection-display-container	Container for the selection display in mobile takeover
.abyss-date-input-selection-display-text	Text element for the selection display
.abyss-date-input-takeover-button-container	Container for buttons in mobile takeover
.abyss-date-input-apply-button	Apply button
.abyss-date-input-cancel-button	Cancel button
.abyss-date-input-selection-display-wrapper	Wrapper for the selection display
.abyss-date-input-selection-display-root	Root element for the selection display
.abyss-date-input-selection-display-elements-container	Container for the elements in the selection display
.abyss-date-input-selection-display-clear	Clear button for the selection display

Calendar Classes

Class Name	Description
.abyss-calendar-root	Calendar root element
.abyss-calendar-header-root	Calendar header root element
.abyss-calendar-header-month-year-container	Calendar header month/year container
.abyss-calendar-header-previous-year-button	Calendar header previous year button
.abyss-calendar-header-previous-month-button	Calendar header previous month button
.abyss-calendar-header-next-month-button	Calendar header next month button
.abyss-calendar-header-next-year-button	Calendar header next year button
.abyss-calendar-header-month-button	Calendar header month button
.abyss-calendar-header-year-button	Calendar header year button
.abyss-calendar-day-grid-root	Calendar table root element
.abyss-calendar-day-grid-header	Calendar table header
.abyss-calendar-day-grid-header-row	Calendar table header row
.abyss-calendar-day-grid-header-cell	Calendar table header cell
.abyss-calendar-day-grid-body	Calendar table body
.abyss-calendar-day-grid-body-row	Calendar table body row
.abyss-calendar-footer	Calendar footer
.abyss-calendar-footer-filled-button	Calendar footer filled button
.abyss-calendar-footer-outline-button	Calendar footer outline button
.abyss-calendar-arrow-button	Arrow button root element
.abyss-calendar-arrow-button-icon	Arrow button icon element
.abyss-calendar-day-grid-day-cell	Day cell root element
.abyss-calendar-day-grid-day-button	Day cell button
.abyss-calendar-month-year-picker-header	Month/year picker header
.abyss-calendar-month-year-picker-back-button	Month/year picker back button
.abyss-calendar-month-year-picker-header-text	Month/year picker header text
.abyss-calendar-month-year-list-container	Month/year list container
.abyss-calendar-month-year-picker-list-option	Month/year picker list option

The example below includes date input range field that open a date picker that implements the dialog design pattern. The dialog contains a calendar that uses the grid pattern to present buttons that enable the user to choose a day from the calendar. Choosing a date from the calendar closes the dialog and populates the date input field. When the dialog is opened, if the input field is empty, or does not contain a valid date, then the current date is focused in the calendar. Otherwise, the focus is placed on the day in the calendar that matches the value of the date input field. Opening the calendar from either the start date or end date button prompts the user to select the first day and then the last day.

Adheres to the Date Picker Dialog WAI-ARIA design pattern.

Date Picker Dialog Keyboard Interactions

Key	Description
Esc	Closes the dialog and returns focus to the Choose Starting Date or Choose Ending Date button
Tab	Moves focus to next element in the dialog Tab sequence
Shift + Tab	Moves focus to previous element in the dialog Tab sequence

Date Picker Dialog: Month/Year Buttons Keyboard Interactions

Key	Description
Space	Change the month and/or year displayed in the calendar grid
Enter	Change the month and/or year displayed in the calendar grid

Date Picker Dialog: Date Grid Keyboard Interactions

Key	Description
Space	Select the date, close the dialog, and move focus to the Choose Starting Date or Choose Ending Date button
Enter	Select the date, close the dialog, and move focus to the Choose Starting Date or Choose Ending Date button
Up Arrow	Moves focus to the same day of the previous week
Down Arrow	Moves focus to the same day of the next week
Right Arrow	Moves focus to the next day
Left Arrow	Moves focus to the previous day
Page Up	Changes the grid of dates to the previous month
Page Down	Changes the grid of dates to the next month
Shift + Page Down	Changes the grid of dates to the next Year
Shift + Page Up	Changes the grid of dates to the previous Year

Known BrAT issues

JAWS announces formatting hint characters (default: "__/__/____") in date inputs.

• By default, JAWS announces the date format characters shown in the field
• NVDA and VoiceOver ignore these characters and announce updates without them

Component Tokens

Note: Click on the token row to copy the token to your clipboard.

Search tokens

DateInputRange Tokens

Token Name	Value
date-input-range.color.border.selection-indicator	#E5E5E6
date-input-range.color.text.selection-indicator	#4B4D4F
date-input-range.border-width.bottom.separator	1px
date-input-range.spacing.gap.horizontal.web.fields	16px
date-input-range.spacing.gap.vertical.container	16px
date-input-range.spacing.gap.vertical.mobile.fields	16px
date-input-range.spacing.gap.vertical.takeover-input-container	16px
date-input-range.spacing.padding.all.takeover-week-days	16px
date-input-range.spacing.padding.bottom.takeover-input-container	24px
date-input-range.spacing.padding.horizontal.takeover-input-container	16px
date-input-range.spacing.padding.top.takeover-calendar	16px
date-input-range.spacing.padding.top.takeover-input-container	16px

Search tokens

DateInput Tokens

Token Name	Value
date-input.color.border.selection-indicator	#E5E5E6
date-input.color.icon.default	#323334
date-input.color.icon.disabled	#7D7F81
date-input.color.icon.utility.active	#000000
date-input.color.icon.utility.hover	#323334
date-input.color.icon.utility.rest	#4B4D4F
date-input.color.surface.button.active	#E5E5E6
date-input.color.surface.button.hover	#F3F3F3
date-input.color.surface.button.rest	#FFFFFF
date-input.color.surface.picker-mobile	#FFFFFF
date-input.color.surface.selection-indicator.default	#F3F3F3
date-input.color.surface.selection-indicator.highlighted	#E5F8FB
date-input.color.text.sub-label	#4B4D4F
date-input.color.text.selection-indicator	#4B4D4F
date-input.border-radius.all.selection-indicator	4px
date-input.border-width.all.selection-indicator	1px
date-input.border-width.bottom.separator	1px
date-input.sizing.all.icon	20px
date-input.spacing.gap.horizontal.takeover-button-container	8px
date-input.spacing.gap.horizontal.selection-indicator	12px
date-input.spacing.gap.vertical.selection-indicator	8px
date-input.spacing.padding.all.takeover-button-container	16px
date-input.spacing.padding.all.takeover-header	16px
date-input.spacing.padding.bottom.takeover-input-container	24px
date-input.spacing.padding.horizontal.takeover-input-container	16px
date-input.spacing.padding.horizontal.selection-indicator	12px
date-input.spacing.padding.top.takeover-input-container	16px

Search tokens

Calendar Tokens

Token Name	Value
calendar.color.border.container	#CBCCCD
calendar.color.border.day-button.today	#002677
calendar.color.icon.utility.active	#00184D
calendar.color.icon.utility.disabled	#7D7F81
calendar.color.icon.utility.hover	#004BA0
calendar.color.icon.utility.rest	#002677
calendar.color.surface.container	#FFFFFF
calendar.color.surface.day-button.default.active	#E5E5E6
calendar.color.surface.day-button.default.hover	#F3F3F3
calendar.color.surface.day-button.default.rest	#FFFFFF
calendar.color.surface.day-button.range.active	#D9E9FA
calendar.color.surface.day-button.range.hover	#E3EEFA
calendar.color.surface.day-button.range.rest	#EDF3FB
calendar.color.surface.day-button.range.background	#D9E9FA
calendar.color.surface.day-button.selected.active	#00184D
calendar.color.surface.day-button.selected.hover	#004BA0
calendar.color.surface.day-button.selected.rest	#002677
calendar.color.surface.day-button.cell.range	#EDF3FB
calendar.color.text.header	#002677
calendar.color.text.day-button.disabled	#7D7F81
calendar.color.text.day-button.default	#002677
calendar.color.text.day-button.range	#002677
calendar.color.text.day-button.selected	#FFFFFF
calendar.color.text.week-days	#4B4D4F
month-year-picker.color.border.separator	#CBCCCD
month-year-picker.color.surface.container	#FFFFFF
month-year-picker.color.text.heading	#002677
calendar.border-radius.all.container	4px
calendar.border-radius.all.day-button	500px
calendar.border-width.all.container	1px
calendar.border-width.all.today	2px
month-year-picker.border-width.separator	1px
calendar.sizing.all.icon.utility	24px
calendar.spacing.gap.horizontal.footer	8px
calendar.spacing.gap.horizontal.header	8px
calendar.spacing.gap.horizontal.header-buttons	8px
calendar.spacing.padding.bottom.container	8px
calendar.spacing.padding.horizontal.container	16px
calendar.spacing.padding.vertical.footer	8px
calendar.spacing.padding.vertical.header	8px
calendar.spacing.padding.vertical.header-button	8px
calendar.spacing.padding.vertical.week-days	4px
calendar.spacing.padding.vertical.week-row	4px
month-year-picker.spacing.gap.horizontal.header	8px
month-year-picker.spacing.padding.all.header	16px
calendar.elevation.container	0px 2px 4px -2px rgba(0,0,0,0.16)

Search tokens

Input Tokens

Token Name	Value
input.color.surface.field.default	#FFFFFF
input.color.surface.field.highlighted	#E5F8FB
input.color.surface.field.disabled	#F3F3F3
input.color.border.field.rest	#4B4D4F
input.color.border.field.hover.default	#196ECF
input.color.border.field.hover.error	#990000
input.color.border.field.hover.success	#007000
input.color.border.field.active.default	#004BA0
input.color.border.field.active.error	#990000
input.color.border.field.active.success	#007000
input.color.text.input	#4B4D4F
input.color.text.hint	#4B4D4F
input.color.text.required	#990000
input.color.icon.utility.rest	#4B4D4F
input.color.icon.utility.hover	#323334
input.color.icon.utility.active	#000000
input.color.icon.content	#323334
input.border-radius.all.field	4px
input.border-width.all.field.default	1px
input.border-width.all.field.active	3px
input.sizing.all.icon	20px
input.spacing.gap.vertical.container	8px
input.spacing.gap.horizontal.field	12px
input.spacing.gap.horizontal.input-indicator	2px
input.spacing.gap.horizontal.prefix-input	2px
input.spacing.gap.horizontal.suffix-clear	2px
input.spacing.padding.all.focus-container	2px
input.spacing.padding.horizontal.field	12px
input.spacing.padding.left.field	12px
input.spacing.padding.right.focus-field	44px

Search tokens

Header Tokens

Token Name	Value
input-header.color.text.label	#4B4D4F
input-header.color.text.hint	#4B4D4F
input-header.color.icon.info.rest	#196ECF
input-header.color.icon.info.hover	#004BA0
input-header.color.icon.info.active	#002677
input-header.sizing.all.icon	24px
input-header.spacing.gap.horizontal.container	4px
input-header.spacing.gap.horizontal.label	4px
input-header.spacing.gap.vertical.content	4px
input-header.spacing.padding.top.content	2px

Search tokens

Validation Tokens

Token Name	Value
input-validation.color.surface.container	#FFFFFF
input-validation.color.text.error	#990000
input-validation.color.text.success	#007000
input-validation.color.icon.error	#990000
input-validation.color.icon.success	#007000
input-validation.sizing.all.icon	20px
input-validation.spacing.gap.horizontal.container	4px