Components

Memorable date

Use with caution: Available English, Spanish

USWDS v3

Three text fields are the easiest way for users to enter most dates.

Examples

Usage

Refer to the U.S. Web Design System for usage guidance

Choosing between variations

Unlike the USWDS, the default component uses a text input instead of a select input for the month. This was done after user testing showed inconsistencies between field types led to challenges for users of assistive technology. Teams should note the maturity of this component and proceed with caution.

Errors

Refer to the specific error examples above.

View form error handling for additional guidance

Hint text

Refer to the hint text example above.

View label hint text for additional guidance

Code usage

Attributes and Properties

Property	Attribute	Type	Default	Description
`customDayErrorMessage`	`custom-day-error-message`	`string`		A custom error message to display if the day is invalid
`customMonthErrorMessage`	`custom-month-error-message`	`string`		A custom error message to display if the month is invalid
`customYearErrorMessage`	`custom-year-error-message`	`string`		A custom error message to display if the year is invalid
`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
`formHeading`	`form-heading`	`string`		The content of the heading if `useFormsPattern`.
`formHeadingLevel`	`form-heading-level`	`number`	`3`	The heading level for the heading if `useFormsPattern`.
`hint`	`hint`	`string`		Hint text string
`invalidDay`	`invalid-day`	`boolean`	`false`
`invalidMonth`	`invalid-month`	`boolean`	`false`
`invalidYear`	`invalid-year`	`boolean`	`false`
`label`	`label`	`string`		Label for the field.
`monthSelect`	`month-select`	`boolean`	`false`	Whether or not to use the month as an input or select.
`name`	`name`	`string`		Used to create unique name attributes for each input.
`required`	`required`	`boolean`	`false`	Render marker indicating field is required.
`useFormsPattern`	`use-forms-pattern`	`string`		Enabling this will add a heading and description for integrating into the forms pattern. Accepts `single` or `multiple` to indicate if the form is a single input or will have multiple inputs.
`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

Refer to the U.S. Web Design System for accessibility guidance

Component checklist

Maturity

Guidance: Examples, usage, code usage, content considerations, and accessibility considerations are all complete.
Research: VFS team conducted research on this component which is linked from this page.
Stability: Component has been in production for more than 3 months with no significant issues found.
Adoption: Multiple teams have adopted this component.; Note: This component was introduced in August 2022.

Accessibility

While this component has been previously tested against older criteria, it has not yet been audited with the updated testing criteria.

Code assets

Variations: Storybook includes all variations (style, size, orientation, optional iconography, selection, error state, etc.)
Responsive: Component depicted in all responsive breakpoints.
Interactive states: Includes all interactive states that are applicable (hover, active, focus, keyboard focus, disabled).
Tokens: All design attributes (color, typography, layout, etc.) are available as tokens.
Internationalization: Describes i18n attributes.

Visual assets

Variations: Sketch library includes all variations (style, size, orientation, optional iconography, selection, error state, etc.)
Responsive: Component designed to work in all responsive breakpoints.
Interactive states: Includes all interactive states that are applicable (hover, active, focus, keyboard focus, disabled).
Tokens: All design attributes (color, typography, layout, etc.) are available as tokens.

80% complete (8 of 10)

Legend:

Complete
Incomplete
Not applicable

Memorable date

Examples

Default

Month select

Extra hint text

Custom validation

Forms pattern single default

Forms pattern multiple

Error

Error with month select

Forms pattern single error

Forms pattern multiple error

Internationalization