Examples

Guidance

When to use

• Use the date picker for dates that have happened within the last year, in the future, or is relevant to selecting the day of the week.

Guidelines

Allow users to have flexibility in entering the date, such as allowing one-digit numbers with or without "0" prior to the number, or entering a date with or without slashes to separate month, day, and year.

• Example: "01" for a month or day. Leading zeros for single digits are necessary if you do not include separating characters between the month, day and year values.
• Example: "05/18/2022" as well as "05182022".

When to consider alternatives

• Don't use if users are entering a memorable date. Instead, use either single- or multi-input date fields.
• Don't use if the date occurred in the distant past (like date of birth).

Accessibility

Accessibility

• Please see the accessibility guidelines for all text inputs for information specific to the input fields.
• The calendar button uses aria-describedby to connect the required label text (supplied via the label prop) and the optional hint text (provided by the hint prop), to ensure screen readers announce contextual information when the open calendar button receives focus.
• Users will be able to enter a variety of date formats that automatically format to the correct date format of MM/DD/YYYY. This change happens once the form field loses focus. For example, a user enters a date as "04122020" and it changes to "04/12/2020" once focus leaves the date input.
• Focus automatically returns to the date input field after date selection.

Accessibility Testing

Keyboard:

• Keyboard interactions follow the guidelines put forth by the ARIA Authoring Practices Guide for the Date Picker Dialog pattern

  You are leaving design.cms.gov.

  You're about to connect to a third-party site. Select CONTINUE to proceed or CANCEL to stay on this site.

  ContinueCancel
  .
• A notable exception to the above pattern is that the CMSDS does not yet support usage of the ESC key to close the dialog.
• Tab: Moves between the date input field and calendar button. When the calendar is initially opened, pressing tab will move focus first from a previous month selection button then to the month selection dropdown, next the year selection dropdown and finally the date entered in the text input or the first of the month if no date has been entered.
• Enter/Space: Opens calendar when button is focused, selects date when calendar is open.
• Arrow keys: Navigate between dates within the calendar grid.
• Home/End: Navigate to beginning/end of week.
• Page Up/Down: Navigate between months.

Screen reader:

• The date format and any helper text is announced when the input receives focus.
• Calendar button is announced with its current state when focused ("Open calendar picker dialog" or "Close calendar picker dialog").
• Selected dates in the calendar are announced with full date information.
• Month/year navigation changes are announced to screen readers.
• Date restrictions (from/to dates) are communicated when users encounter disabled dates (i.e. noted as “dimmed” in MacOS Voiceover).

Code

React

The calendar picker is another name for the <SingleInputDateField> with a calendar picker button. To enable the date picker feature, you must pass both a from<TIME> property (i.e., fromDate, fromMonth, etc.) and a to<TIME> property (i.e., toDate, toMonth, etc.) to the date field component.

Review Storybook for React guidance of this component.

Style customization

The following CSS variables can be overridden to customize Input/Form components:

Related patterns

• Date field (multi-input)
• Date field (single-input)

Component maturity