import { DateInput } from '@uhg-abyss/mobile';Usage
The DateInput component allows users to select a date or time from a picker. The picker will display a calendar for date selection and a time picker for time selection.
The time picker is an internal component, but Calendar is a separate component that can be used independently.
Keyboard Entry
Users can enter the date or time with the native keyboard by pressing the input box. The date or time entered can be read from the value prop. Use the onSubmit prop to handle the action when the submit key is pressed.
The date input validates against the configured dateFormat pattern using Day.js parsing. The default date pattern is MM/DD/YYYY.
Validation occurs when keyboard entry is submitted or editing ends. Text that does not match the configured format remains in the field so the user can correct it.
The time input will not accept an entry if it is not in 12-hour hh:mm AM/PM format with leading zeros.
The tokens in dateFormat determine which keyboard is shown and how the entry is formatted as the user types:
dateFormat | Keyboard | Entry |
|---|---|---|
Fixed-width numeric, such as MM/DD/YYYY or YYYY-MM-DD | Numeric keypad | Separators are inserted automatically |
Single-width numeric, such as M/D/YYYY | Numeric keyboard with punctuation on iOS, default on Android | Separators are inserted automatically, and leading zeros are not required |
Textual, such as MMMM D, YYYY | Default keyboard | Validated as typed on submission, with no formatting applied |
Ambiguous entries
Formats with single-width M or D tokens accept a date without leading zeros, so 8122026 becomes 8/12/2026. A few entries can be read two ways: 1192023 is both 1/19/2023 and 11/9/2023.
Rather than guess and silently commit the wrong date, the field leaves those entries as typed and stops inserting separators. Typing the separator resolves them, and both 1/19/2023 and 11/9/2023 are accepted. Submitting an unresolved entry reports an invalid entry with code 0.
This affects January 10–29, November 1–9, and December 1–9. Use a fixed-width format such as MM/DD/YYYY if users should never encounter it.
Date Format
Use the dateFormat prop to control the date keyboard entry pattern and displayed date value when mode="date".
- Must be a Day.js-compatible format string.
- Default value is
MM/DD/YYYY. - Formats with single-width
MorDtokens have a small number of ambiguous entries. - See Day.js format reference: https://day.js.org/docs/en/display/format
When a controlled value is present, changing dateFormat reformats the displayed value without changing the underlying Date.
useState
The useState hook gets values from the component state. A date value is required and will be displayed in the input box and as the selected date or time on the picker.
Mode
Use the mode prop to define the type of picker. The default mode is set to "date"
Date
Time
Label
Use the label prop to display a label above the input menu.
Help Content
The helpContent prop is used to display a help icon in the top right of the container, which will display the provided content in a BottomSheet when pressed.
Required
Use the isRequired prop to display an asterisk next to the label when using useState.
Disabled
Set the isDisabled prop to true to disable the date picker.
Error Message (useState)
Use the errorMessage prop to display a custom error message below the menu when using useState.
Success Message
Use the successMessage prop to display a custom success message below the menu.
Excluded Dates
To exclude dates use the excludeDate prop. Set a function that receives date as an argument and returns true if date should be disabled. For example, to disable weekends, check if the day is 0 or 6.
Min/Max Date
Date
Use the minimumDate and maximumDate props to set the min and max dates in the Calendar dropdown.
Time
Use the minimumDate and maximumDate props to set the min and max times in the Time dropdown.
onInvalidEntry
Use the onInvalidEntry prop to handle the date validation. The function returns an object
{ value: Date, input: string, code: number, message: string } where value is the Date instance of the user's attempted entry,
input is the string submitted by the user, code indicates a custom code that references a specific error and
message describes the error.
The explanation of code is noted below:
- 0 - Indicates the input date is invalid, including an entry that could be read as more than one date.
- 1 - Indicates the input is before the minimum date.
- 2 - Indicates the input is after the maximum date.
- 3 - Indicates the input is a disabled date.
DateInput Props
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
dateFormat | string | undefined | 'MM/DD/YYYY' | - | A string representing the date format to be used in date mode; must be compatible with the Day.js library. Fixed-width numeric formats (MM, DD, YY, YYYY) use a numeric keypad and insert separators as the user types. Formats with single-width tokens (M, D) do the same but offer a separator key, because entries such as 1192023 read as both 1/19/2023 and 11/9/2023; those are left as typed until a separator resolves them. Formats with textual tokens are validated as entered on submission. |
errorMessage | string | undefined | - | - | Sets the error message to be displayed below the date input field |
excludeDate | (date: Date) => boolean | undefined | - | - | Callback to exclude dates from the calendar |
helpButtonAccessibilityLabel | string | undefined | - | - | Sets the accessibility label for the help button |
helpContent | React.ReactNode | undefined | - | - | When defined, displays a help icon that can be tapped to view the provided content in a modal screen |
hintText | string | undefined | - | - | Set the hint text of the date input |
isDisabled | boolean | undefined | false | - | Flag to enable/disable the picker. If true, the picker will be disabled |
isRequired | boolean | undefined | false | - | Flag to add an asterisk next to the label, indicating that the field is required. This is independent of form validation and is only for visual purposes. |
label | string | undefined | - | - | Label for date or time input field |
maximumDate | Date | undefined | - | - | Specifies the maximum selectable day by a user' |
minimumDate | Date | undefined | - | - | Specifies the minimum selectable day by a user |
mode | 'time' | 'date' | undefined | 'date' | - | Sets the mode of the date input to capture date or time entry |
model | never | string | undefined | - | - | model is only used when the input is bound to a form via useForm. Model name used to bind the input to the form state. Only used inside a FormProvider. |
onChange | (date?: Date) => void | undefined | - | - | Callback fired every time the value changes |
onChangeText | (text: string) => void | undefined | - | - | Callback fired every time the text changes during manual entry |
onInvalidEntry | (props: InvalidEntryProps) => void | undefined | - | - | Callback fired on date entry validation. Returns the entered date value |
showOptionalLabel | boolean | undefined | - | - | Flag to display 'optional' next to the label |
successMessage | string | undefined | - | - | Sets the success message to be displayed below the date input field |
validations | Validations | undefined | - | - | Set rules for the input to be valid. Valid in both useState and useForm modes. Set rules for the input to be valid. |
value | Date | undefined | - | - | Value of the date input |
DateInput Classes
| Class Name | Description |
|---|---|
| abyss-date-input-root | Root element |
| abyss-date-input-header | Header element |
| abyss-date-input-label | Label element |
| abyss-date-input | Date input element |
| abyss-date-input-hint-text | Hint text element |
| abyss-date-input-format-text | Format text element |
| abyss-date-input-button | Input button element |
| abyss-date-input-submit-button | Submit button element |
| abyss-date-input-icon-button | The date or time picker button |
| abyss-date-input-icon | The date or time picker icon |
| abyss-date-input-message | Message element |
| abyss-date-input-bottom-sheet | Bottom sheet element |
| abyss-date-input-help-button | Help button |
| abyss-date-input-help-modal | Help modal |
| abyss-input-help-icon | Help icon element |
| abyss-input-help-modal-footer | Help modal footer |
| abyss-input-help-modal-close-button | Help modal close button |
| abyss-input-message-icon | Message icon |
| abyss-input-message-text | Message text |
| abyss-date-input-calendar | Calendar |
| abyss-date-input-time-picker | Time picker |
DateInput Translations
| Translation Key | Value |
|---|---|
| help | Help |
| close | Close |
| error | Error |
| success | Success |
| selected | Selected |
| DateInput.selectDate | Select Date |
| DateInput.selectTime | Select Time |
| TimePicker.hours | Hours |
| TimePicker.minutes | Minutes |
| TimePicker.AM | AM |
| TimePicker.PM | PM |
| Calendar.prevMonth | Previous Month |
| Calendar.nextMonth | Next Month |
| Calendar.year | Year |
| Calendar.today | Today |
| Calendar.inProgress | In Progress |
Picker
Both date and time pickers are accessible on iOS and Android when a screen reader (VoiceOver or TalkBack) is active. On iOS users can swipe up or down to increment or decrement the selected value, Android uses left and right swipes. The value is announced after each change.
Keyboard entry
Both date and time modes support direct keyboard entry without opening the picker. The text input announces the expected format based on the mode (the string passed to the dateFormat prop or hh:mm AM/PM) and any active error message to screen readers via the accessibility hint.
DateInput Tokens
| Token Name | Value | |
|---|---|---|
| input-header.color.text.label | #4B4D4F | |
| input-header.color.text.hint | #4B4D4F | |
| input-header.color.icon.help.rest | #196ECF | |
| input-header.color.icon.help.active | #004BA0 | |
| input-message.color.text.error | #990000 | |
| input-message.color.text.success | #007000 | |
| input-message.color.icon.error | #990000 | |
| input-message.color.icon.success | #007000 | |
| input-field.color.surface.default | #FFFFFF | |
| input-field.color.surface.disabled | #F3F3F3 | |
| input-field.color.text.input | #4B4D4F | |
| input-field.color.border.rest.default | #4B4D4F | |
| input-field.color.border.rest.error | #990000 | |
| input-field.color.border.rest.success | #007000 | |
| input-field.color.border.active.default | #196ECF | |
| input-field.color.border.active.error | #990000 | |
| input-field.color.border.active.success | #007000 | |
| input-field.color.icon.utility.rest | #4B4D4F | |
| input-field.color.icon.utility.disabled | #929496 | |
| input-field.color.icon.utility.active | #323334 | |
| input-field.border-radius.all.container | 4 | |
| input-field.border-width.all.container.rest | 1 | |
| input-field.border-width.all.container.active | 3 | |
| input-header.sizing.all.icon.help | 24 | |
| input-message.sizing.all.icon.leading | 20 | |
| input-field.sizing.icon.all.utility | 20 | |
| input-field.sizing.icon.all.picker | 20 | |
| input-container.spacing.gap.vertical.container | 8 | |
| input-header.spacing.gap.horizontal.container | 12 | |
| input-header.spacing.gap.horizontal.label | 4 | |
| input-header.spacing.gap.vertical.content | 4 | |
| input-message.spacing.gap.horizontal.container | 4 | |
| input-field.spacing.padding.all.field | 12 | |
| input-field.spacing.gap.horizontal.field | 12 | |
| input-field.spacing.gap.horizontal.input-indicator | 2 | |
| input-field.spacing.gap.horizontal.prefix-input | 2 | |
| input-field.box-shadow.container.active |
| |
| input-field.box-shadow.container.error |
| |
| input-field.box-shadow.container.success |
|