Components
Time picker
A time picker helps users select a specific time.
Passed WCAG 2.1 AA
<div class="usa-form-group">
<label class="usa-label" id="appointment-time-label" for="appointment-time"
>Appointment time</label
>
<div class="usa-hint" id="appointment-time-hint">
Select a time from the dropdown. Type into the input to filter options.
</div>
<div class="usa-time-picker">
<input
class="usa-input"
id="appointment-time"
name="appointment-time"
aria-describedby="appointment-time-label appointment-time-hint"
/>
</div>
</div>Guidance
When to use the time picker component
- Scheduling. Use the time picker to schedule a time from common, consistent increments, such as planning a meeting time in 30-minute blocks.
When to consider something else
- Exact time. Plain text input is more appropriate for historical exact times, like time of birth.
Usability guidance
- Use option strings familiar to users. The combo box filters by matching strings. Include option text that includes familiar strings or spellings (i.e. if using the combobox with a state list, include the postal abbreviation in the option text: District of Columbia (DC)).
- Make sure to test. Test select menus thoroughly with members of your target audience. Several usability experts suggest they should be the “UI of last resort.” Many users find them confusing and difficult to use.
- Avoid dependent options. Avoid making options in one select menu change based on the input to another. Users often don’t understand how choosing an item in one impacts another
- Use a good default. When most users will (or should) pick a particular option, make it the default:
<option selected="selected">Default</option>. - Avoid auto-submission. Don’t use JavaScript to automatically submit the form (or do anything else) when an option is selected. Offer a “submit” button at the end of the form instead. Users often change their choices multiple times. Auto-submission is also less accessible.
Accessibility guidance
- Customize form controls accessibly. If you customize this component, ensure that it continues to meet the accessibility requirements that apply to all form controls.
- Always use a label. Make sure your select element has a label. Don’t replace it with the default menu option (for example, removing the “State” label and just having the menu read “Select a state” by default).
- Avoid auto-submission. Don’t use JavaScript to automatically submit the form (or do anything else) when an option is selected. Auto-submission disrupts screen readers because they select each option as they read them.
Using the time picker component
-
Properties. The following properties modify component functionality. These properties can be set or adjusted at any time before or after initialization in order to have an effect.
Property Element Description data-filter.usa-time-picker
The time picker will use this regular expression to filter the time picker options. You are declaring a case insensitive match over the entire option text, which means
^and$are added automatically. You can specify the inputted query with{{query}}. You can also declare a custom query filter as a data property as well, which can be used in the custom filter (data-number-filter="[0-9]"and then usingdata-filter="{{numberFilter}}.*"). The default filter is.*{{query}}.*, which is a simple “find anywhere within the option” text. -
Initialization properties. The following properties update the component during initialization. These properties must be set before the component is initialized in order to have an effect.
Property Element Description data-min-time.usa-time-picker
The start time used in the time picker in
hh:mm24-hour format. The default is00:00.data-max-time.usa-time-picker
The end time used for the time picker in
hh:mm24-hour format. The default is23:59.data-step.usa-time-picker
The number of minutes between options. The minimum is
1minute and the default is30minutes.value.usa-input
The default value shown in the time picker.
-
Procedures. The following static procedures update the component after initialization. These are in addition to the primary methods referenced in the JS customization documentation.
Procedure Parameters Description enable.usa-time-picker
The time picker component will be enabled.
disable.usa-time-picker
The time picker component will be disabled / read-only.
Time picker settings
This component has no settings.
Time picker variants
This component has no variants.
Accessibility test status
The USWDS team did 11 tests based on WCAG 2.1 AA success criteria.
| Total tests |
Passed
|
Passed with exceptions
|
Conditional
|
Failed
|
|---|---|---|---|---|
| 11 | 9 | 0 | 2 | 0 |
Overview of recent accessibility test results:
Learn more on the time picker accessibility tests page.
Package
-
Package usage:
@forward "usa-time-picker"; - Dependencies:
uswds-fonts,usa-label,usa-hint,usa-input
Latest updates
Meaningful code and guidance updates are listed in the following table:
| Date | USWDS version | Affects | Description |
|---|---|---|---|
| 2024-11-13 | 3.10.0 |
|
Updated the time picker hint text to improve clarity. This update allows the component to meet the success criteria in WCAG 3.3.2. More information: uswds#6147 |
| 2024-11-07 | N/A |
|
Added WCAG compliance tag and accessibility test status section. More information: uswds-site#2921 |
| 2022-04-28 | 3.0.0 |
|
Breaking Updated to Sass module syntax and new package structure. More information: uswds#4656 |
| 2022-04-11 | N/A |
|
Added documentation for the |
| 2022-04-11 | 2.13.3 |
|
Allow default |
