Date time picker

A date time picker allows the user to select an associated date and time.

Default

By default, selecting the date field opens the calendar view. The current date text is bold, underlined, and highlighted blue.

Add clearControlLabel to give the clear button an aria-label, and do not place the clear button in the tab order.

The time field is used to select a time from the select menu.

Appointment date and time

2/18/1993

1:00 PM

import React from 'react';

import DateTimePicker from '@atlaskit/datetime-picker/date-time-picker';
import { Label } from '@atlaskit/form/label/default';

const DateTimePickerDefaultExample = (): React.JSX.Element => (
	<>
		<Label htmlFor="datetime">Appointment date and time</Label>
		<DateTimePicker
			id="datetime"
			clearControlLabel="Clear default example"
			datePickerProps={{ shouldShowCalendarButton: true, label: 'Appointment date' }}
			timePickerProps={{ label: 'Appointment time' }}
		/>
	</>
);

export default DateTimePickerDefaultExample;

Form

Date time picker used with the form component includes a field label and helper text.

import React from 'react';

import Button from '@atlaskit/button/default/button';
import DateTimePicker from '@atlaskit/datetime-picker/date-time-picker';
import Form from '@atlaskit/form/form';
import Field from '@atlaskit/form/field';
import { FormFooter } from '@atlaskit/form/form-footer';

const DateTimePickerFormExample = (): React.JSX.Element => (
	<Form onSubmit={(formState: unknown) => console.log('form submitted', formState)}>
		<Field
			name="datetime-picker"
			label="Scheduled run time"
			isRequired={false}
			helperMessage="Help or instruction text goes here."
			component={({ fieldProps }) => (
				<DateTimePicker
					{...fieldProps}
					clearControlLabel="Clear scheduled run time"
					datePickerProps={{
						shouldShowCalendarButton: true,
						label: 'Scheduled run time, date',
					}}
					timePickerProps={{ label: 'Scheduled run time, time' }}
				/>
			)}
		/>
		<FormFooter>
			<Button type="submit" appearance="primary">
				Submit
			</Button>
		</FormFooter>
	</Form>
);

export default DateTimePickerFormExample;

Required

How date time picker works when the form is required.

Log Entry

2/18/1993

1:00 PM

import React from 'react';

import DateTimePicker from '@atlaskit/datetime-picker/date-time-picker';
import Field from '@atlaskit/form/field';

const DateTimePickerRequiredExample = (): React.JSX.Element => (
	<Field name="datetime" label="Log Entry" isRequired>
		{({ fieldProps: { ...rest } }) => (
			<DateTimePicker
				{...rest}
				clearControlLabel="Clear log entry"
				datePickerProps={{ shouldShowCalendarButton: true, label: 'Log entry, date' }}
				timePickerProps={{ label: 'Log entry, time' }}
			/>
		)}
	</Field>
);

export default DateTimePickerRequiredExample;

Validation

This is how date time picker behaves within forms.

Validation displays an error message related to the restrictions of the date time picker.

When a user selects the date time picker area, the focus color changes to blue.

When validating date time pickers in real-time, message icons switch based on the message type. For example, helper text becomes an error message when the input content doesn't meet the criteria. Error and warning messages disappear when the criteria is met.

Keep helper text as short as possible. For complex information, provide a link to more information in a new browser tab. Use the messaging guidelines for more help.

import React from 'react';

import Button from '@atlaskit/button/default/button';
import DateTimePicker from '@atlaskit/datetime-picker/date-time-picker';
import Form from '@atlaskit/form/form';
import Field from '@atlaskit/form/field';
import { FormFooter } from '@atlaskit/form/form-footer';

const validateField = (value?: string) => {
	if (!value) {
		return 'This field is required.';
	} else if (new Date(value) < new Date()) {
		return 'You may not enter a datetime that is in the past.';
	}
};

const DateTimePickerFormExample = (): React.JSX.Element => (
	<Form onSubmit={(formState) => console.log('form submitted', formState)}>
		<Field
			name="datetime-picker"
			label="Scheduled run time"
			validate={validateField}
			isRequired
			helperMessage="You have entered a valid datetime."
			component={({ fieldProps }) => (
				<DateTimePicker
					{...fieldProps}
					clearControlLabel="Clear scheduled run time"
					datePickerProps={{
						shouldShowCalendarButton: true,
						label: 'Scheduled run time, date',
					}}
					timePickerProps={{ label: 'Scheduled run time, time' }}
				/>
			)}
		/>
		<FormFooter>
			<Button type="submit" appearance="primary">
				Submit
			</Button>
		</FormFooter>
	</Form>
);

export default DateTimePickerFormExample;

Spacing

Use spacing to control the vertical spacing of the date time picker. The default spacing is gridSize() * 5, and compact spacing is gridSize() * 4.

Appointment date and time

2/18/1993

