# Date Picker
The Dia date picker component is an open source input element that allows users to enter a date into input fields or by selecting a date using a calendar interface.
# Usage
<dia-date-picker label="Default"></dia-date-picker>
The default date picker component will provide you with an input field and the calendar dialog. The dialog can be activated by clicking calendar icon on the right side of the input.
# Required
Beside setting the date range on the component, you can also indicate if it is required using the required attribute.
<dia-date-picker label="Required Date" required></dia-date-picker>
# Disabled
Adding the disabled attribute will prevent to control from being updated or focused on.
<dia-date-picker
label="Disabled Date"
value="2/22/2022"
disabled
></dia-date-picker>
# Readonly
Adding the readonly attribute will allow the input to be focused on, but the date cannot be modified and the calendar control cannot be expanded.
<dia-date-picker
label="Readonly Date"
value="2/22/2022"
readonly
></dia-date-picker>
# Focus Date
If you don't want to set the value, but you want the calendar to be focused on a specific date initially, you can use the focus-date attribute.
<dia-date-picker label="Focus Date" focus-date="2-22-2022"></dia-date-picker>
# Min/Max Dates
You can provide a range of available date using the min-date and max-date attributes.
<dia-date-picker
label="Date Range"
min-date="3/5/2022"
max-date="3/20/2022"
></dia-date-picker>
# Disabled Dates
In order to disabled multiple dates, you can pass a comma separated list of dates to the disabled-dates attribute.
<dia-date-picker
label="Disabled Dates"
disabled-dates="5/5/2022,5/8/2022, 5/19/2022, 5/25/2022"
></dia-date-picker>
# Week Numbers
When the show-week-numbers attribute is added to the component, week numbers will appear at the beginning of each week's row indicating the week number in the year.
<dia-date-picker label="Show Week Numbers" show-week-numbers></dia-date-picker>
# Disabled Days of the Week
There may be occasion where only weekends need to be available or specific days of the week may not be. This can be achieved by adding a comma separated list of week days (1-7) to the disabled-week-days attribute.
<dia-date-picker
label="Disabled Weekends"
disabled-week-days="1,7"
></dia-date-picker>
# First Day of the Week
Depending on your application or your location, you may want to start the day of the week with a day other than Sunday. You can pass the number of days to off-set the week by (0-6) to the first-day-of-week attribute to shift the week to your preference.
<dia-date-picker
label="Week Starts on Monday"
first-day-of-week="1"
></dia-date-picker>
# Translations
This component is almost entirely translated by the native browser API. The component will automatically detect the current language, but you can also manually specify a language using the lang attribute.
Not only will the months and days be translated, but the format of the input will be updated to match the date format of that locale.
In the demo below, select a locale below and see how it is translated.
Translatable Fields
As you can see not everything gets translated. You will need to provide translations for the labels for day, month, and year inputs, button labels and error messages.
# Accessibility
These components have been built form the ground up with accessibility in mind. A lot fo effort has gone into ensuring that this component works well with keyboards and assistive technologies like screen readers.
# Keyboard Navigation
# Date Picker Input
When focused on the main input, users can use LEFT and RIGHT arrow keys to move between day, month, and year input fields. Basic TAB functionality will also enable users to switch back and forth.
When entering values in the input fields, users will automatically be moved to the next input field once appropriate values have been added to it to not additional tabbing or arrow key presses are necessary.
When focused on the main input, users can press the SPACE key to trigger the calendar dialog. This is similar to existing behavior for the date input type.
# Date Picker Dialog
Once the calendar dialog is open you can navigate the days in the calendar using the ARROW keys and the rest of the controls in the dialog using the TAB key.
If the value or focus date has been set and the user has focused on another date, pressing the ESC key will reset the date back to the originally focused date. Pressing the ESC key again will close the dialog. Otherwise, pressing the ESC key will close the dialog and set the focus back on the main input.
# Screen Readers
This component has been decorated with the appropriate roles, aria attributes, and labels to ensure users utilizing screen readers can accurately input or select an appropriate date.
# Attributes / Properties
| Attribute | Property | Description | Type | Default Value |
|---|---|---|---|---|
| value | value | selected value in input | string | undefined | |
| label | label | label for main date input | string | undefined | |
| help-text | helpText | content to provide additional context to the input | string | undefined | |
| name | name | name used to identify the input | string | undefined | |
| invalid | invalid | adds required validation to the input | boolean | false |
| required | required | adds required validation to the input | boolean | false |
| disabled | disabled | disables input and calendar drop-down | boolean | false |
| readonly | readonly | makes input readonly and disables drop-down | boolean | false |
| min-date | minDate | the minimum selectable date | string | undefined | |
| max-date | maxDate | the maximum selectable date | string | undefined | |
| focus-date | focusDate | the initial focus date if no value is set | string | undefined | |
| disabled-dates | disabledDates | comma separated list of disabled dates | string | undefined | |
| show-week-numbers | showWeekNumbers | show week numbers at the beginning of each week | boolean | undefined | |
| disabled-week-days | disabledWeekDays | comma separated list of week days to be disabled (1-7) | string | undefined | |
| first-day-of-week | firstDayOfWeek | the day of the week the calendar will start with (0-6) | 0 | 1 | 2 | 3 | 4 | 5 | 6 | undefined | |
| day-label | dayLabel | label used for day input | string | 'Day' |
| month-label | monthLabel | label used for month input | string | 'Month' |
| year-label | yearLabel | label used for year input | string | 'Year' |
| clear-label | clearLabel | text for "Clear" button | string | 'Clear' |
| today-label | todayLabel | text for "Today" button | string | 'Today' |
| required-error-message | requiredErrorMessage | message displayed when required validation fails | string | 'This field is required' |
| range-error-message | rangeErrorMessage | message displayed when selected date is out of range | string | 'The date you have selected is not within the date range' |
| unavailable-error-message | unavailableErrorMessage | message displayed when disabled date is selected | string | 'The date you have selected is unavailable' |
| custom-error-message | customErrorMessage | custom error message when the `invalid` attribute is set to "true" | string | undefined | |
| show-error-below | showErrorBelow | displays error message below input | boolean | undefined | |
| show-help-text-below | showHelpTextBelow | shows help text below input | boolean | undefined | |
| hide-required-indicator | hideRequiredIndicator | hide asterisk (*) as a required input indicator | boolean | undefined |
# CSS Properties
| Name | Description | Default Value |
|---|---|---|
| --border-color | Default border color | #c5d1da |
| --border-radius | Default border radius | 0.25rem |
| --disabled-color | Color of disabled days | #acbdca |
| --error-color | Color used to communicate error in the component | #b32e2e |
| --outline | Default focus outline style | solid 0.0625rem #37444F |
| --outline-offset | Outline offset | 0.125rem |
| --primary-color | Primary color used in the component | #004884 |
# CSS Parts
| Name | Description |
|---|---|
| label | controls styles for the main input label |
| help-text | controls styles for the help text |
| error-message | controls styles for the error message |
| dropdown | controls styles for the dropdown panel that contains the calendar |
| main-input | controls styles for the main input for day, month, and year |
| calendar-toggle | controls styles for the toggle button to show and hide the calendar |
| input | Controls styles of calendar inputs (month and year) |
| button | Controls styles of buttons |
| prev-month | Controls styles of previous month button |
| next-month | Controls styles of next month button |
| week-number | Controls styles of week numbers |
| day | Controls styles of day controls in the calendar |
| alt-month | Controls styles of days of previous and next month |
| day-today | Controls styles of current day |
| selected | Controls styles of selected day |
| day-label | Controls styles of day number label |
| clear | Controls style of "Clear" button |
| today | Controls style of "Today" button |
| delimiter | Controls style of delimiters between the day, month, and year inputs |
# Events
| Name | Description | Type |
|---|---|---|
| dia-input | emits the date as short ISO string when calendar date is manually entered or focused on in the calendar | CustomEvent |
| dia-change | emits the date as short ISO string when calendar date is selected | CustomEvent |
Calendar →