Components

Date input

Use: Deployed

Use the date input component to help users enter a date they would know or a date they can approximate.

Examples

Usage

When to use date input

Use a month, day, year date input component for a date a user knows, like a date of birth or marriage. (Example: July 21, 1992). Or a date they can easily look up (for example, the expiration date of a credit card).
Use the month year variant for a date a user can approximate, like a date they graduated from high school or a GED equivalent. (Example: May 2010)

When to consider something else

Do not use the date input component if users are unlikely to know the exact date of the event you’re asking about. You may consider using a date picker for scheduling, with the following caveats

We do not currently have a calendar picker as part of the design system. For reference, visit the VA online scheduling tool (VAOS) to see an experimental version of a calendar picker.
Date pickers have not been tested for accessibility, and may lead to launch blocking issues for your product unless carefully designed with an accessibility specialist. We strongly recommend reaching out to #accessibility-help on slack for support before considering this pattern.

How to use date inputs

The component consists of two select boxes for month and day inputs and a text input for year input. For those components please check the usability guidance for select boxes and text inputs
For the month select box, provide the user unabbreviated months to choose from. Example: January

Validation

By default all date components have the following validation:

Cannot have blank values
Month and Day must be valid numbers
The Year cannot fall outside of the range of 1900 through the current year plus 100 years

The option to add custom validation is available as well.

Code usage

Attributes and Properties

Property	Attribute	Type	Default	Description
`enableAnalytics`	`enable-analytics`	`boolean`	`false`	Whether or not an analytics event will be fired.
`error`	`error`	`string`		The error message to render (if any) This prop should be leveraged to display any custom validations needed for this component
`hint`	`hint`	`string`		Optional hint text.
`invalidDay`	`invalid-day`	`boolean`	`false`
`invalidMonth`	`invalid-month`	`boolean`	`false`
`invalidYear`	`invalid-year`	`boolean`	`false`
`label`	`label`	`string`		Label for the field.
`monthOptional`	`month-optional`	`boolean`	`false`	Whether month should be optional; has no effect unless monthYearOnly is true
`monthYearOnly`	`month-year-only`	`boolean`	`false`	Whether or not only the Month and Year inputs should be displayed.
`name`	`name`	`string`		Used to create unique name attributes for each input.
`required`	`required`	`boolean`	`false`	Render marker indicating field is required.
`value`	`value`	`string`		Set the default date value must be in YYYY-MM-DD format.

Events

Name	Description
`component-library-analytics`	The event used to track usage of the component. This is emitted when an input value changes and enableAnalytics is true.
`dateBlur`	Fires when the date input loses focus
`dateChange`	Fires when the date input loses focus after its value was changed

Accessibility considerations

Follow text input and select box guidance. The component consists of two select boxes for month and day inputs and a text input for year input.

Date input

Examples

Default

Month/Year

With hint text

With a custom required message

Default with error

With hint text and error

With custom validation