Skip to content
Paste
UX Platform
Change the site theme
GitHub

Time Picker

An input field for users to enter a time.

Code ready:
Code done
Design assets:Pending
Documentation:Pending
Peer review:Pending
Status
Production
Version
0.1.1
Sources
Storybook
Import from
@twilio-paste/core/time-picker — or — @twilio-paste/time-picker

Guidelines#

About Time Picker#

The Time Picker is an input field which accepts a value in HH:mm format.

Currently, the Time Picker is built on top of the HTML time pickerlink takes you to an external page, using an input field with type="time", which comes with some inherent limitations. In order to release a functional and stable Time Picker for immediate use, we decided to work within these limitations with the intention of updating this package to a custom Time Picker in a future release. The current API was designed to avoid any breaking changes with future versions of the Time Picker.

Browser support#

Because browsers' implementations of the native time picker vary, this component may not be fully accessible in all cases. Chrome/Edge, Safari and Firefox all support the Time Picker, but the user experience differs browser-to-browser. Some of those differences are outlined below:

Chrome/Edge
  • Default value is "--:-- --"
  • Clock pop-up is triggered by clicking on the clock icon - clicking on the input field places focus on the value
  • Scrollable time selector pop-up
Chrome/Edge implementation of time picker
Safari
  • Default value is 12:30 PM
  • No clock icon or time selector pop-up, only usable by keyboard (number or arrow keys)
  • Clicking on the input field places focus on the hour value
Chrome/Edge implementation of time picker
Firefox
  • Default value is "--:-- --"
  • No clock icon or time selector pop-up, only usable by keyboard (number or arrow keys)
  • Clicking on the input field places focus on the hour value
Chrome/Edge implementation of time picker

While cross-browser functionality, style and accessibility differences are present, they will not affect the usability of the Time Picker. The API is stable and full usage of the component is encouraged. There are certain use cases not included in the input type="time" functionality, such as a time range picker. You can find examples of how to recreate those use cases below. If there's a Time Picker use case not covered by the current implementation, feel free to open a Discussionlink takes you to an external page so that we can help you find a solution.

Accessibility#

  • Include a visible label on all Time Pickers.
  • Each label must use the htmlFor prop that matches the id of the associated input.
  • Use one of 3 ways to label a Time Picker:
    • Visible label with Label (preferred)
    • Visible label that's associated to the Time Picker with aria-labelledby
    • Label directly using aria-label
  • Provide clear identification of required fields in the label or at the start of a form. If you use the required field indicator, include the form key at the start of the form.
    • Use the required prop to programatically indicate they are required to browsers.
  • Include inline error text with the error icon on any field that errors to make it visually clear that the field changed.
  • If the Time Picker has associated Help Text or error text, include the aria-describedby prop on the Time Picker. This should match the id of the help or error text.

Examples#

The Time Picker component should include the base TimePicker, along with supporting elements to compose an input field that gives users the context they need to successfully fill it out.

  • Label — A label should be included for every Time Picker and provide a short title for its associated input.
  • Required field indicator — In a form where there are fewer or as many required fields as optional, use a required indicator to show users which fields are required to be filled out.
  • Help text — Text that's placed below the field to help users prevent an error and describe what makes the Time Picker input successful.

Make sure to connect the Label to the TimePicker. This is done with the htmlFor prop on the label, and the id prop on the Time Picker. Those two need to match.

If the Time Picker has any associated Help Text, it should also use the aria-describedby prop that equals the id of the Help Text. This ensures screen readers know the Help Text ties directly to the Time Picker.

Select a time.

Time range picker#

The Time Picker doesn't currently support the selection of time ranges within a single input field, however a time range picker can be easily implemented using two side-by-side Time Pickers.

Time formatting#

In addition to the Time Picker, this package exports a formatReturnTime() function that can be used to format the time value that's being returned from the Time Picker.

Note: the format of the time being displayed by the Time Picker cannot be changed. The display value is formatted according to the locale of the user's browserlink takes you to an external page. The parsed value format, however, which is returned in HH:mm format (using a 24-hour time format), can be changed.

To change the format of the return time value, we recommend using the formatReturnTime() function on the Time Picker's onChange() or onBlur() handler.

The function accepts two parameters: (1) the time value that should be formatted (e.g. '14:52'), and (2) the desired time format (e.g. 'mm:hh aa'). It uses a library called date-fnslink takes you to an external page to return the given time in the desired format. Time format must follow the tokens outlined by date-fnslink takes you to an external page.

Select a time above.
Return value:

States#

TimePicker with inline error#

Change a Time Picker to its error state and add an inline error if the value entered doesn't pass validation requirements.

An inline error is placed below the field to inform a user of any errors in their value. If Help Text exists, the error text should replace and repeat the Help Text.

Select a time.

Disabled input#

Use a disabled Time Picker to show users that they can't interact with it.

If you want to show information that can't be edited, use a read-only field or consider another way of showing static information.

Choose a time.

Read-only input#

Use a read-only Time Picker when a its value can't be changed, but users should be able to read or apply focus on it.

Choose a time.

Composition notes#

A Time Picker must have at least a label and an input.

Quick note about Time Picker DOM methods

There are three methods that come with the HTML picker: stepUp(), stepDown() and select(). Usage of these methods is possible, but we do not encourage it, as they may not be supported in future versions of the Time Picker. Use at your own risk!

Positioning Time Pickers#

When using multiple Time Pickers, stack them vertically with $space-80 spacing between each field. To stack them, you can use either a Box or a Stack (as seen in the example below).

Select a time above.
Select a time above.

Avoid placing multiple pickers on the same horizontal row to help make it easier to scan a page vertically. Use a Grid if you need to place them horizontally.

