Date picker

A date picker allows the user to select a particular date.

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.

Choose date

2/18/1993

import React from 'react';

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

const DatePickerDefaultExample = (): React.JSX.Element => (
	<>
		<Label id="date" htmlFor="default-date-picker-example">
			Choose date
		</Label>
		<DatePicker
			id="default-date-picker-example"
			clearControlLabel="Clear choose date"
			shouldShowCalendarButton
			inputLabelId="date"
			openCalendarLabel="open calendar"
		/>
	</>
);

export default DatePickerDefaultExample;

Form

When using the date picker with the form component, include a field label and helper text. For more information, see the form component.

import React from 'react';

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

const DatePickerFormExample = (): React.JSX.Element => (
	<Form onSubmit={(formState: unknown) => console.log('form submitted', formState)}>
		<Field
			name="datepicker-form"
			label="Start date"
			isRequired={false}
			defaultValue=""
			helperMessage="Help or instruction text goes here"
			component={({ fieldProps }) => (
				<DatePicker
					{...fieldProps}
					clearControlLabel="Clear start date"
					shouldShowCalendarButton
					inputLabel="Start date"
					openCalendarLabel="open calendar"
				/>
			)}
		/>
		<FormFooter>
			<Button type="submit" appearance="primary">
				Submit
			</Button>
		</FormFooter>
	</Form>
);

export default DatePickerFormExample;

Required

How date picker works when the form is required.

Start Date

2/18/1993

import React from 'react';

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

const DatePickerRequiredExample = (): React.JSX.Element => (
	<Field
		name="date"
		label="Start Date"
		isRequired
		component={({ fieldProps: { ...rest } }) => (
			<DatePicker shouldShowCalendarButton clearControlLabel="Clear start date" {...rest} />
		)}
	/>
);

export default DatePickerRequiredExample;

Validation

This is how date picker behaves within forms.

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

When a user selects the date picker area, the focus color changes to blue. When validating date 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 DatePicker from '@atlaskit/datetime-picker/date-picker';
import Field from '@atlaskit/form/field';
import Form from '@atlaskit/form/form';
import { FormFooter } from '@atlaskit/form/form-footer';

const validateField = (value?: string) => {
	if (!value) {
		return 'This field is required.';
	}
};

const DatePickerValidationExample = (): React.JSX.Element => (
	<Form onSubmit={(formState) => console.log('form submitted', formState)}>
		<Field
			name="datepicker-validation"
			label="Start day"
			validate={validateField}
			isRequired
			defaultValue=""
			helperMessage="You have entered a valid date."
			component={({ fieldProps }) => (
				<DatePicker
					{...fieldProps}
					clearControlLabel="Clear start day"
					shouldShowCalendarButton
					inputLabel="Start day"
					openCalendarLabel="open calendar"
				/>
			)}
		/>
		<FormFooter>
			<Button type="submit" appearance="primary">
				Submit
			</Button>
		</FormFooter>
	</Form>
);

export default DatePickerValidationExample;

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.

Disabled Dates

12/15/2020

import React from 'react';

import DatePicker from '@atlaskit/datetime-picker/date-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 DatePickerDisabledExample = (): React.JSX.Element => (
	<>
		<Label id="disabled" htmlFor="datepicker-disabled">
			Disabled Dates
		</Label>
		<DatePicker
			defaultValue="2020-12-15"
			disabled={disabledDates}
			id="datepicker-disabled"
			clearControlLabel="Clear disabled dates"
			shouldShowCalendarButton
			inputLabelId="disabled"
			openCalendarLabel="open calendar"
		/>
	</>
);

export default DatePickerDisabledExample;

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.

Disabled Date Range

12/15/2020

import React from 'react';

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