1:00 PM

import React from 'react';

import DateTimePicker from '@atlaskit/datetime-picker/date-time-picker';
import { Label } from '@atlaskit/form/label/default';

const DateTimePickerDefaultExample = (): React.JSX.Element => (
	<>
		<Label htmlFor="datetime">Appointment date and time</Label>
		<DateTimePicker
			id="datetime"
			clearControlLabel="Clear default example"
			spacing="compact"
			datePickerProps={{ shouldShowCalendarButton: true, label: 'Appointment date' }}
			timePickerProps={{ label: 'Appointment time' }}
		/>
	</>
);

export default DateTimePickerDefaultExample;

Disabled dates

If a certain date is not a valid selection, you may disable it in the calendar shown to users. This does not restrict the dates that a user may type, so validation is necessary.

Specific dates

Use disabled to restrict selection of individual dates.

Appointment date and time

12/15/2020

12:00 AM

import React from 'react';

import DateTimePicker from '@atlaskit/datetime-picker/date-time-picker';
import { Label } from '@atlaskit/form/label/default';

const disabledDates = [
	'2020-12-07',
	'2020-12-08',
	'2020-12-09',
	'2020-12-16',
	'2020-12-17',
	'2020-12-18',
];

const DateTimePickerDisabledExample = (): React.JSX.Element => (
	<>
		<Label htmlFor="datetime">Appointment date and time</Label>
		<DateTimePicker
			id="datetime"
			clearControlLabel="Clear disabled dates"
			datePickerProps={{
				disabled: disabledDates,
				shouldShowCalendarButton: true,
				label: 'Appointment date',
			}}
			defaultValue="2020-12-15"
			timePickerProps={{ label: 'Appointment time' }}
		/>
	</>
);

export default DateTimePickerDisabledExample;

Date ranges

Use minDate to set a minimum valid date and maxDate to set a maximum valid date. These can be used to define a valid date range.

Appointment date and time

12/15/2020

12:00 AM

import React from 'react';

import DateTimePicker from '@atlaskit/datetime-picker/date-time-picker';
import { Label } from '@atlaskit/form/label/default';

const DateTimePickerDisableRangeExample = (): React.JSX.Element => (
	<>
		<Label htmlFor="datetime">Appointment date and time</Label>
		<DateTimePicker
			id="datetime"
			clearControlLabel="Clear range"
			datePickerProps={{
				minDate: '2020-12-10',
				maxDate: '2020-12-20',
				shouldShowCalendarButton: true,
				label: 'Appointment date',
			}}
			defaultValue="2020-12-15"
			timePickerProps={{
				label: 'Appointment time',
			}}
		/>
	</>
);

export default DateTimePickerDisableRangeExample;

Complex behavior

Use disabledDateFilter for more complicated date options, like enabling only specific days of the week to be selectable.

Appointment date and time

12/15/2020

12:00 AM

import React from 'react';

// oxlint-disable-next-line @atlassian/no-restricted-imports
import { parseISO } from 'date-fns';

import DateTimePicker from '@atlaskit/datetime-picker/date-time-picker';
import { Label } from '@atlaskit/form/label/default';

const weekendFilter = (date: string) => {
	const dayOfWeek = parseISO(date).getDay();
	return dayOfWeek === 0 || dayOfWeek === 6;
};

const DateTimePickerDisableComplexExample = (): React.JSX.Element => (
	<>
		<Label htmlFor="datetime">Appointment date and time</Label>
		<DateTimePicker
			id="datetime"
			clearControlLabel="Clear complex dates"
			defaultValue="2020-12-15"
			datePickerProps={{
				disabledDateFilter: weekendFilter,
				shouldShowCalendarButton: true,
				label: 'Appointment date',
			}}
			timePickerProps={{ label: 'Appointment time' }}
		/>
	</>
);

export default DateTimePickerDisableComplexExample;

Internationalization

Date time picker supports internationalization through two props:

locale affects language, format and, parsing.
weekStartDay determines the first day of the week shown on the calendar.

Locale

Use locale to tailor UI copy to local audiences.

Date and time in US

2/18/1993

1:00 PM

Date and time in Japan

1993/2/18

13:00

import React from 'react';

import DateTimePicker from '@atlaskit/datetime-picker/date-time-picker';
import { Label } from '@atlaskit/form/label/default';
import { Box } from '@atlaskit/primitives/compiled';

const DateTimePickerLocaleExample = (): React.JSX.Element => (
	<>
		<Label htmlFor="locale-1">Date and time in US</Label>
		<DateTimePicker
			id="locale-1"
			clearControlLabel="Clear Date and time in US"
			datePickerProps={{ shouldShowCalendarButton: true, label: 'Date in US' }}
			locale={'en-US'}
			timePickerProps={{ label: 'Time in US' }}
		/>

		<Box>
			<Label htmlFor="locale-2">Date and time in Japan</Label>
			<DateTimePicker
				id="locale-2"
				clearControlLabel="Clear Date and time in Japan"
				datePickerProps={{ shouldShowCalendarButton: true, label: 'Date in Japan' }}
				locale={'ja-JP'}
				timePickerProps={{ label: 'Time in Japan' }}
			/>
		</Box>
	</>
);

