Time picker

A time picker helps users select a specific time.

hh:mm
1
2
3
4
5
6
7
8
9
<form class="usa-form">
  <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">hh:mm</div>
    <div class="usa-time-picker">
      <input class="usa-input" id="appointment-time" name="appointment-time" type="text" aria-describedby="appointment-time-label appointment-time-hint">
    </div>
  </div>
</form>

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

  • See combo box usability guidance. The time picker is a specialized combo box, see the combo box documentation for complete usability guidance.

Accessibility

  • See combo box accessibility guidance. The time picker is a specialized combo box, see the combo box documentation for complete accessibility guidance.

Implementation

The properties and procedures listed below that show .usa-time-picker as the element are specific to the time picker, but the time picker is a specialized combo box instance and supports all combo box properties and procedures on .usa-time-picker just as on .usa-combo-box.

  • 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. Those listed below that show .usa-time-picker as the element are specific to the time picker, but the time picker is a specialized combo box instance and supports the combo box initialization properties on .usa-time-picker just as on .usa-combo-box.
    Property Element Description

    required

    select

    The combo box component will be required in terms of native form validation.

    disabled

    select

    The combo box component will be disabled / read-only. You can re-enable it by executing the enable procedure on the component.

    data-placeholder

    .usa-combo-box

    To update the placeholder text of the combo box, use the data-placeholder attribute. We recommend using a label or hint instead of a placeholder.

    data-default-value

    .usa-combo-box

    The combo box will set this value as the default selection if it is found within the select options.

    data-min-time

    .usa-time-picker

    The start time used in the time picker in hh:mm 24-hour format. The default is 00:00.

    data-max-time

    .usa-time-picker

    The end time used for the time picker in hh:mm 24-hour format. The default is 23:59.

    data-step

    .usa-time-picker

    The number of minutes between options. The minimum is 1 minute and the default is 30 minutes.

  • 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-combo-box

    The combo box will use this regular expression to filter the combo box 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 using data-filter="{{numberFilter}}.*"). The default filter is .*{{query}}.*, which is a simple “find anywhere within the option” text.

  • Additional component 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-combo-box

    The combo box component will be enabled.

    disable

    .usa-combo-box

    The combo box component will be disabled / read-only.

Time picker settings

This component has no settings.

Time picker variants

This component has no variants.

Package information

  • Package usage: @import form-controls
  • Requires: required, global