Date Picker

Allows users to select a single date or a range of dates depending on the use case.

General

Examples

Default date picker

HTML React 
<head>
    <script type="module" src="https://cdn.jsdelivr.net/npm/@govtechsg/sgds-web-component@2.1.2/components/Datepicker/index.umd.js">
    </script>
</head>
<body>
<sgds-datepicker></sgds-datepicker>
</body>
 [**DEV**]View on React storybook

Anatomy

Date Picker Anatomy
  1. Month: Allows the user to select the month.
  2. Year: Allows the user to select the year.
  3. Forward/backward chevrons: Allows the user to move forward or backwards by month within the selected year.

Spacing

Date Picker Spacing

Within the calendar
Ensure that there is a minimum of 24px vertical and horizontal spacing.

Usage guidelines

Date picker should be used when:

  1. You want users need to select a range of dates (e.g., start and end dates), a date picker can facilitate this with clear visual representation.

Date picker should not be used when:

  1. Users only need to input dates in a simple text format without complex selections, a text input field may be more appropriate.

Usability guidelines

Be relevant and clear
Date pickers can display past, present or future dates, display as relevant to the task as possible. Clearly indicate important dates as well; current and selected dates.

Target touch size
Ensure that the target touch size is big enough, this will reduce the chance of users hitting the wrong target that potentially cause them to complete the action wrongly without realising.

Behaviour
Selecting the relevant dates should close the date picker and populate the input field with the chosen dates. Clicking or tapping outside the date picker should close it.

Accessibility guidelines

Aria attributes

Date input field:
  1. The date input field has a visible label referenced by aria-labelledby, or has a label specified with aria-label or has a label specified with for attribute which points to the date input field's id attribute.
  2. The aria-invalid attribute should be used to reflect the current validity state of the date input, allowing users to know whether the entered value is valid or invalid.
  3. The aria-describedby attribute can link the date input field to explanatory, instructional or feedback text, improving comprehension for all users.
Choose date button:
  1. The button that opens the date picker should have an aria-label to convey its function, making it clear that it triggers a calendar or date selection interface.
  2. The aria-expanded attribute on the choose date button should indicate whether the date selection panel is currently visible or hidden, helping users understand the state of the component.
  3. The aria-haspopup attribute is useful for indicating that the choose date button opens a popup or dropdown, such as a calendar, which can aid users in navigating the interface.
  4. The aria-controls attribute on the choose date button should reference the id of the date picker dropdown, establishing a clear relationship between the control and the date picker.
Clear date button:
  1. The button to reset the date picker should have an aria-label that explains its function, to ensure users are aware of its purpose.
Date picker dialog:
  1. The date picker dialog should have a role of dialog to inform assistive technologies that it is a standalone, interactive element requiring user attention.
  2. The aria-modal attribute should be set to true on the dialog to indicate that the background content is inactive and to keep the focus within the dialog until it is closed.
  3. A descriptive aria-label, should be assigned to the dialog to provide a meaningful name that describes its purpose and function.
Date picker dialog: Calendar navigation buttons:
  1. Navigation buttons for changing months and years within the date picker should have aria-label, to specify their actions clearly.
  2. The currently displayed month and year should have aria-live="polite" to notify users of the updated month, year or year range without interrupting their workflow.
  3. The attribute aria-disabled="false" is used on buttons to indicate they are clickable, whereas aria-disabled="true" signifies that the buttons are not interactive and are disabled.
Date picker dialog: Date grid:
  1. The date picker table should have role="grid" to define its structure and enhance accessibility for screen readers.
  2. The date buttons within the calendar should be marked with role="button" to indicate their interactive nature and have aria-label that describe each date fully, such as "Monday, January 1, 2024".
  3. The current date should have aria-current="date" to identify it as the selected or today's date, enhancing orientation for users.
Date picker dialog: Month grid
  1. The month buttons within the calendar should have aria-label that describe each month, such as "January 2024".
  2. For the current month, the aria-label includes the phrase "Current month," followed by the month and year, to highlight its importance and provide additional context, helping users easily identify the current month.
  3. The aria-selected attribute is used to denote the selection state of each month button. For example, aria-selected="true" signifies that the month is currently selected, while aria-selected="false" means it is not selected.
Date picker dialog: Year grid
  1. For the current year, the aria-label includes the phrase "Current year," followed by the year, to highlight its importance and provide additional context, helping users easily identify the current month.
  2. The aria-selected attribute is used to denote the selection state of each month button. For example, aria-selected="true" signifies that the month is currently selected, while aria-selected="false" means it is not selected.

Keyboard accessibility

Before the date picker is opened:
  1. Enter or Space to open date picker on focus.
When date picker is opened:
  1. Tab or Shift-Tab to navigate between date input field, choose date button and clear date button.
Choose date button:
  1. Enter or Space to open the date picker dialog, if there is selected date, move focus to the selected date or the end date of the date range, i.e., the date displayed in the date input text field. If no date has been selected, place focus on the current date.
  2. Esc to close the date picker dialog and return focus to the date input field.
Clear date button:
  1. Enter or Space to clear the selected date.
Date picker dialog:
  1. Tab or Shift-Tab to move focus between the elements in the date picker dialog.
  2. Enter or Space to trigger the focused element.
Date picker dialog: Date grid:
  1. ↑ to move focus to the same day of week of the past week.
  2. ↓ to move focus to the same day of week of the next week.
  3. ← to move focus to the previous day.
  4. → to move focus to the next day.
Date picker dialog: Month grid:
  1. ↑ to move focus to the past 3 months.
  2. ↓ to move focus to the next 3 months.
  3. ← to move focus to the previous month.
  4. → to move focus to the next month.
Date picker dialog: Year grid:
  1. ↑ to move focus to the past 3 years.
  2. ↓ to move focus to the next 3 years.
  3. ← to move focus to the previous year.
  4. → to move focus to the next year.

Focus indicator

  1. Ensure that there are visual differences between the different states such as hover, on focus, disabled, selected.
  2. The focus indicator should move smoothly and visibly as the user navigates through the date picker.
  3. Mouse interactions should also provide a visual focus indicator, so users can see which date or control is currently focused.
Last updated 02 October 2024
Home
Latest version 2.3.5