export default DateTimePickerLocaleExample;

Week start day

Use weekStartDay to adjust which day of the week is shown first in the calendar. A value of 0 corresponds to Sunday (default), 1 to Monday, and so on.

Sunday example

2/18/1993

1:00 PM

Monday example

2/18/1993

1:00 PM

import React from 'react';

import DateTimePicker from '@atlaskit/datetime-picker/date-time-picker';
import { Label } from '@atlaskit/form/label/default';
import { Box } from '@atlaskit/primitives/compiled';

const DateTimePickerWeekStartDayExample = (): React.JSX.Element => (
	<>
		<Label htmlFor="datetime-1">Sunday example</Label>
		<DateTimePicker
			id="datetime-1"
			clearControlLabel="Clear Sunday example"
			datePickerProps={{
				weekStartDay: 0,
				shouldShowCalendarButton: true,
				label: 'Sunday example, date',
			}}
			timePickerProps={{ label: 'Sunday example, time' }}
		/>
		<Box>
			<Label htmlFor="datetime-2">Monday example</Label>
			<DateTimePicker
				id="datetime-2"
				clearControlLabel="Clear Monday Example"
				datePickerProps={{
					weekStartDay: 1,
					shouldShowCalendarButton: true,
					label: 'Monday example, date',
				}}
				timePickerProps={{ label: 'Monday example, time' }}
			/>
		</Box>
	</>
);

export default DateTimePickerWeekStartDayExample;

Date and time formats

Date time picker supports customizing the format of dates and times. Formats are given as strings and use the syntax specified at Modern JavaScript Date Utility Library.

dateFormat determines how dates are formatted.
timeFormat determined how times are formatted.

Where possible use locale for date and time formatting, instead of a custom format. Date and time formats should be informed by the user’s locale and the use case.

Appointment date and time

2/18/1993

1:00 PM

import React from 'react';

// oxlint-disable-next-line @atlassian/no-restricted-imports
import { parseISO } from 'date-fns';

import DateTimePicker from '@atlaskit/datetime-picker/date-time-picker';
import { Label } from '@atlaskit/form/label/default';

const DateTimePickerFormattingExample = (): React.JSX.Element => (
	<>
		<Label htmlFor="datetime">Appointment date and time</Label>
		<DateTimePicker
			id="datetime"
			clearControlLabel="Clear Appointment date and time"
			datePickerProps={{
				dateFormat: 'YYYY-MM-DD',
				placeholder: '',
				parseInputValue: (date: string) => parseISO(date),
				shouldShowCalendarButton: true,
				label: 'Appointment date',
			}}
			timePickerProps={{
				timeFormat: 'HH:mm',
				placeholder: '',
				label: 'Appointment time',
			}}
		/>
	</>
);

export default DateTimePickerFormattingExample;

Accessibility

If using fields with labels other than "Date" and "Time" for the date picker and time picker respectively, use datePickerProps and timePickerProps to pass the label prop.

Accessible clear controls

Don’t add a clear button to the tab order, as it has been intentionally removed. Being in the tab order can confuse people across multiple disability cohorts and be cumbersome for sighted people who use keyboards.

Instead, the clear control is optimized for pointer interactions, like mouse click or tap. And people using a keyboard will use the DELETE key to clear contents and CTRL+A to select all.

import React from 'react';

import Button from '@atlaskit/button/default/button';
import DateTimePicker from '@atlaskit/datetime-picker/date-time-picker';
import Form from '@atlaskit/form/form';
import Field from '@atlaskit/form/field';
import { FormFooter } from '@atlaskit/form/form-footer';

const DateTimePickerFormAccessibleExample = (): React.JSX.Element => (
	<Form onSubmit={(formState: unknown) => console.log('form submitted', formState)}>
		<Field name="datetime-picker-accessible" label="Scheduled run time" isRequired>
			{({ fieldProps }) => (
				<DateTimePicker
					{...fieldProps}
					datePickerProps={{
						label: 'Scheduled run time, date',
						shouldShowCalendarButton: true,
					}}
					timePickerProps={{ label: 'Scheduled run time, time' }}
					clearControlLabel="Clear scheduled run time"
				/>
			)}
		</Field>
		<FormFooter>
			<Button type="submit" appearance="primary">
				Submit
			</Button>
		</FormFooter>
	</Form>
);

export default DateTimePickerFormAccessibleExample;

Was this page helpful?

We use this feedback to improve our documentation.