Date Picker New
Date Picker component lets user pick a single date or a date range using a special calendar like date picker interface. There’s also open source version of this component available.
Date Picker allows you to set a minimum and a maximum allowed date. These settings can be combined or used alone, depending on the need. Please note that the date values must be passed in IS0-8601 format: YYYY-MM-DD
.
Examples
<duet-date-picker name="date" label="Valitse päivämäärä" placeholder="pp.kk.vvvv"></duet-date-picker>
<script>
// Select the above date picker component
var picker = document.querySelector("duet-date-picker")
// Listen for when date is selected
picker.addEventListener("duetChange", function(e) {
console.log("selected date", e.detail.valueAsDate)
})
</script>
<duet-date-picker
label="Valitse päivämäärä"
min="2020-06-10"
max="2020-07-18"
value="2020-06-16"
placeholder="pp.kk.vvvv">
</duet-date-picker>
<script>
// Select the above date picker component
var picker = document.querySelector("duet-date-picker")
// Listen for when date is selected
picker.addEventListener("duetChange", function(e) {
console.log("selected date", e.detail.valueAsDate)
})
</script>
<duet-label>Valitse aikaväli</duet-label>
<duet-grid alignment="center" style="max-width:420px;">
<duet-date-picker name="startdate" class="start" expand margin="none" label="Valitse aloituspäivä" label-hidden value="2020-06-01"></duet-date-picker>
<duet-spacer direction="horizontal" size="x-small"></duet-spacer>
<duet-icon name="navigation-arrow-right" margin="none" color="currentColor" size="x-small"></duet-icon>
<duet-spacer direction="horizontal" size="x-small"></duet-spacer>
<duet-date-picker name="enddate" class="end" expand margin="none" label="Valitse lopetuspäivä" label-hidden direction="left" value="2020-06-10"></duet-date-picker>
</duet-grid>
<script>
// Select the above date picker components
var startPicker = document.querySelector(".start")
var endPicker = document.querySelector(".end")
var startDate, endDate
// Handle date selection
function handleDateSelect() {
if (startDate && endDate) {
console.log("date range selected", startDate, endDate)
}
}
// When the start date picker is changed…
startPicker.addEventListener("duetChange", function(e) {
startDate = e.detail.valueAsDate
endPicker.min = e.detail.value
if (!endDate) {
endPicker.show()
}
handleDateSelect()
})
// When the end date date picker is changed…
endPicker.addEventListener("duetChange", function(e) {
endDate = e.detail.valueAsDate
startPicker.max = e.detail.value
handleDateSelect()
})
</script>
<duet-date-picker name="date" disabled label="Valitse päivämäärä" value="2020-05-16"></duet-date-picker>
<script>
// Select the above date picker component
var picker = document.querySelector("duet-date-picker")
// Listen for when date is selected
picker.addEventListener("duetChange", function(e) {
console.log("selected date", e.detail.valueAsDate)
})
</script>
<duet-date-picker name="date" error="There is an error!" label="Choose a date" value="2020-05-16"></duet-date-picker>
<script>
// Select the above date picker component
var picker = document.querySelector("duet-date-picker")
// Listen for when date is selected
picker.addEventListener("duetChange", function(e) {
console.log("selected date", e.detail.valueAsDate)
})
</script>
<duet-date-picker
tooltip="Hello, I’m a tooltip! To close me you can hit ESC key,
click the close button, or click outside of the tooltip."
label="Choose a date (with tooltip)"
value="2020-05-16">
</duet-date-picker>
<script>
// Select the above date picker component
var picker = document.querySelector("duet-date-picker")
// Listen for when date is selected
picker.addEventListener("duetChange", function(e) {
console.log("selected date", e.detail.valueAsDate)
})
</script>
<duet-date-picker name="date" language="en" label="Choose a date" placeholder="dd.mm.yyyy"></duet-date-picker>
<script>
// Select the above date picker component
var picker = document.querySelector("duet-date-picker")
// Listen for when date is selected
picker.addEventListener("duetChange", function(e) {
console.log("selected date", e.detail.valueAsDate)
})
</script>
<duet-date-picker name="date" language="sv" label="Välj datum" placeholder="dd.mm.åååå"></duet-date-picker>
<script>
// Select the above date picker component
var picker = document.querySelector("duet-date-picker")
// Listen for when date is selected
picker.addEventListener("duetChange", function(e) {
console.log("selected date", e.detail.valueAsDate)
})
</script>
<duet-date-picker name="date" language="en" label="Choose a date" placeholder="dd.mm.yyyy"></duet-date-picker>
<script>
// Select the above date picker component
var picker = document.querySelector("duet-date-picker")
// Call show method
setTimeout(function() {
picker.show()
}, 100)
</script>
Properties #
Property | Attribute | Description | Type | Default |
---|---|---|---|---|
direction | direction | Forces the opening direction of the calendar modal to be always left or right. This setting can be useful when the input is smaller than the opening date picker would be as by default the picker always opens towards right. | "left" | "right" | "right" |
disabled | disabled | Makes the date picker input component disabled. This prevents users from being able to interact with the input, and conveys its inactive state to assistive technologies. | boolean | false |
error | error | Display the date picker input in error state along with an error message. | string | "" |
expand | expand | Expands the date picker input to fill 100% of the container width. | boolean | false |
identifier | identifier | Adds a unique identifier for the date picker input. | string | "" |
label | label | Label for the date picker input. | string | "" |
labelHidden | label-hidden | Visually hide the label, but still show it to screen readers. | boolean | false |
language | language | The currently active language. This setting changes the month/year/day names and button labels as well as all screen reader labels. | "en" | "fi" | "sv" | "fi" |
margin | margin | Controls the margin of the component. | "auto" | "none" | "auto" |
max | max | Minimum date allowed to be picked. Must be in IS0-8601 format: YYYY-MM-DD This setting can be used alone or together with the min property. | string | "" |
min | min | Minimum date allowed to be picked. Must be in IS0-8601 format: YYYY-MM-DD. This setting can be used alone or together with the max property. | string | "" |
name | name | Name of the date picker input. | string | "" |
placeholder | placeholder | Hint text to display before the user types into the date picker input. | string | "pp.kk.vvvv" |
required | required | Set whether the input is required or not. Please note that this is necessary for accessible inputs when the user is required to fill them. When using this property you need to also set “novalidate” attribute to your form element to prevent browser from displaying its own validation errors. | boolean | false |
role | role | Defines a specific role attribute for the date picker input. | string | undefined |
theme | theme | Theme of the component. | "" | "default" | "turva" | "" |
tooltip | tooltip | Tooltip to display next to the label of the date picker input. | string | "" |
tooltipDirection | tooltip-direction | With direction setting you can force the tooltip to always open towards left or right instead of automatically determining the direction. | "auto" | "left" | "right" | "auto" |
value | value | Date value. Must be in IS0-8601 format: YYYY-MM-DD | string | "" |
Events #
Event | Description | Type |
---|---|---|
duetBlur | Event emitted the date picker input is blurred. | CustomEvent<{ component: "duet-date-picker"; }> |
duetChange | Event emitted when a date is selected. | CustomEvent<{ component: "duet-date-picker"; valueAsDate: Date; value: string; }> |
duetFocus | Event emitted the date picker input is focused. | CustomEvent<{ component: "duet-date-picker"; }> |
Methods #
hide(moveFocusToButton?: boolean) => Promise<void>
#
Hide the calendar modal. Set moveFocusToButton
to false to prevent focus
returning to the date picker's button. Default is true.
Returns #
Type: Promise<void>
setFocus() => Promise<void>
#
Sets focus on the date picker's input. Use this method instead of the global focus()
.
Returns #
Type: Promise<void>
show() => Promise<void>
#
Show the calendar modal, moving focus to the calendar inside.
Returns #
Type: Promise<void>
Usage #
This section includes guidelines for designers and developers about the usage of this component in different contexts.
When to use #
- When the user needs to choose a single date or a date range.
When not to use #
- For entering date of birth. Use input components instead.
- To choose a date that is over 10 years in the future or the past.
Accessibility #
This component has been validated to meet the WCAG 2.1 AA accessibility guidelines. You can find additional information regarding accessibility of this component below.
- Date picker includes a date input and a toggle button that opens a calendar picker that is built using the dialog design pattern. This opening dialog contains a calendar that uses the grid pattern which presents buttons that allow the user to choose a specific date.
- When a date is chosen from this calendar, the accessible name of the calendar picker toggle button is updated to include the selected date.
- The calendar grid provides hotkeys for changing the year and month as well as support for normal grid navigation keys.
label
property is always required for an accessible date picker control.labelHidden
property hides the above label visually, but still keeps it accessible for assistive technologies.- Use
role
property to define a specific role attribute for the date picker input. - Calendar grid uses
aria-disabled
(instead ofdisabled
attribute) in disabled date buttons to convey their disabled state to assistive technologies. The reason we switched away fromdisabled
attribute is that we wanted to make it possible for mouse users to be able to select a date from a previous month. - Because of the above reason, the contrast ratios for the disabled buttons don’t pass WCAG 2.1 requirements. Instead, Duet offers alternative ways to access these same functionalities through the next/previous month menus.
Keyboard support #
Duet Date Picker’s keyboard support is built to closely follow W3C Date Picker Dialog example with some small exceptions to e.g. better support iOS VoiceOver and Android TalkBack.
Choose date button #
Space, Enter
: Opens the date picker dialog and moves focus to the first select menu in the dialog.
Date picker dialog #
Esc
: Closes the date picker dialog and moves focus back to the “choose date” button.Tab
: Moves focus to the next element in the dialog. Please note since the calendar usesrole="grid"
, only one button in the calendar grid is in the tab sequence. Additionally, if focus is on the last focusable element, focus is next moved back to the first focusable element inside the date picker dialog.Shift + Tab
: Same as above, but in reverse order.
Date picker dialog: Month/year buttons #
Space, Enter
: Changes the month and/or year displayed.
Date picker dialog: Date grid #
Space, Enter
: Selects a date, closes the dialog, and moves focus back to the “Choose Date” button. Additionally updates the value of the Duet Date Picker input with the selected date, and adds selected date to “Choose Date” button label.Arrow up
: Moves focus to the same day of the previous week.Arrow down
: Moves focus to the same day of the next week.Arrow right
: Moves focus to the next day.Arrow left
: Moves focus to the previous day.Home
: Moves focus to the first day (e.g Monday) of the current week.End
: Moves focus to the last day (e.g. Sunday) of the current week.Page Up
: Changes the grid of dates to the previous month and sets focus on the same day of the same week.Shift + Page Up
: Changes the grid of dates to the previous year and sets focus on the same day of the same week.Page Down
: Changes the grid of dates to the next month and sets focus on the same day of the same week.Shift + Page Down
: Changes the grid of dates to the next year and sets focus on the same day of the same week.
Date picker dialog: Close button #
Space, Enter
: Closes the dialog, moves focus to “choose date” button, but does not update the date in input.
Integration
For integration, event and theming guidelines, please see Using Components. This documentation explains how to implement and use Duet’s components across different technologies like Angular, React or Vanilla JavaScript.
Tutorials
Follow these practical tutorials to learn how to build simple page layouts using Duet’s CSS Framework, Web Components and other features:
Abstract
TutorialsBuilding Layouts
TutorialsUsing CLI Tools
TutorialsCreating Custom Patterns
TutorialsServer Side Rendering
TutorialsSharing Prototypes
TutorialsUsage With Markdown
TutorialsVS Code
TutorialsZeplin
Troubleshooting
If you experience any issues while using a component, please head over to the Support page for more guidelines and help.