const DatePickerDisableRangeExample = (): React.JSX.Element => (
	<>
		<Label id="disabled" htmlFor="datepicker-disabled-range">
			Disabled Date Range
		</Label>
		<DatePicker
			defaultValue="2020-12-15"
			minDate="2020-12-10"
			maxDate="2020-12-20"
			id="datepicker-disabled-range"
			clearControlLabel="Clear disabled date range"
			shouldShowCalendarButton
			inputLabelId="disabled"
			openCalendarLabel="open calendar"
		/>
	</>
);

export default DatePickerDisableRangeExample;

Complex behavior

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

Disabled Dates (Complex)

12/15/2020

import React from 'react';

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

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

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

const DatePickerDisableComplexExample = (): React.JSX.Element => (
	<>
		<Label id="disabled" htmlFor="datepicker-disable-complex">
			Disabled Dates (Complex)
		</Label>
		<DatePicker
			defaultValue="2020-12-15"
			disabledDateFilter={weekendFilter}
			id="datepicker-disable-complex"
			clearControlLabel="Clear disabled dates (complex)"
			shouldShowCalendarButton
			inputLabelId="disabled"
			openCalendarLabel="open calendar"
		/>
	</>
);

export default DatePickerDisableComplexExample;

Internationalization

DatePicker 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.

English Language Example

2/18/1993

Japanese Language Example

1993/2/18

import React from 'react';

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

const DatePickerLocaleExample = (): React.JSX.Element => (
	<>
		<Label id="english" htmlFor="datepicker-locale-en">
			English Language Example
		</Label>
		<DatePicker
			locale={'en-US'}
			id="datepicker-locale-en"
			clearControlLabel="Clear English language example"
			shouldShowCalendarButton
			inputLabelId="english"
			openCalendarLabel="open calendar"
		/>
		<br />
		<Label id="japanese" htmlFor="datepicker-locale-jp">
			Japanese Language Example
		</Label>
		<DatePicker
			locale={'ja-JP'}
			id="datepicker-locale-jp"
			clearControlLabel="Clear Japanese language example"
			shouldShowCalendarButton
			inputLabelId="japanese"
			openCalendarLabel="open calendar"
		/>
	</>
);

export default DatePickerLocaleExample;

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.

Week Starting on Sunday

2/18/1993

Week Starting on Monday

2/18/1993

import React from 'react';

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

const DatePickerWeekStartDayExample = (): React.JSX.Element => (
	<>
		<Label id="sunday" htmlFor="datepicker-sunday">
			Week Starting on Sunday
		</Label>
		<DatePicker
			weekStartDay={0}
			id="datepicker-sunday"
			clearControlLabel="Clear week starting on Sunday"
			shouldShowCalendarButton
			inputLabelId="sunday"
			openCalendarLabel="open calendar"
		/>
		<br />
		<Label id="monday" htmlFor="datepicker-monday">
			Week Starting on Monday
		</Label>
		<DatePicker
			weekStartDay={1}
			id="datepicker-monday"
			clearControlLabel="Clear week starting on Monday"
			shouldShowCalendarButton
			inputLabelId="monday"
			openCalendarLabel="open calendar"
		/>
	</>
);

export default DatePickerWeekStartDayExample;

Date formats

You can customize the date format using the dateFormat prop. Formats are given as strings and use the syntax specified at Modern JavaScript date utility library, (opens new window).

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

Custom Date Format

2021-06-10

import React from 'react';

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

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

const DatePickerFormattingExample = (): React.JSX.Element => (
	<>
		<Label id="custom" htmlFor="datepicker-format">
			Custom Date Format
		</Label>
		<DatePicker
			dateFormat="YYYY-MM-DD"
			placeholder="2021-06-10"
			parseInputValue={(date: string) => parseISO(date)}
			id="datepicker-format"
			clearControlLabel="Clear Custom Date Format"
			shouldShowCalendarButton
			inputLabelId="custom"
			openCalendarLabel="open calendar"
		/>
	</>
);

export default DatePickerFormattingExample;

Was this page helpful?

We use this feedback to improve our documentation.