Use date and time inputs to set dates and times in forms. They are available as separate inputs (date or time) or as a combined date & time input, and each of them is also available as a range.
<script type="module">
import '@brightspace-ui/core/components/inputs/input-date.js';
import '@brightspace-ui/core/components/inputs/input-time.js';
</script>
<d2l-input-date label="Date Input"></d2l-input-date>
<d2l-input-time label="Time Input"></d2l-input-time>- Use short but descriptive labels like "Start Date" or "Due Date"
- Offer reasonable defaults whenever possible
- Use date and time values relative to the user's timezone
- Don't combine inputs to form a range, use an actual range input instead; this will handle layout and validation automatically
Use the <d2l-input-date> component when users need to choose a single date. It consists of a text input field for typing a date and an attached calendar (<d2l-calendar>) dropdown. The dropdown opens on click of the text input, or on enter or down arrow press if the text input is focused. It displays the value if one is specified, or a placeholder if not, and reflects the selected value when one is selected in the d2l-calendar or entered in the text input.
Note: All *value properties should be in ISO 8601 calendar date format (YYYY-MM-DD) and should be localized to the user's timezone (if applicable).
<script type="module">
import '@brightspace-ui/core/components/inputs/input-date.js';
</script>
<d2l-input-date label="Birthdate">
</d2l-input-date>| Property | Type | Description |
|---|---|---|
label |
String, required | Accessible label for the input |
disabled |
Boolean | Disables the input |
label-hidden |
Boolean | Hides the label visually (moves it to the input's aria-label attribute) |
labelled-by |
String | HTML id of an element in the same shadow root which acts as the input's label |
max-value |
String | Maximum valid date that could be selected by a user. |
min-value |
String | Minimum valid date that could be selected by a user. |
opened |
Boolean | Indicates if the calendar dropdown is open |
required |
Boolean | Indicates that a value is required |
value |
String, default '' |
Value of the input. |
change: dispatched when a date is selected or typed.valuereflects the selected value and is in ISO 8601 calendar date format (YYYY-MM-DD).
inline-help: Help text that will appear below the input. Use this only when other helpful cues are not sufficient, such as a carefully-worded label.
Use the <d2l-input-date-range> component when users need to enter two dates in a range, like a course start and end date. The component consists of two input-date components - one for the start of a range and one for the end of a range. Values specified for these components (through the start-value and/or end-value attributes) are displayed if specified, and selected values are reflected.
Note: All *value properties should be in ISO 8601 calendar date format (YYYY-MM-DD) and should be localized to the user's timezone (if applicable).
<script type="module">
import '@brightspace-ui/core/components/inputs/input-date-range.js';
</script>
<d2l-input-date-range label="Availability Range">
</d2l-input-date-range>| Property | Type | Description |
|---|---|---|
label |
String, required | Accessible label for the input fieldset that wraps the date inputs |
auto-shift-dates |
Boolean | Automatically shifts end date when start date changes to keep the same range |
child-labels-hidden |
Boolean | Visually hides the labels for start and end date inputs |
disabled |
Boolean | Disables the inputs |
end-label |
String, default 'End Date' |
Accessible label for the second date input |
end-opened |
Boolean | Indicates if the end calendar dropdown is open |
end-value |
String, default '' |
Value of the second date input |
inclusive-date-range |
Boolean | Validate on inclusive range (i.e., it is valid for start and end dates to be equal) |
label-hidden |
Boolean | Hides the fieldset label visually |
max-value |
String | Maximum valid date that could be selected by a user |
min-value |
String | Minimum valid date that could be selected by a user |
required |
Boolean | Indicates that values are required |
start-label |
String, default 'Start Date' |
Accessible label for the first date input |
start-opened |
Boolean | Indicates if the start calendar dropdown is open |
start-value |
String, default '' |
Value of the first date input |
change: dispatched when a start or end date is selected or typed.start-valuereflects the value of the first input,end-valuereflects the value of the second input, and both are in ISO 8601 calendar date format (YYYY-MM-DD).
inline-help: Help text that will appear below the input. Use this only when other helpful cues are not sufficient, such as a carefully-worded label.
Use the <d2l-input-time> component when users need to enter a time, without a date. The component consists of a text input field for typing a time and an attached dropdown for time selection. The dropdown opens on click of the text input, or on enter or down arrow press if the text input is focused. It displays the value if one is specified, or a fallback time if not, and reflects the selected value when one is selected in the dropdown or entered in the text input.
Note: All *value properties should be in ISO 8601 time format (hh:mm:ss) and should be localized to the user's timezone (if applicable).
<script type="module">
import '@brightspace-ui/core/components/inputs/input-time.js';
</script>
<d2l-input-time label="Time">
</d2l-input-time>| Property | Type | Description |
|---|---|---|
label |
String, required | Accessible label for the input |
default-value |
String, default:'00:00:00' |
Set default value of input. Accepts ISO 8601 time format (hh:mm:ss) and the following keywords: startOfDay,endOfDay. |
disabled |
Boolean | Disables the input |
enforce-time-intervals |
Boolean | Rounds up to nearest valid interval time (specified with time-interval) when user types a time |
label-hidden |
Boolean | Hides the label visually (moves it to the input's aria-label attribute) |
labelled-by |
String | HTML id of an element in the same shadow root which acts as the input's label |
opened |
Boolean | Indicates if the dropdown is open |
required |
Boolean | Indicates that a value is required |
time-interval |
String, default: thirty |
Number of minutes between times shown in dropdown. Valid values include five, ten, fifteen, twenty, thirty, and sixty. |
value |
String, default '' |
Value of the input. This should be in ISO 8601 time format (hh:mm:ss) and should be localized to the user's timezone (if applicable). |
change: dispatched when a time is selected or typed.valuereflects the selected value and is in ISO 8601 time format (hh:mm:ss).
inline-help: Help text that will appear below the input. Use this only when other helpful cues are not sufficient, such as a carefully-worded label.
Use the <d2l-input-time-range> component when users need to enter two times in a range, and the date is already known. The component consists of two input-time components - one for the start of a range and one for the end of a range. Values specified for these components (through the start-value and/or end-value attributes) are displayed if specified, and selected values are reflected.
Note: All *value properties should be in ISO 8601 time format (hh:mm:ss) and should be localized to the user's timezone (if applicable).
<script type="module">
import '@brightspace-ui/core/components/inputs/input-time-range.js';
</script>
<d2l-input-time-range label="Availability Range">
</d2l-input-time-range>| Property | Type | Description |
|---|---|---|
label |
String, required | Accessible label for the input fieldset that wraps the time inputs |
auto-shift-times |
Boolean | Automatically shifts end time when start time changes to keep the same range |
child-labels-hidden |
Boolean | Visually hides the labels for start and end time inputs |
disabled |
Boolean | Disables the inputs |
end-label |
String, default 'End Time' |
Accessible label for the second time input |
end-opened |
Boolean | Indicates if the end dropdown is open |
end-value |
String, default '' |
Value of the second time input |
enforce-time-intervals |
Boolean | Rounds up to nearest valid interval time (specified with time-interval) when user types a time |
inclusive-time-range |
Boolean | Validate on inclusive range (i.e., it is valid for start and end times to be equal) |
label-hidden |
Boolean | Hides the fieldset label visually |
required |
Boolean | Indicates that values are required |
start-label |
String, default 'Start Time' |
Accessible label for the first time input |
start-opened |
Boolean | Indicates if the start dropdown is open |
start-value |
String, default '' |
Value of the first time input |
time-interval |
String, default: thirty |
Number of minutes between times shown in dropdown. Valid values include five, ten, fifteen, twenty, thirty, and sixty. |
inline-help: Help text that will appear below the input. Use this only when other helpful cues are not sufficient, such as a carefully-worded label.
Use the <d2l-input-date-time> component when users need to enter a single date and time, like a due date. The component consists of a <d2l-input-date> and a <d2l-input-time> component. The time input only appears once a date is selected. This component displays the value if one is specified, and reflects the selected value when one is selected or entered.
Note: All *value properties should be in ISO 8601 combined date and time format (YYYY-MM-DDTHH:mm:ss.sssZ) and in UTC time (i.e., do NOT localize to the user's timezone).
<script type="module">
import '@brightspace-ui/core/components/inputs/input-date-time.js';
</script>
<d2l-input-date-time label="Due Date">
</d2l-input-date-time>| Property | Type | Description |
|---|---|---|
label |
String, required | Accessible label for the input |
disabled |
Boolean | Disables the input |
label-hidden |
Boolean | Hides the fieldset label visually |
labelled-by |
String | HTML id of an element in the same shadow root which acts as the input's label |
localized |
Boolean | Indicates that any timezone localization will be handeld by the consumer and so any values will not be converted from/to UTC |
max-value |
String | Maximum valid date/time that could be selected by a user |
min-value |
String | Minimum valid date/time that could be selected by a user |
opened |
Boolean | Indicates if the date or time dropdown is open |
required |
Boolean | Indicates that a value is required |
time-default-value |
String, default:'00:00:00' |
Set default value of time input. Accepts ISO 8601 time format (hh:mm:ss) and the following keywords: startOfDay,endOfDay. |
value |
String, default '' |
Value of the input. |
change: dispatched when there is a change in selected date or selected time (when date is already selected).valuereflects the selected value and is in ISO 8601 combined date and time format (YYYY-MM-DDTHH:mm:ss.sssZ).
inline-help: Help text that will appear below the input. Use this only when other helpful cues are not sufficient, such as a carefully-worded label.
Use the <d2l-input-date-time-range> component when users need to enter two dates and times in a range, like an assignment start and end date/time. The component consists of two input-date-time components - one for the start of a range and one for the end of a range. Values specified for these components (through the start-value and/or end-value attributes) are displayed if specified, and selected values are reflected.
Note: All *value properties should be in ISO 8601 combined date and time format (YYYY-MM-DDTHH:mm:ss.sssZ) and in UTC time (i.e., do NOT localize to the user's timezone).
<script type="module">
import '@brightspace-ui/core/components/inputs/input-date-time-range.js';
</script>
<d2l-input-date-time-range label="Availability Range">
</d2l-input-date-time-range>| Property | Type | Description |
|---|---|---|
label |
String, required | Accessible label for the input fieldset that wraps the date-time inputs |
auto-shift-dates |
Boolean | Automatically shifts end date when start date changes to keep the same range |
child-labels-hidden |
Boolean | Visually hides the labels for start and end date-time inputs |
disabled |
Boolean | Disables the inputs |
end-label |
String, default 'End Date' |
Accessible label for the second date-time input |
end-opened |
Boolean | Indicates if the end date or time dropdown is open |
end-value |
String, default '' |
Value of the second date-time input |
inclusive-date-range |
Boolean | Validate on inclusive range (i.e., it is valid for start and end date-times to be equal) |
label-hidden |
Boolean | Hides the fieldset label visually |
required |
Boolean | Indicates that values are required |
start-label |
String, default 'Start Date' |
Accessible label for the first date-time input |
start-opened |
Boolean | Indicates if the start date or time dropdown is open |
start-value |
String, default '' |
Value of the first date-time input |
change: dispatched when a start or end date is selected or typed.start-valuereflects the value of the first input,end-valuereflects the value of the second input, and both are in ISO 8601 combined date and time format (YYYY-MM-DDTHH:mm:ss.sssZ) and in UTC time.
inline-help: Help text that will appear below the input. Use this only when other helpful cues are not sufficient, such as a carefully-worded label.
The date and time components generally follow the W3C's best practice recommendations for a Date picker dialog. For details on the accessibility of the calendar within the date input components, see Calendar Accessibility.
A few notable accessibility-related features of these components are:
- The expected date format is indicated both in placeholder text and a tooltip available on hover and focus
- Focus is trapped in the date input dropdown
- When the date input is opened with the keyboard, focus goes to either selected date, today, or earliest valid date if today is prior to
min-date - Extensive intuitive keyboard interaction support
The input-date-time and input-date-time-range components expect input in UTC (YYYY-MM-DDTHH:mm:ss.sssZ). These components will convert values automatically to the user's timezone to display the date/time to them, and then will provide the value back in UTC. No timezone conversions are needed.
The input-date, input-date-range, input-time, and input-time-range components do not handle timezone and so require the input to be in the user's timezone (if applicable), which corresponds to the user's timezone as specified in their account settings. The consumer of the component will need to handle any necessary UTC to local to UTC conversions. The following methods can be used for these conversions:
getLocalDateTimeFromUTCDateTime(utcDateTime)(whereutcDateTimeis the date/time in the formatYYYY-MM-DDTHH:mm:ss.sssZ) returns the date/time in the formatYYYY-MM-DDTHH:mm:ss.sssin the user's local timezonegetUTCDateTimeFromLocalDateTime(localDate, localTime)(wherelocalDateandlocalTimeare the date and time in the user's local timezone) returns the date/time in the formatYYYY-MM-DDTHH:mm:ss.sssZin UTC