Ask users for dates and times

Time input

Time input allows users to type an exact time - for example, the known time of an incident or event.

When the user enters a time, formatting is applied to collect input in a consistent format.

It should be used in situations when a user knows and can provide an exact and arbitrary time.

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

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

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

	return (
		<TimeInput
			hideOptionalLabel
			invalid={invalid}
			label="Time"
			message="Enter a valid time"
			onChange={onChange}
			value={value}
		/>
	);
};

Time picker

Time picker is a composition of combobox that allows users to select a time from a predefined list of consistent time intervals.

As the user enters text into the field, autocomplete narrows the list to match their input.

The list is closed when a time is selected.

It should be used when a user needs to select from a large list of specific times.

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

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

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

Asking for specific known dates

When a specific known date is required, use a format tolerant Text input that validates acceptable formats and auto formats minor issues like spaces or capital letters.

Examples of a specific known date are birth date, when an application was made or an expiry date.

<TextInput hideOptionalLabel hint="(e.g. 15/02/1982)" label="Date of event" />

The Date picker component can also be used when a specific known date is required.

Asking for approximate dates

When asking for a date that may be general or hard for users to remember, allow them to provide an approximate date.

Use a format-tolerant text input that accepts a range of valid formats and automatically reformats minor issues, such as extra spaces or capital letters.

Examples of approximate dates include any dates that are indicative and non-specific like ’January 2025’.

<TextInput
	hideOptionalLabel
	hint="(e.g. December 2025)"
	label="Approximate date"
/>

Picking dates

Use Date picker so a user can pick a specific or available date from a calendar.

The Date picker calendar allows selection of both past and future dates. It displays one month at a time, with controls to navigate by month or year.

Use Date picker when a user needs to pick an unknown date or when they need to find an available date like when booking appointments.

() => {
	const [value, setValue] = React.useState();
	return (
		<DatePickerNext
			hideOptionalLabel
			label="Select date"
			onChange={setValue}
			value={value}
		/>
	);
};

Picking date ranges

Use Date range picker when a user needs to pick a specific or available date range from a calendar.

The Date range picker calendars allow selection of both past and future dates. They display two months at a time on large screens, with controls to navigate by month or year.

Use Date range picker when a user needs to pick a start and end. For example, when providing transport times or booking accommodation.

() => {
	const [value, setValue] = React.useState({ from: undefined, to: undefined });
	return (
		<DateRangePickerNext value={value} onChange={setValue} hideOptionalLabel />
	);
};

Picking a date and time

Use the Grouped fields component to combine closely related inputs like Date picker and Time picker when asking users to provide a specific date and time.

An examples of when we combine date and time in Grouped fields is booking a departure time or an appointment.

() => {
	const [dateValue, setDateValue] = React.useState();
	const [timeValue, setTimeValue] = React.useState();
	return (
		<GroupedFields legend="Departure time" hideOptionalLabel>
			{({ field1Props, field2Props }) => (
				<>
					<DatePickerNext
						hideOptionalLabel
						label="Date"
						onChange={setDateValue}
						value={dateValue}
						{...field1Props}
					/>
					<TimePicker
						hideOptionalLabel
						label="Time"
						onChange={setTimeValue}
						value={timeValue}
						{...field2Props}
					/>
				</>
			)}
		</GroupedFields>
	);
};

Time zones

Use the Grouped fields component to combine closely related inputs like Time picker and a time zone Select when asking users for a time and the time zone is important.

An example of when we combine time and time zone in Grouped fields is when the time a consignment will arrive in another country is required.

() => {
	const [timeValue, setTimeValue] = React.useState();
	const [timezoneValue, setTimezoneValue] = React.useState();
	return (
		<GroupedFields legend="Departure time" hideOptionalLabel>
			{({ field1Props, field2Props }) => (
				<>
					<TimePicker
						hideOptionalLabel
						label="Time"
						message="Enter a valid time"
						onChange={setTimeValue}
						value={timeValue}
						{...field1Props}
					/>
					<Select
						hideOptionalLabel
						label="Timezone"
						onChange={(e) => setTimezoneValue(e.target.value)}
						options={[
							{ value: 'AWST', label: 'AWST' },
							{ value: 'ACWST', label: 'ACWST' },
							{ value: 'ACST', label: 'ACST' },
							{ value: 'AEST', label: 'AEST' },
							{ value: 'LHST', label: 'LHST' },
						]}
						placeholder="Please select"
						value={timezoneValue}
					/>
				</>
			)}
		</GroupedFields>
	);
};

Related components

• Date picker (Next) – The Date picker component allows users to select a single date via a calendar or text input.
• Date range picker (Next) – The Date range picker component allows users to select a range of dates via a calendar or text input.
• Time input – The Time input component allows users to enter a time in multiple formats.
• Time picker – The Time picker component allows users to easily select a time from a list of options.