Labels and Help Text#

Labels should clearly describe the time value being requested. They should be concise and descriptive, not instructional. To do this:

  • Use Help Text to provide instruction if needed. For example, don't use "Enter the date you wish to receive your bill below" as label text. Instead, use "Billing date" as a label and "Your account will be automatically billed on the above date." as Help Text.
  • Avoid articles ("a", "the") and punctuation. For example, use "SIM registration code" rather than "The SIM registration code".

To support internationalization, avoid starting a sentence with the label and using the field to finish it since sentence structures vary across languages. For example, use "Call log expiration time" or "How long should logs be stored?". Don't use "Remove logs after:".

Required field indicator#

Use required indicators to show users which fields they must fill out.

Select a time.

Validation#

Validate Time Picker fields on form submission.

Validating a field input when the user leaves the current field (on blur) can be helpful to check for syntax errors. However, this can be frustrating to users who tab through controls to navigate a page, and to screen reader users, who might not be able to detect that an error occurred on blur.

Don't prevent form submission by disabling the submit button. An error message can give more information than a disabled button can to help users figure out which fields are invalid.

Usage of the min and max props on Time Picker is discouraged as browser support is varied and limited.

Errors#

Use inline error text to explain how to fix an error.

Ideally, Help Text should have enough information to help users prevent errors. If Help Text exists and you need to show an error, the error text should replace and repeat the Help Text until the error has been resolved.

Error text should:

  • Be actionable. Explain how to fix an error and if reasonable, why it happened so that it might also be prevented in the future.
  • Be concise and simple, maybe even more than normal. Avoid jargon. Try to keep error text to 2 sentences or fewer.
  • Use the passive voice for input errors to avoid placing blame on the user. For example, "A friendly name is required."
  • Use the active voice for system errors. For example, "Our systems are currently down. Please contact our support team."

Time Picker and placeHolder

Because Time Picker has a default display value of --:-- -- (and defaults to 12:30 PMon Safari), any value that gets passed into placeholder will be overwritten (and effectively ignored).

Anatomy#

PropertyDefault tokenModifiable?
Label text
  • $font-size-30
  • Default: $color-text, $font-weight-semibold
  • Disabled: $color-text-weaker, $font-weight-semibold
No
Required field indicator
  • 4px size (0.25rem)
  • Background: $color-background-required
No
Box Shadow
  • Default: $shadow-border
  • Hover: $shadow-border-primary-strong
  • Disabled: $shadow-border-weak
  • Error: $shadow-border-error
  • Error hover: $shadow-border-error-strong
No
Background
  • Default: $color-background-body
  • Disabled, Readonly: $color-background
No
Value text
  • $font-size-30
  • Default, Readonly: $color-text
  • Disabled: $color-text-weaker
No
Help text$color-text-weak, $font-size-30No
Inline error
  • Text: $color-text-error, $font-size-30
  • Icon: IconError, $color-text-error, $icon-size-20
No
Spacing
  • Label:
    • Bottom: $space-10
    • Between label and required indicator: $space-20
  • TimePicker:
    • Left padding: $space-40
    • Top, right, bottom padding: $space-30
  • Help text:
    • Top: $space-20
  • Inline error:
    • Spacing between icon and text: $space-20
    • Top: $space-20
No

Usage Guide#

API#

Installation#

yarn add @twilio-paste/time-picker - or - yarn add @twilio-paste/core

Usage#

import {TimePicker, formatReturnTime} from '@twilio-paste/core/time-picker';
import {Label} from '@twilio-paste/core/label';
import {HelpText} from '@twilio-paste/core/helptext';
const TimePickerExample = () => {
return (
<>
<Label htmlFor="foo" required>
Start time
</Label>
<TimePicker
aria-describedby="foo_text"
id="foo"
name="foo"
onChange={(evt) => formatReturnTime(evt.target.value, 'hh:mm aa')}
required
/>
<HelpText id="foo_text">Please select a time.</HelpText>
</>
);
};

TimePicker Props#

All the valid HTML attributes for input (except type) are supported, including the following props:

PropTypeDescriptionDefault
id?stringSets the id of the time picker. Should match the htmlFor of Label.null
name?stringSets the name of the time picker.null
value?stringSets the value of the time picker.null
disabled?booleanDisables the time picker.false
readOnly?booleanSets the time picker to readonly.false
required?booleanSets the time picker as required.false
hasError?booleanSets the time picker to an error state.false
min?stringSets the earliest valid time value.null
max?stringSets the last valid time value.null
onChange?(event: React.MouseEvent<HTMLElement>)null
onFocus?(event: React.MouseEvent<HTMLElement>)null
onBlur?(event: React.MouseEvent<HTMLElement>)null
variant?'default', 'inverse''default'

formatReturnTime() Props#

PropTypeDescriptionDefault
timeValuestringTime value to be formatted. Must be in HH:mm format.null
timeFormatstringSpecify the format in which to return the timeValue. Formats come from the date-fns library.null

Label Props#

All the valid HTML attributes for label are supported including the following props:

PropTypeDescriptionDefault
children?ReactNodenull
htmlForstringSets the for of the label. Should match the id of TimePicker. Required.null
disabled?booleanShows the time picker is disabled.false
required?booleanShows the time picker is required.false
marginBottom?'space0', 'space10''space10'
variant ?'default', 'inverse''default'

HelpText Props#

All the valid HTML attributes (role, aria-*, type, and so on) including the following props:

PropTypeDescriptionDefault
children?ReactNodenull
marginTop?'space0', 'space20''space20'
variant?'default', 'error', 'error_inverse', 'inverse'Changes the state.'default'

Black lives matter.