Calendar

An interactive calendar for date selection experiences.

Neutral selected states

When the platform-dst-tokens-finesse feature flag is enabled, this component uses the new neutral treatment for selected states.

Examples Code Usage Changelog

Installation

Package installation information
Install	`yarn add @atlaskit/calendar`
Source	Bitbucket.org, (opens new window)
npm	@atlaskit/calendar, (opens new window)
Bundle	unpkg.com, (opens new window)

Props

`analyticsContext`
Description	Additional information to be included in the `context` of analytics events.
Type	`{ [x: string]: any; }`

`className`
Description	Class name to apply to the calendar.
Type	`string`

`createAnalyticsEvent`
Description	You should not be accessing this prop under any circumstances. It is provided by `@atlaskit/analytics-next` and integrated in the component
Type	`(payload: AnalyticsEventPayload) => UIAnalyticsEvent`

`day`
Description	The number of the day currently focused. Places border around the date. Enter `0` to highlight no date.
Type	`number`

`defaultDay`
Description	Sets the default value for `day`.
Type	`number`

`defaultMonth`
Description	Sets the default value for `month`.
Type	`number`

`defaultPreviouslySelected`
Description	Sets the default value for `previouslySelected`.
Type	`string[]`

`defaultSelected`
Description	Sets the default value for `selected`.
Type	`string[]`

`defaultYear`
Description	Sets the default value for `year`.
Type	`number`

`disabled`
Description	Takes an array of dates as string in the format 'YYYY-MM-DD'. All dates provided are greyed out and not selectable.
Type	`string[]`

`disabledDateFilter`
Description	A filter function that takes a date string in the format 'YYYY-MM-DD' and returns true if that date should be disabled.
Type	`(date: string) => boolean`

`locale`
Description	BCP 47 language tag (e.g. `ja-JP`) that ensures dates are in the official format for the locale.
Type	`string`

`maxDate`
Description	The latest enabled date. All dates in the future after this date will be disabled.
Type	`string`

`minDate`
Description	The earliest enabled date. All dates in the past before this date will be disabled.
Type	`string`

`month`
Description	The number of the month (from 1 to 12) which the calendar should be on.
Type	`number`

`nextMonthLabel`
Description	The aria-label attribute associated with the next month arrow, to describe it to assistive technology.
Type	`string`

`onBlur`
Description	Function which is called when the calendar is no longer focused.
Type	`(event: FocusEvent<Element, Element>) => void`

`onChange`
Description	Called when the calendar is navigated. This can be triggered by the keyboard, or by clicking the navigational buttons. The 'interface' property indicates the the direction the calendar was navigated whereas the 'iso' property is a string of the format YYYY-MM-DD.
Type	`(event: ChangeEvent, analyticsEvent: UIAnalyticsEvent) => void`

`onFocus`
Description	Called when the calendar receives focus. This could be called from a mouse event on the container, or by tabbing into it.
Type	`(event: FocusEvent<Element, Element>) => void`

`onSelect`
Description	Function called when a day is clicked on. Calls with an object that has a day, month and year property as numbers, representing the date just clicked. It also has an 'iso' property, which is a string of the selected date in the format YYYY-MM-DD.
Type	`(event: SelectEvent, analyticsEvent: UIAnalyticsEvent) => void`

`previouslySelected`
Description	Takes an array of dates as string in the format 'YYYY-MM-DD'. All dates provided are given a background color.
Type	`string[]`

`previousMonthLabel`
Description	The aria-label attribute associated with the previous month arrow, to describe it to assistive technology.
Type	`string`

`ref`
Description	No description.
Type	`((instance: HTMLDivElement) => void) \| RefObject<HTMLDivElement>`

`selected`
Description	Takes an array of dates as string in the format 'YYYY-MM-DD'. All dates provided are given a background color.
Type	`string[]`

`shouldSetFocusOnCurrentDay`
Description	This allows the calendar to automatically set the focus to the current day. The default is false.
Type	`boolean`

`style`
Description	Style customization to apply to the calendar.
Type	`CSSProperties`

`tabIndex`
Description	Indicates if the calendar can be focused by keyboard or only programmatically. Defaults to "0".
Type	`0 \| -1`

`testId`
Description	A `testId` prop is provided for specified elements, which is a unique string that appears as a data attribute `data-testid` in the rendered code, serving as a hook for automated tests testId--container - Outermost container containing everything inside calendar testId--month - Container containing all available days for the month testId--previous-month - Button to show next month testId--next-month - Button to show previous month testId--current-month-year - Text containing the current month and year testId--selected-day - The currently selected day (may be missing if a date isn’t selected)
Type	`string`

`today`
Description	Value of current day, as a string in the format 'YYYY-MM-DD'.
Type	`string`

`weekStartDay`
Description	Start day of the week for the calendar. The mapping between numbers and days of the week is as follows: `0` Sunday `1` Monday `2` Tuesday `3` Wednesday `4` Thursday `5` Friday `6` Saturday Defaults to the first day of the week for the given `locale` when `platform-dst-locale-week-start-day` is enabled. Otherwise defaults to Sunday (`0`).
Type	`0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6`

`year`
Description	Year to display the calendar for.
Type	`number`

Was this page helpful?

We use this feedback to improve our documentation.