@asphalt-react/time-picker v1.23.2
TimePicker
TimePicker lets users type and select a specific time in 12-hour format. It shows a picker inside a popover to select a time from. It also has an input field to type a time. Both the picker and field are always in sync. A button with clock icon in the input field toggles the picker.
The input field accepts time in hh:mm AM
format; follows the ISO 8601 calendar date extended format. If a user types an invalid time in the field, the picker retains its previous state.
The picker allows users to select the hour, minute and day period (AM/PM). By default, the picker shows the selected time (if present), else the current time. The picker has next/previous buttons to change the hour and minute values. 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 "12", clicking the next hour button rolls the value over to "1". Clicking outside the picker or pressing Esc closes the picker, persisting the changes made through it.
The minute values change on a particular interval (see step prop). The minute values are always a multiple of the interval. For example, Let's say the interval is "15". A user types "10:32 AM" and opens the picker. The picker shows "32" as the minute value. Clicking the next minute button changes the value to "45" and then to "00". Similarly, clicking the previous month button changes the value to "30", then to "15" and so on.
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)} />
}
Errors
TimePicker validates the input values and raises these errors:
InvalidTime
: Ifvalue
prop receives an invalid date object; use the Date() constructor to create date objects.UserInvalidTime
: When a user types a date which is either invalid or in incorrect format. For example:12:32 AM
✅1:34 pm
✅12:93 PM
❌ - invalid time18:23 PM
❌ - invalid time15:34
❌ - incorrect format
Accessibility
- The TimePicker is accessible via keyboard.
- The picker traps focus and rotates the focus among its elements.
- The next/previous buttons for the hour and minute labels in the picker have
aria-label
to assist screen readers. - 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 in
hh:mm AM
format.
- When the picker closes, the focus shift to the time icon button. The screen reader then announces the selected time.
- If the end-user types an invalid date in the input field, TimePicker adds
aria-invalid=”true”
to the field. - The day period buttons are semantic radio buttons. Use ↑ or ↓ keys to change selection.
- 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 5, 10, 15.
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" |
1 month ago
2 months ago
5 months ago
7 months ago
10 months ago
11 months ago
8 months ago
9 months ago
9 months ago
9 months ago
9 months ago
11 months ago
12 months ago
1 year ago
1 year ago
12 months ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
2 years ago
2 years ago
1 year ago
1 year ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago