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 { DateInput } from '@uhg-abyss/web/ui/DateInput';

label

subText

errorMessage

successMessage

dateFormat

hideLabel

isClearable

isDisabled

highlighted

matchAnchorWidth

() => {
  const [value, setValue] = useState<string>();

  return (
    <DateInput
      label="DateInput Sandbox"
      value={value}
      onChange={(e) => setValue(e.target.value)}
    />
  );
};

Day.js

DateInput relies on the Day.js library to handle date operations. Several inputs to the DateInput 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 separatelyopens in a new window.

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

Variants

Input with calendar

The default variant for DateInput is an input field with a button to open a calendar.

Input only

Use the inputOnly prop when the date can be easily entered without a calendar; for example, when entering a birthday.

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 input. To hide the input label, set hideLabel to true.

Use isRequired and isOptional for further customization.

useState only

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 field. The prop accepts either a string or an object of the form:

{
  text: string;
  position: 'above' | 'below';
}

The position property determines where the subtext will be displayed in relation to the input field. The default value is 'below'.

Date format

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

Important

The format must be compatible with the Day.js libraryopens in a new window. Due to the input mask used, DateInput 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

Important

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

Hide placeholder

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

Note

The formatting mask is unaffected by this prop. The placeholder is only visible if there is no text in the input.

Width

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

Left element

Use the inputLeftElement prop to add an element inside of the text input field. The recommended usage is for inserting icons. The prop accepts an object with the following properties:

• element: The element to be displayed inside the input field.
• description: An optional string that describes the purpose of the element for screen readers.

These are considered decorative and do not need to be exposed to screen readers. That said, please note that icons should not provide any information that is not also conveyed in a screen-readable way. For example, an exclamation mark (!) icon to indicate errors needs to be accompanied by aria-invalid.

If the icon is used to convey additional information, use the inputLeftElement.description prop to provide a description for screen readers.

Tip

The recommended usage is when using the inputOnly prop.

Match anchor width

By default, the calendar will match the width of the input field. 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.

Tip

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 field 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.

Warning

The input field 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.

Warning

The input field 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 field. 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 field, preventing user interaction. The input will still display the current value, but users cannot change it.

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, clicking on a date in the calendar will set that date as the selected date 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 date as a Dayjs object.

Responsiveness

On screens 360px wide or smaller, the calendar will be placed in a full-screen takeover instead of a popup. Resize the window and open the calendar to see the change!

DateInput Props

