Skip to main content

Datepicker

The datepicker is a composite component that combines a text input field with a calendar widget. It allows users to either type a date directly or select one from a visual calendar. This provides flexibility for users who know the exact date and for those who need the context of a calendar to choose a date.

The primary method for date entry should always be the text input. The calendar is an enhancement that provides a helpful alternative. Use this component for collecting dates like a date of birth or an application date.

Below is the standard presentation of the datepicker component on InsureKidsNow.gov. It includes a label, a clearly formatted text input field and a calendar icon that toggles the interactive calendar widget.

IKN Datepicker


Filter by Start of State Rating Period (mm/dd/yyyy)

Anatomy and Visual Specifications

The datepicker is composed of two main parts: the date input and the calendar widget.

  • Label: Text that clearly describes the required date.
  • Date Input Field: A standard text input where users can type a date.
  • Format Hint Text: Required text below the label that specifies the expected date format (MM/DD/YYYY).
  • Calendar Icon Button: An icon-only button to the right of the input field. Clicking this button shows or hides the calendar widget.
  • Calendar Widget: The interactive calendar that appears when the user clicks the calendar icon. It includes:
    • Navigation Controls: Buttons for moving to the previous and next month.
    • Month and Year Display: The currently displayed month and year.
    • Day of the Week Headers: Single-letter abbreviations for the days of the week (S, M, T, W, T, F, S).
    • Date Grid: The interactive grid of days for the current month. Today’s date and the selected date are visually distinct.

There are various states for the datepicker component.

  • Default State: The date input has a 1px solid gray border and white background. The calendar icon is a dark gray.
  • Hover State: When a user hovers over the date input its border darkens. The calendar icon button gets a light gray background on hover to indicate it is clickable.
  • Focus State: A 2px solid blue outline (#0D76AD) must appear around the component to provide a highly visible focus indicator. This outline applies to the input field when it is in focus. When the calendar widget is open focus is managed within the calendar and the currently focused date or control has a visible outline.
  • Disabled State: The input field and calendar icon are grayed out with reduced opacity to indicate they are not interactive.
  • Error State: When an invalid or incomplete date is entered the input field’s border becomes a 2px solid red. A descriptive error message must appear below the input.

Accessibility and Implementation Guidance

A datepicker presents significant accessibility challenges. The following implementation details are mandatory to ensure the component is usable for everyone.

  • Prioritize the Text Input. The component must function as a standard text input field even if JavaScript fails to load. Always include hint text that explicitly states the required MM/DD/YYYY format.
  • Use Proper Labels. Every datepicker must have a corresponding < label > element. The for attribute of the label must match the id of the < input > field. This programmatic association is essential for screen reader users.
  • Support Full Keyboard Navigation. Users must be able to complete the task of selecting a date using only a keyboard.
  • Date Input Field: Standard keyboard interactions for a text input apply.
  • Calendar Icon Button: The button must be focusable via the Tab key. Enter or Spacebar opens and closes the calendar widget.
  • Calendar Widget Navigation:
    • Escape: Closes the calendar. Focus returns to the calendar icon button.
    • Arrow Keys: Navigate day by day within the calendar grid.
    • Enter or Spacebar: Selects the focused date, updates the input field and closes the calendar. Focus returns to the input field.
    • Page Up / Page Down: Moves to the previous or next month.
    • Shift + Page Up / Page Down: >Moves to the previous or next year.
    • Home / End: Moves focus to the first or last day of the current week.
  • Implement ARIA Attributes Correctly.Use ARIA (Accessible Rich Internet Applications) attributes to communicate the component’s state and behavior to assistive technologies.
    • The calendar widget should have role="dialog" and an aria-label to describe its purpose (e.g., "Calendar").
    • Use aria-hidden="true" to hide the calendar widget from screen readers when it is not visible.
    • The calendar icon button should have an aria-label like "Open calendar" to announce its function.
  • Provide Clear and Accessible Error Messages. Validation errors (e.g., incorrect format, invalid date) must be communicated clearly. The error message text should be programmatically linked to the input field using the aria-describedby attribute. Do not rely on color alone to convey an error.

Additional Specifications

For any additional information about specifications, guidelines, accessibility and usage, please refer to the Datepicker component on the USWDS website:

USWDS - Datepicker