Time picker

import { ... } from '@ag.ds-next/react/time-picker';

As the user enters text into the field, its autocomplete offers suggestions, and highlights ones that best match the text entered. The list closes when an option is selected.

Time picker is a superset of Combobox, with additional functionality specific to entering times. It accepts all of Combobox’s props, with the exception of options and renderItem.

Time picker is a controlled component which means consumers of these components need to manage the state of these components by using the value and onChange props.

() => {
	const [value, setValue] = React.useState(null);

	const onChange = (timeValue) => {
		console.log('onChange', timeValue);
		setValue(timeValue);
	};

	return (
		<TimePicker
			label="Select a time"
			hint="Start typing to see results"
			value={value}
			onChange={onChange}
		/>
	);
};

Do

• use to help users select from a large list of specific times
• use an appropriate time format for the options
• use an appropriate range and interval for the options
• create hint text to let the user know they can search or select
• consider whether the list of selections is complex enough to merit searching and filtering
• indicate whether input is optional.

Don’t

• use if the list of possible results is small – use Select instead
• use when users are required to enter an exact, arbitrary time – use Time input instead.

Time picker

Use the TimePicker component when users can choose a single item from a predefined list of options. Regardless of the time format used for the options, it supports multiple time formats to be entered and matched against.

() => {
	const [value, setValue] = React.useState(null);

	const onChange = (timeValue) => {
		console.log('onChange', timeValue);
		setValue(timeValue);
	};

	return (
		<TimePicker
			label="Select a time"
			hint="Start typing to see results"
			value={value}
			onChange={onChange}
		/>
	);
};

Changing the time range and intervals

By default, Time picker displays options from 12 am to 11:45 pm at 15 minute intervals. This can be customised by setting the min, max and interval props. min and max accept a 24 hour time string in the HH:mm format (such as '09:00'). interval accepts a number of minutes between 1 and 180 to create the options at appropriate intervals between the min and max times.

() => {
	const [value, setValue] = React.useState(null);

	const onChange = (timeValue) => {
		console.log('onChange', timeValue);
		setValue(timeValue);
	};

	return (
		<TimePicker
			label="Select a time"
			hint="Start typing to see results"
			value={value}
			onChange={onChange}
			min="09:00"
			max="17:00"
			interval={30}
		/>
	);
};

Changing the time format

Like Time input, the Time picker component allows users to enter times in various formats, however, its options are always displayed in a specific format ('h:mm aaa' by default). To input 9:00 pm, a user could input '9pm', '9:00pm', '2100', '21:00' or other, lenient variations on these formats.

To modify the time format used in the options, 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(null);

	const onChange = (timeValue) => {
		console.log('onChange', timeValue);
		setValue(timeValue);
	};

	return (
		<TimePicker
			label="Select a time"
			hint="Start typing to see results"
			value={value}
			onChange={onChange}
			timeFormat="HH:mm"
		/>
	);
};

Loading options

Unlike ComboboxAsync which can asynchronously load its options over the network, Time picker instead uses the simple, boolean loading prop to indicate that the options are not yet ready to be displayed.

() => {
	const [value, setValue] = React.useState(null);

	const onChange = (timeValue) => {
		console.log('onChange', timeValue);
		setValue(timeValue);
	};

	return (
		<TimePicker
			label="Select a time"
			hint="Start typing to see results"
			value={value}
			onChange={onChange}
			loading
		/>
	);
};

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({ label: '9:66', value: '9:66' });

	const onChange = (timeValue) => {
		console.log('onChange', timeValue);
		setValue(timeValue);
	};

	const invalid = value && !isValidTime(value.value);

	return (
		<TimePicker
			invalid={invalid}
			label="Select a time"
			hint="Start typing to see results"
			message="Enter a valid time"
			onChange={onChange}
			value={value}
		/>
	);
};

Related components

• Combobox – This component allows users to select from a list of options. It’s especially useful when there are many options to choose from.
• Time input – The Time input component allows users to enter a time in multiple formats.