Name	Type	Default	Required	A11y	Description
className	string | undefined				CSS class name to apply to each element within the component
confirmSelection	boolean | undefined	false			If true, the Calendar will only close when the user presses the "Apply" button
css	CSSProperties | Partial<Record<"abyss-date-input-input" | "abyss-date-input-calendar" | "abyss-date-input-picker-input", CSSProperties>> | undefined				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 | undefined				Suffix used to create a unique ID used for automated testing See Component Testing for more information
dateFormat	string | undefined	'MM/DD/YYYY'			A string representing the date format to be used in the input, exposed to screen readers via aria-describedby so users know the expected format; must be compatible with the Day.js library.
disableDefaultProviderProps	boolean | undefined	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 | undefined	false			If true, the page will remain scrollable when the popover is open
errorMessage	string | undefined				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) | undefined				Predicate function to exclude matching dates from the Calendar. This applies even to dates within the minDate and maxDate range, if applicable.
helper	string | number | bigint | boolean | ReactElement<any, string | JSXElementConstructor<any>> | Iterable<ReactNode> | ReactPortal | Promise<...> | null | undefined				Helper element next to label
hiddenFrom	Breakpoint | undefined				When defined, the component is hidden once the screen width reaches the specified breakpoint.
hideLabel	boolean | undefined	false			If true, hides the label visually while keeping it accessible to screen readers.
hidePlaceholder	boolean | undefined	false			If true, the placeholder in the input will be hidden
highlighted	boolean | undefined	false			If true, the input field will be highlighted
inputLeftElement	{ element: ReactNode; description?: string | undefined; } | undefined				Content to be displayed as a left element within the input (typically a IconSymbol)
inputOnly	boolean | undefined	false			If true, only the input field will be rendered without the picker button and popover calendar
isClearable	boolean | undefined				If true, the input will display a clear button
isDisabled	boolean | undefined	false			If true, the input will be disabled
isOptional	boolean | undefined	false			If true, the label will be appended with "(Optional)"
isRequired	boolean | undefined				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; associated with it so screen readers announce it as the input's accessible name.
matchAnchorWidth	boolean | undefined	true			If true, the Calendar will match the width of the input
maxDate	Dayjs | undefined				If present, the Calendar will only display dates of this value's month and earlier
minDate	Dayjs | undefined				If present, the Calendar will only display dates of this value's month and later
model	string | undefined				model should not exist in useState mode. Model name for form validation. Only used when in a FormProvider.
onApply	((selectedDate: Dayjs) => void) | undefined				Callback executed when the "Apply" button is clicked. Only used when confirmSelection is true.
onBlur	FocusEventHandler<HTMLInputElement> | undefined				Callback function executed when the input is blurred
onCancel	(() => void) | undefined				Callback executed when the "Cancel" button is clicked. Only used when confirmSelection is true.
onChange	ChangeEventHandler<HTMLInputElement> | undefined				Callback function executed when the input value changes
onClear	(() => void) | undefined				Callback function executed when the input is cleared
onFocus	FocusEventHandler<HTMLInputElement> | undefined				Callback function executed when the input is focused
onMonthChange	((activeMonth: Dayjs) => void) | undefined				Callback function executed when the active/displayed month changes
onOpenChange	((isOpen: boolean) => void) | undefined				Callback executed when the Calendar open state changes
onPickerButtonClick	(() => void) | undefined				Callback executed when the picker button is clicked
openPosition	"default" | "top" | "bottom" | undefined	'default'			Determines where the Calendar will open relative to the input
slotProps	DateInputSlotPropsMap | undefined				Props to pass to individual internal slots of the component. See slotProps for more information
subText	string | { text: string; position: SubTextPosition; } | undefined				Additional descriptive text for the input
successMessage	string | undefined				Success message to display for the input
validationBelowMenu	boolean | undefined	false			If true, displays error and success validation messages below the menu
validators	RegisterOptions | undefined				validators should not exist in useState mode. Validators for the input. Only used when in a FormProvider.
value	string | (readonly string[] & string) | undefined				The value of the input. Only used when not in a FormProvider. value should not exist in useForm mode.
visibleFrom	Breakpoint | undefined				When defined, the component is hidden until the screen width reaches the specified breakpoint.

DateInput Classes

Class Name	Description
.abyss-date-input-calendar	The calendar
.abyss-date-input-input	The date input element
.abyss-date-input-picker-input	PickerInput rendered by DateInput

Calendar Classes

Class Name	Description
.abyss-calendar-arrow-button	Arrow button root element
.abyss-calendar-arrow-button-icon	Arrow button icon element
.abyss-calendar-day-grid-body	Calendar table body
.abyss-calendar-day-grid-body-row	Calendar table body row
.abyss-calendar-day-grid-day-button	Day cell button
.abyss-calendar-day-grid-day-cell	Day cell root element
.abyss-calendar-day-grid-header	Calendar table header
.abyss-calendar-day-grid-header-cell	Calendar table header cell
.abyss-calendar-day-grid-header-row	Calendar table header row
.abyss-calendar-day-grid-root	Calendar table root element
.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-header-month-button	Calendar header month button
.abyss-calendar-header-month-year-container	Calendar header month/year container
.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-previous-month-button	Calendar header previous month button
.abyss-calendar-header-previous-year-button	Calendar header previous year button
.abyss-calendar-header-root	Calendar header root element
.abyss-calendar-header-year-button	Calendar header year button
.abyss-calendar-month-year-list-container	Month/year list container
.abyss-calendar-month-year-picker-back-button	Month/year picker back button
.abyss-calendar-month-year-picker-header	Month/year picker header
.abyss-calendar-month-year-picker-header-text	Month/year picker header text
.abyss-calendar-month-year-picker-list-option	Month/year picker list option
.abyss-calendar-root	Calendar root element

Adheres to the Date Picker Dialog WAI-ARIA design patternopens in a new window.

For calendar accessibility information, see: Calendar Accessibility documentation.

Component Tokens

Tip

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

DateInput Tokens

Search 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

Calendar Tokens

Search 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)

Input Tokens

Search 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.color.cursor	#196ECF
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

Header Tokens

Search 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

Validation Tokens

Search 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