DatePicker
Date Picker allows user to enter a date either through text input, or by choosing a date from the calendar. Please note that the date must be passed in ISO-8601 format: YYYY-MM-DD.
Properties
| Property | Attribute | Description | Type | Default |
|---|---|---|---|---|
value | value | Date value. Must be in IS0-8601 format: YYYY-MM-DD. | string | '' |
open | open | Controls whether date picker dialog is open or not. | boolean | false |
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 | undefined | — |
max | max | Maximum 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 | undefined | — |
today | today | The date that is considered today. Must be in IS0-8601 format: YYYY-MM-DD. If not set, the current local date of the user is used. | string | undefined | — |
firstDayOfWeek | first-day-of-week | Which day is considered first day of the week? `0` for Sunday, `1` for Monday, etc. Default is Monday. | DaysOfWeek | — |
expand | expand | Controls whether the date picker expands to fill the width of its container. | boolean | false |
size | size | The size of the component. | 's' | 'm' | 'l' | 'm' |
label | label | Label for the input. | string | '' |
hint | hint | Optional hint text to be displayed with the input. Alternatively use the hint slot. | string | undefined | — |
hideLabel | hide-label | Visually hide the label, but still show it to assistive technologies like screen readers. | boolean | false |
placeholder | placeholder | Placeholder text to display within the input. | string | undefined | — |
error | error | Optional error to be shown with the input. Alternatively use the error slot. | string | undefined | — |
required | required | Determines whether the input is required or not. An input marked as required will be announced as such to users of assistive technology. When using this property you need to also set “novalidate” attribute on a form element to prevent browser from displaying its own validation errors. | boolean | false |
hideRequired | hide-required | Visually hide the required indicator, but still show required attribute to assistive technologies like screen readers. | boolean | false |
readonly | readonly | Makes the component readonly, so that it is not editable. Readonly differs from disabled in that readonly fields are still focusable and will be submitted with a form. | boolean | false |
disabled | disabled | Makes the component disabled. This prevents users from being able to interact with the component, and conveys its inactive state to assistive technologies. | boolean | false |
name | name | The name of the form component. | string | undefined | — |
form | form | Gets the form, if any, associated with the form element. The setter accepts a string, which is the id of the form. | HTMLFormElement | null | — |
Methods
| Method name | Parameters | Description |
|---|---|---|
hide(moveFocusToButton?: boolean) => void | moveFocusToButton: A boolean option to move the focus to the original button that opens the popout. | Hide the date picker programmatically. |
show() => void | N/A | Show the date picker programmatically. |
focus(options?: FocusOptions) => void | options: An object which controls aspects of the focusing process. | Programmatically move focus to the component. |
blur() => void | N/A | Programmatically remove focus from the component. |
click() => void | N/A | Programmatically simulates a click on the component. |
| Event | Detail Type | Description |
|---|---|---|
change | NordEvent | Fired whenever the input's value is changed via user interaction. |
open | NordEvent | Dispatched when the popout is opened. |
close | NordEvent | Dispatched when the popout is closed. |
nord-focus-date | DateSelectEvent | Dispatched when the calendar's focused date changes. |
input | NordEvent | Fired as the user types into the input. |
CSS Properties
CSS Custom Properties provide more fine grain control over component presentation. We advise utilizing existing properties on the component before using these.
| Property | Description | Default |
|---|---|---|
--n-label-color | Controls the text color of the label, using our color tokens. | var(--n-color-text) |
Dependencies
This component is internally dependent on the following components:
- <nord-button>
Button
Buttons are used for interface actions. Primary style should be used only once per section for main call-to-action, while other styles can appear more frequently.
- <nord-calendar>
Calendar
Calendar allows user to pick a date. It comes with built-in functionality that allows you to set a minimum and a maximum allowed date. Please note that the date must be passed in ISO-8601 format.
- <nord-icon>
Icon
Icons are used to provide additional meaning or in places where text label doesn’t fit. Icon component allows you to display an icon from the Nordicons library.
- <nord-input>
Input
Inputs are used to allow users to provide text input when the expected input is short. As well as plain text, Input supports various types of text, including passwords and numbers.
- <nord-popout>
Popout
Popouts are small overlays that open on demand. They let users access additional content and actions without cluttering the page.
- <nord-stack>
Stack
Stack component manages layout of immediate children along the vertical or horizontal axis with optional spacing between each child.
- <nord-visually-hidden>
VisuallyHidden
Visually hidden is used when an element needs to be available to assistive technologies like screen readers, but be otherwise hidden.
Usage
This section includes guidelines for designers and developers about the usage of this component in different contexts.
Do
- Use when the user needs to choose a single date or a date range.
Don’t
- Don’t use for entering date of birth. Use input component instead.
- Don’t use to choose a date that is over 10 years in the future or the past.
Keyboard accessibility
Date picker 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 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. In right-to-left languages, moves focus to the previous day.Arrow left: Moves focus to the previous day. In right-to-left languages, moves focus to the next 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 guidelines, please see Web Components documentation .