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();

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

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.

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

Note: The format must be compatible with the Day.js library. 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

Note: 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.

Note: 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.

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

Note: 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.

Note: 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	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.
helper	React.ReactNode	-	-	Helper element next to label
hideLabel	boolean	false	-	If true, the label will be visually hidden
hidePlaceholder	boolean	false	-	If true, the placeholder in the input will be hidden
highlighted	boolean	false	-	If true, the input field will be highlighted
inputLeftElement	{ element: React.ReactNode; description?: string | undefined; }	-	-	Content to be displayed as a left element within the input (typically a IconSymbol)
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	(selectedDate: Dayjs) => 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	React.ChangeEventHandler<HTMLInputElement>	-	-	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
onMonthChange	(activeMonth: Dayjs) => void	-	-	Callback function executed when the active/displayed month changes
onOpenChange	(isOpen: boolean) => void	-	-	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
subText	string | { text: string; position: SubTextPosition; }	-	-	Additional descriptive text for the input
successMessage	string	-	-	Success message to display for the input
validationBelowMenu	boolean	false	-	If true, displays error and success validation messages below the menu
validators	never | RegisterOptions	-	-	validators should not exist in useState mode. Validators for the input. Only used when in a FormProvider.
value	ValueType | never	-	-	The value of the input. Only used when not in a FormProvider. value should not exist in useForm mode.

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

Abyss.d.ts

DateInput.types.ts

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

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

For calendar accessibility information, see: Calendar Accessibility documentation.

Component Tokens

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

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