Components

Date picker

Overview

Overview

TDS provides only the HTML and CSS for a date picker.

When to use

• Allow users to choose recent or near future dates.
• Limit date options to a specific range of dates.
• When it is important for the user to know the day of the week, or the relationship between days. For example: scheduling appointments.

When not to use

When a user needs to input a far distant (e.g. birth date) or a far future (e.g. expiry date of an id card etc), use the date input component instead.

Principles

Datepicker component combines a text field with a calendar dropdown.

The user can either type a date into the text field or choose a day from the calendar dropdown which will populate the text field with the chosen date.

Date input field

Default field example

This example uses the Vanilla JS Datepicker library and the JavaScript shown under Show Code → JavaScript to configure it. You may use any library, but will have to configure and style it yourself.

Help texts

The input field can use either a placeholder text or a hint text to inform a user about the required date format. We recommend to use hint text for public services and placeholder text for internal services.

Recommended date format for public services is DD.MM.YYYY. For internal services various formats can be used, if needed (for example, YYYY-MM-DD).

Required field indicator and error state

Calendar Dropdown

Anatomy

Default calendar example

Clicking on the calendar button inside the text field opens the calendar dropdown below the text field. When a user clicks on a date in the calendar, the dropdown disappears and selected date is displayed in the text field.

If the calendar dropdown is opened after selecting a date, the selected date is highlighted in the dropdown.

Disabled dates

Specific dates or date ranges can be disabled. For example, weekend days, all dates before or after certain days, etc.

Month and year selectors

Clicking on the month or year in the header of the dropdown opens a month or year selector respectively and currently selected month/year is highlighted. Navigation buttons can be configured to go through months/years or disabled.

When a user clicks on a month or a year, the dropdown returns to calendar view and the selected month/year is displayed.

Date ranges

Date range input can be accomplished with two datepickers.

Accessibility

Keyboard

The calendar is driven from the text input, which keeps focus the whole time.

• Arrow Down, Space or Enter in the input open the calendar.
• While it is open, the arrow keys move the focused day and Enter picks it and closes the calendar.
• Ctrl+Arrow Up switches to the month view, then the year view.
• Escape closes the calendar without reopening it.
• The calendar button opens or closes the calendar and moves focus into the input.

The month, year and previous/next buttons in the calendar header are mouse targets (tabindex="-1"). Keyboard users reach the same views with the shortcuts above.

Screen readers

The input is labelled by its visible label; hint and error are linked with aria-describedby, and the error state sets aria-invalid="true". The calendar button is named "Ava kalender" (buttonLabel) and has aria-haspopup="dialog", aria-expanded and aria-controls pointing at the calendar. The calendar is a role="dialog" named "Kalender" (calendarLabel). The month and year header buttons expose the active view through aria-pressed, and the previous/next arrows are named "Eelmine" and "Järgmine". All icons are aria-hidden="true".

Using the example

• Give the input an id that is unique on the page; the calendar id (<id>-calendar) is derived from it.
• Always render a visible label, and state the format ("PP.KK.AAAA") in the hint, not only in the placeholder.
• The required asterisk is visual only; add required or aria-required="true" to the input.

Known limits

The day grid is not announced as the arrow keys move through it. Screen reader users should be able to type the date directly in dd.mm.yyyy format, so keep the input editable and validate typed values.