Time input
The Time input component allows users to enter a time in multiple formats.
import { ... } from '@ag.ds-next/react/time-input';
() => { const [value, setValue] = React.useState(); const onChange = (timeValue) => { console.log('onChange', timeValue); setValue(timeValue); }; const invalid = value && !isValidTime(value.value); return ( <TimeInput invalid={invalid} label="Time" message="Enter a valid time" onChange={onChange} value={value} /> ); };
Time input is a superset of Text input, with additional functionality specific to entering times. It accepts all of Text input’s props, with changes to onChange
and value
.
Time input is a controlled component which means consumers of this component need to manage the state of this component by using the value
and onChange
props.
The onChange
handler provides an object with both a value
and formatted
version of the time. value
is always in 'HH:mm'
and formatted
is provided in the timeFormat
used. You can use this to display the time elsewhere in the UI, where necessary.
Do
- use when users are specifically required to enter an exact, arbitrary time.
Don’t
- use when users are required to enter free-form text that isn’t a time
- use when users are required to enter a specific, constrained time – use Time picker instead.
Invalid
Use the invalid
prop to indicate if the user input is invalid. The isValidTime()
function can be used to help identify whether the input is valid.
() => { const [value, setValue] = React.useState({ value: '9:66' }); const onChange = (timeValue) => { console.log('onChange', timeValue); setValue(timeValue); }; const invalid = value && !isValidTime(value.value); return ( <TimeInput invalid={invalid} label="Time" message="Enter a valid time" onChange={onChange} value={value} /> ); };
Changing the time format
The Time input component allows users to enter times in various formats. To input 9:00 pm, a user could input '9pm', '9:00pm', '2100', '21:00', 'T21:00:00.000Z', or other, lenient variations on these formats.
When a valid time is typed, on blur, the time will be formatted using the timeFormat
prop, which is set to 'h:mm aaa'
by default.
To modify the time format, you can change the timeFormat
prop to one of these supported time formats:
'h:mm aaa'
(e.g. 9:00 am, 9:00 pm)'hh:mm aaa'
(e.g. 09:00 am, 09:00 pm)'HH:mm'
(e.g. 09:00, 21:00)
() => { const [value, setValue] = React.useState(); const onChange = (timeValue) => { console.log('onChange', timeValue); setValue(timeValue); }; return ( <TimeInput label="Time" onChange={onChange} timeFormat="HH:mm" value={value} /> ); };
Colour
AgDS foreground components respond to the background colour of their parent container. When placed on a dark palette background, the dark palette variant of the component is displayed. When placed on a light palette background the light palette variant is displayed.
This logic ensures sufficient contrast between foreground and background elements is maintained to meet WCAG 2.1 AA, 4:5:1 contrast ratio for text (WCAG 1.4.3) and 3:1 for graphic elements that convey information (WCAG 1.4.11).
Light palette
<Box background="body" paddingX={{ xs: 0.75, md: 1.5 }} paddingY={1.5}> <Render> {() => { const [value, setValue] = React.useState(); const onChange = (timeValue) => { console.log('onChange', timeValue); setValue(timeValue); }; const invalid = value && !isValidTime(value.value); return ( <TimeInput invalid={invalid} label="Time input: on light background" message="Enter a valid time" onChange={onChange} value={value} /> ); }} </Render> </Box>
Dark palette
<Box background="body" paddingX={{ xs: 0.75, md: 1.5 }} paddingY={1.5} palette="dark"> <Render> {() => { const [value, setValue] = React.useState(); const onChange = (timeValue) => { console.log('onChange', timeValue); setValue(timeValue); }; const invalid = value && !isValidTime(value.value); return ( <TimeInput invalid={invalid} label="Time input: on dark background" message="Enter a valid time" onChange={onChange} value={value} /> ); }} </Render> </Box>
Related components
- Text input – This component allows users to enter free-form text.
- Time picker – The Time picker component allows users to easily select a time from a list of options.