Agriculture Design System
Design System for import and export services

Time input

The Time input component allows users to enter a time in multiple formats.

View in FigmaView in StorybookView in Github
import { ... } from '@ag.ds-next/react/time-input';
Open in Playroom, opens in a new tabOpen responsive preview
() => {
	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>
  • 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.