Skip to content

input-date-time.md

Latest commit

 

History

History
301 lines (232 loc) · 18.5 KB

input-date-time.md

File metadata and controls

301 lines (232 loc) · 18.5 KB

Date & Time Inputs

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>

Best Practices

  • 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 time zone
  • Don't combine inputs to form a range, use an actual range input instead; this will handle layout and validation automatically

Date Input [d2l-input-date]

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 time zone (if applicable).

<script type="module">
  import '@brightspace-ui/core/components/inputs/input-date.js';
</script>
<d2l-input-date label="Birthdate">
</d2l-input-date>

Properties

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.
name String Name of the form control. Submitted with the form as part of a name/value pair.
opened Boolean Indicates if the calendar dropdown is open
required Boolean Indicates that a value is required
value String, default '' Value of the input.

Events

  • change: dispatched when a date is selected or typed. value reflects the selected value and is in ISO 8601 calendar date format (YYYY-MM-DD).

Slots

  • 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.

Date Range Input [d2l-input-date-range]

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>

Properties

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
name String Name of the form control. Submitted with the form as part of a name/value pair.
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

Events

  • change: dispatched when a start or end date is selected or typed. start-value reflects the value of the first input, end-value reflects the value of the second input, and both are in ISO 8601 calendar date format (YYYY-MM-DD).

Slots

  • 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.

Time Input [d2l-input-time]

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 time zone (if applicable).

<script type="module">
  import '@brightspace-ui/core/components/inputs/input-time.js';
</script>
<d2l-input-time label="Time">
</d2l-input-time>

Properties

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
name String Name of the form control. Submitted with the form as part of a name/value pair.
opened Boolean Indicates if the dropdown is open
required Boolean Indicates that a value is required
time-zone-hidden Boolean Hides the time zone inside the selection dropdown. Should only be used when the input value is not related to any one timezone
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 time zone (if applicable).

Events

  • change: dispatched when a time is selected or typed. value reflects the selected value and is in ISO 8601 time format (hh:mm:ss).

Slots

  • 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.

Time Range Input [d2l-input-time-range]

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 time zone (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>

Properties

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
name String Name of the form control. Submitted with the form as part of a name/value pair.
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.

Slots

  • 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.

Date-Time Input [d2l-input-date-time]

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 time zone).

<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>

Properties

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 time zone 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
name String Name of the form control. Submitted with the form as part of a name/value pair.
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.

Events

  • change: dispatched when there is a change in selected date or selected time (when date is already selected). value reflects the selected value and is in ISO 8601 combined date and time format (YYYY-MM-DDTHH:mm:ss.sssZ).

Slots

  • 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.

Date-Time Range Input [d2l-input-date-time-range]

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 time zone).

<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>

Properties

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
name String Name of the form control. Submitted with the form as part of a name/value pair.
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

Events

  • change: dispatched when a start or end date is selected or typed. start-value reflects the value of the first input, end-value reflects 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.

Slots

  • 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.

Accessibility

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

Time Zone

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 time zone to display the date/time to them, and then will provide the value back in UTC. No time zone conversions are needed.

The input-date, input-date-range, input-time, and input-time-range components do not handle time zone and so require the input to be in the user's time zone (if applicable), which corresponds to the user's time zone 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) (where utcDateTime is the date/time in the format YYYY-MM-DDTHH:mm:ss.sssZ) returns the date/time in the format YYYY-MM-DDTHH:mm:ss.sss in the user's local time zone
  • getUTCDateTimeFromLocalDateTime(localDate, localTime) (where localDate and localTime are the date and time in the user's local time zone) returns the date/time in the format YYYY-MM-DDTHH:mm:ss.sssZ in UTC