@asphalt-react/time-picker
v2.0.0-rc.4
Published
Picker to select & set a specific time
Downloads
290
Readme
TimePicker
TimePicker lets you type and select time. TimePicker renders in 12 hour format by default but you can opt for the 24 hour format as well. 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. TimePicker also supports selection of time range.
For touch capable devices, TimePicker renders the native UI of the user agent which you can disable as well. The range feature will not work when the native picker is active. This is a restriction from the browser. You can disable the native picker to use the time range selection feature.
Usage
import TimePicker from "@asphalt-react/time-picker"
export default () => {
const [time, setTime] = React.useState([new Date(2023, 7, 8, 15, 12, 12)])
<TimePicker
value={time}
onChange={(time) => {
setTime(time)
}}
onError={() => false}
/>
}
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:
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:
By default,
12:32 AM
✅1:34 pm
✅18:23 PM
❌ - invalid time
When meridiem
is set to false
which enables 12 hour format
21:00
✅01:00
✅10:00 AM
❌ - invalid time
TimePicker with range
,
12:32 AM to 18:23 AM
✅13:00 to 23:45
✅5:00 AM to 21:00
❌ - invalid range15:00 - 16:00
❌ - invalid range
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.
- 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. Pass the start time followed by end time when it's a ranged TimePicker.
| type | required | default | | ------- | -------- | ------- | | arrayOf | true | N/A |
onChange
Callback to handle time change.:
time
: This is an array which contains selected time as a JS date object. It contains the start time as the first index followed by the end time (if range is true).event
: The react synthetic event.
const timeHandler = (time, event) => {
// handle the selected time
}
Note: TimePicker will show the console warnings if value
or onChange
props are missing, as they are needed to update the time.
Hence, we recommend you to pass both the props.
| type | required | default | | ---- | -------- | ------- | | func | true | 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" |
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" |
meridiem
Enables 12 hour time format.
| type | required | default | | ---- | -------- | ------- | | bool | false | true |
native
Enables native timepicker when on touch devices. You can change this behavior by setting it to false. Range does not work when this is enabled.
| type | required | default | | ---- | -------- | ------- | | bool | false | true |
range
Enables range time picker. This feature will not work when native is enabled.
| type | required | default | | ---- | -------- | ------- | | bool | false | false |
startSwitchCaption
Caption for start time in range time picker.
| type | required | default | | ------ | -------- | ------------ | | string | false | "Start Time" |
endSwitchCaption
Caption for end time in range time picker.
| type | required | default | | ------ | -------- | ---------- | | string | false | "End Time" |