@asphalt-react/time-picker

TimePicker

TimePicker lets users type and select a specific time in both 12-hour and 24-hour format. It shows a picker inside a popover which has buttons to select a time. You can set the interval for the minutes field. It also has an input field for typing a time. A button with clock icon in the input field toggles the picker and clicking outside the picker or pressing Esc closes the picker, persisting the changes made through it.

For touch capable devices, TimePicker renders the native UI of the user agent.

Usage

import TimePicker from "@asphalt-react/time-picker"

export default () => {
  const [time, setTime] = React.useState(new Date(2021, 4, 25, 4, 45))

  <TimePicker value={time} onTimeChange={({ time }) => setTime(time)} />
}

Supported formats

The input field accepts time following the ISO 8601 calendar date extended format. If a user types an invalid time in the field, the picker retains its previous state.

12-hour format

The input field in 12-hour format shows the time in hh:mm AM format. The picker allows the users to select the hour, minute and day period (AM/PM). Either of the two day period buttons is selected at all times. The hour and minute values roll over on reaching the end. For example: If the hour value is "10", clicking the next hour button rolls the value over to "11".

24-hour format

The input field in 24-hour format shows the time in hh:mm format. Set militaryTime prop to use this format. The picker allows the users to select the hour and the minute. The hour and minute values roll over on reaching the end. For example, if the the hour value is "22", clicking the next hour button rolls the value over to "23".

Configuring Minutes Steps

The minute values change on a particular interval using the minuteStep prop. The minute values are always a multiple of the interval. By default, the interval is set to "15". So, if the current value of minute is "30", clicking the next minute button changes the value to "45" and then to "00". Similarly, clicking the previous minute button changes the value to "30", then to "15" and so on.

Errors

TimePicker validates the input values and raises these errors:

1. InvalidTime: If value prop receives an invalid date object; use the Date() constructor to create date objects.
2. UserInvalidTime: When a user types a date which is either invalid or in incorrect format. For example:

By default,

• 12:32 AM ✅
• 1:34 pm ✅
• 18:23 PM ❌ - invalid time

When militaryTime is set to true which enables 24 hour format

• 21:00 ✅
• 01:00 ✅
• 10:00 AM ❌ - invalid time

Accessibility

1. The TimePicker is accessible via keyboard.
2. The picker traps focus and rotates the focus among its elements.
3. The next/previous buttons for the hour and minute labels in the picker have aria-label to assist screen readers.
4. The time icon button has an aria-label attribute with value that change depending on whether a time is selected or not:
   • If no time is selected, the label is "Select a time"
   • If TimePicker already has a value, the label is "Selected time is TIME_STRING", where TIME_STRING is the selected time.
5. When the picker closes, the focus shift to the time icon button. The screen reader then announces the selected time.
6. If the end-user types an invalid date in the input field, TimePicker adds aria-invalid=”true” to the field.
7. The day period buttons are semantic radio buttons. Use ↑ or ↓ keys to change selection.
8. TimePicker accepts all aria attributes for role=”textbox”

Props

value

Selected time. It should always contain the current selected time.

Note: TimePicker will show the console warnings if value or onTimeChange props are missing, as they are needed to update the time. Hence, we recommend you to pass both the props.

type	required	default
object	false	N/A

onTimeChange

Callback to handle time change. The argument is an object of the shape:

• time: Selected time as a JS date object.
• event: The react synthetic event.

Use the time property to update the value prop.

const timeHandler = ({ time, event }) => {
 // handle the selected time
}

Note: TimePicker will show the console warnings if value or onTimeChange props are missing, as they are needed to update the time. Hence, we recommend you to pass both the props.

type	required	default
func	false	N/A

minuteStep

Step interval for minute values in the picker. Possible values are 1, 5, 10, 15.

The value "1" is available from v1.23.2+

type	required	default
enum	false	15

invalid

Renders TimePicker in error state.

type	required	default
bool	false	false

onError

Callback to handle errors. The argument is an instance of JS Error.

function onError(error) {
  // handle the error
}

type	required	default
func	false	N/A

size

Size of the time picker. Possible values are "m", "l" for medium & large.

type	required	default
enum	false	"m"

placeholder

Placeholder for the input field.

type	required	default
string	false	"hh:mm AM"

disabled

Disables the input field.

type	required	default
bool	false	false

stretch

Enables the input field to take parent's width. The size of the picker does not change.

type	required	default
bool	false	false

timeIconLabel

accessibility

aria-label for time icon button

type	required	default
string	false	N/A

nextHourLabel

accessibility

aria-label for next hour button

type	required	default
string	false	"next hour"

previousHourLabel

accessibility

aria-label for previous hour button

type	required	default
string	false	"previous hour"

nextMinuteLabel

accessibility

aria-label for next minute button.

type	required	default
string	false	"next minute"

previousMinuteLabel

accessibility

aria-label for previous minute button.

type	required	default
string	false	"previous minute"

militaryTime

Enables 24 hour time format

type	required	default
bool	false	false