Calendar

a calendar of days displayed by month

Props

a11yTitle

Custom label to be used by screen readers. When provided, an aria-label will be added to the element.

string

"a user friendly label for screen readers"

activeDate

When using range, Whether the next date selection will affect the start or end bound of the range.

string

"start"

"end"

alignSelf

How to align along the cross axis when contained in a Box or along the column axis when contained in a Grid.

string

"start"

"center"

"end"

"stretch"

"baseline"

animate

Whether to animate the calender as the user interacts with it.

boolean

true

false

bounds

An array of two numbers indicating the limits on navigation in ISO8601 format.

array

["2018-09-01", "2018-12-31"]

children

Function that will be called to render each day.

function

'date' is a string containing an ISO8601 date for the day being rendered. 'day' is a number containing the day of the month being rendered. 'isInRange' is a boolean indicating whether the date is within a selected range of dates. 'isSelected' is a boolean indicating whether this date is selected.

({ date, day, isInRange, isSelected }) => {}

date

The selected date or array of dates in ISO8601 format.

string

"2018-10-16T12:22:00Z"

array

["2018-10-12", "2018-10-17"]

dates

Multiple selected dates in ISO8601 format.

array["string"]

["2018-10-12", "2018-10-17"]

array[array["string"]]

Items that are an array indicate a range of dates.

[["2018-10-19", "2018-11-23"]]

daysOfWeek

Whether to show the days of the week.

boolean

true

false

disabled

Multiple dates in ISO8601 format that should not be selectable.

array["string"]

["2018-09-21", "2018-09-27"]

array[array["string"]]

Items that are an array indicate a range of dates.

[["2018-12-23", "2018-12-26"]]

fill

Whether the calendar should fill the parent container.

boolean

true

false

firstDayOfWeek

The first day of the week.

number

0 for Sunday. 1 for Monday.

gridArea

The name of the area to place this inside a parent Grid.

string

"a parent grid area name"

header

If specified, the entire calendar header will be managed by the caller.

function

'onPreviousMonth' and 'onNextMonth' are callbacks that will tell the calendar to move between months. 'previousInBound' and 'nextInBound' are booleans that tell, when using 'bounds', if the current date is within that range. You can then use that to disable the previous and next buttons.


({
  date: Date,
  locale: "en-US",
  onPreviousMonth: func,
  onNextMonth: func,
  previousInBound: bool,
  nextInBound: bool,
}) => {}

level

The heading level in Calendar. It corresponds to the number after the 'H' for the DOM tag. Set the level for semantic accuracy and accessibility.

string

"1"

"2"

"3"

"4"

"5"

"6"

number

locale

The locale to use.

string

"en-US"

margin

The amount of margin around the component.

string

"none"

"xxsmall"

"xsmall"

"small"

"medium"

"large"

"xlarge"

object

Can be specified to distinguish horizontal margin, vertical margin, and margin on a particular side.


{
    vertical: "...",
    horizontal: "...",
    top: "...",
    bottom: "...",
    left: "...",
    right: "..."
}

messages

Custom messages for Calendar. Used for internationalization and customization of default strings and accessibility announcements. readers.

string


({
  previous: "Moved to {date}",
  next: "Moved to {date}",
})

onReference

Called with an ISO8601 date when the user navigates to a different month.

function

('2018-10-22T12:22:00Z') => {}

onSelect

Called with an ISO8601 date when the user selects a day. For single select, make this the subsequent 'date' property value. For multiple select or ranges, toggle values in 'dates'. Not specifying this property makes the component read only.

function

('2018-10-22T12:22:00Z') => {}

range

Whether to automatically manage multiple date selection as a range. When the user clicks the first date, onSelect will be called with that date. When the user selects another date, onSelect will be called with an array of two dates.

boolean

true

false

string

If range = "array", then an array of dates will be returned even when the start or end date of the range is undefined.

"array"

reference

The date to show if 'date' isn't set, in ISO8601 format.

string

"2018-10-12"

showAdjacentDays

Whether to show the days from the previous and next months.

boolean

true

false

string

'trim' limits adjacent days shown to rows containing days in the current month.

"trim"

size

What size to make it.

string

T-shirt sizing based off the theme or a specific size in px, em, etc.

"small"

"medium"

"large"

"string"

React/DOM Properties

At its core, the Calendar component is a regular <div> element. Thus, both DOM and React properties, methods, and events are accessible. To read up on all of the possible DOM attributes and types available for div elements, check out this MDN Web Documents page. To learn more about DOM events and methods, you can read more on the MDN Web Events documentation page.

Also, feel free to read about the types of React events available, or see how DOM attributes change in React. Working in tandem with Styled Components, you also have access to the as property.

Theme

calendar.day.adjacent.color

The text color to use for dates that are outside of the current month.

string

A hex, name, or rgb value.

"text-xweak"

object

An object with a color for dark and light modes.

{ dark: "light-4", light: "dark-3" }

calendar.day.hover

Any additional background and color hover style for the Calendar day.

string

A hex, name, or rgb value.

"brand"

object

An object with a color for dark and light modes.

{ dark: "light-4", light: "dark-3" }

calendar.day.selected

Any additional background and color selected style for the Calendar day.

string

A hex, name, or rgb value.

"brand"

object

An object with a color for dark and light modes.

{ dark: "light-4", light: "dark-3" }

calendar.day.selected.font.weight

Font weight for the selected date.

string

Any browser font-weight definition.

"normal"

"bold"

number

calendar.day.selected.hover

Any additional background and color hover style for the selected Calendar day.

string

A hex, name, or rgb value.

"brand"

object

An object with a color for dark and light modes.

{ dark: "light-4", light: "dark-3" }

calendar.day.inRange.color

Any additional color style for the day in range of Calendar.

string

A hex, name, or rgb value.

"brand"

calendar.day.inRange.font.weight

Font weight for the days in range.

string

Any browser font-weight definition.

"normal"

"bold"

number

calendar.day.inRange.hover

Any additional background and color hover style for the days in range.

string

A hex, name, or rgb value.

"brand"

object

An object with a color for dark and light modes.

{ dark: "light-4", light: "dark-3" }

calendar.day.extend

Any additional style for the day of Calendar.

string

Any CSS.

css`color: 'blue'`

function

(props) => {}

calendar.extend

Any additional style for the Calendar.

string

Any CSS.

css`color: 'blue'`

function

(props) => {}

calendar.heading.level

The calendar[size].title should be used in place of this heading level used for the calendar.

number

calendar.icons.next

The icon to use for the next month navigation control.

element

<Next />

calendar.icons.previous

The icon to use for the previous month navigation control.

element

<Previous />

calendar.icons.small.next

The icon to use for the next month navigation control when small.

element

<FormNext />

calendar.icons.small.previous

The icon to use for the previous month navigation control when small.

element

<FormPrevious />

calendar.large.daySize

The size of a day when large.

string

"109.7px"

calendar.large.fontSize

The font size to use for days when large.

string

"30px"

calendar.large.lineHeight

The line height to use for days when large.

number

1.11

calendar.large.slideDuration

How long it animate the slide between months when large.

string

"0.8s"

calendar.large.title

Any valid Text prop for the calendar text heading when large.

object

{}

calendar.medium.daySize

The size of a day when medium.

string

"54.84px"

calendar.medium.fontSize

The font size to use for days when medium.

string

"18px"

calendar.medium.lineHeight

The line height to use for days when medium.

number

1.45

calendar.medium.slideDuration

How long it animate the slide between months when medium.

string

"0.5s"

calendar.medium.title

Any valid Text prop for the calendar text heading when medium.

object

{}

calendar.small.day.round

The amount to round the corner of a day when small.

boolean

true

false

string

"xsmall"

"small"

"medium"

"large"

"xlarge"

"full"

"any CSS size"

object

{ size: "...", corner: "..." }

where corner could be:

"top"

"left"

"bottom"

"right"

"top-left"

"top-right"

"bottom-left"

"bottom-right"

calendar.small.range.round

The amount to round the corner of a day in range when small.

boolean

true

false

string

"xsmall"

"small"

"medium"

"large"

"xlarge"

"full"

"any CSS size"

object

{ size: "...", corner: "..." }

where corner could be:

"top"

"left"

"bottom"

"right"

"top-left"

"top-right"

"bottom-left"

"bottom-right"

calendar.small.range.round.start

The amount to round the corner of a day in range when small.

boolean

true

false

string

"xsmall"

"small"

"medium"

"large"

"xlarge"

"full"

"any CSS size"

object

{ size: "...", corner: "..." }

where corner could be:

"top"

"left"

"bottom"

"right"

"top-left"

"top-right"

"bottom-left"

"bottom-right"

calendar.small.range.round.end

The amount to round the corner of a day in range when small.

boolean

true

false

string

"xsmall"

"small"

"medium"

"large"

"xlarge"

"full"

"any CSS size"

object

{ size: "...", corner: "..." }

where corner could be:

"top"

"left"

"bottom"

"right"

"top-left"

"top-right"

"bottom-left"

"bottom-right"

calendar.small.daySize

The size of a day when small.

string

"27.42px"

calendar.small.fontSize

The font size to use for days when small.

string

"14px"

calendar.small.lineHeight

The line height to use for days when small.

number

1.375

calendar.small.slideDuration

How long it animate the slide between months when small.

string

"0.2s"

calendar.small.title

Any valid Text prop for the calendar text heading when small.

object

{}

global.size.small

The width of the calendar when small.

string

"192px"

global.size.medium

The width of the calendar when medium.

string

"384px"

calendar.medium.day.round

The amount to round the corner of a day when medium.

boolean

true

false

string

"xsmall"

"small"

"medium"

"large"

"xlarge"

"full"

"any CSS size"

object

{ size: "...", corner: "..." }

where corner could be:

"top"

"left"

"bottom"

"right"

"top-left"

"top-right"

"bottom-left"

"bottom-right"

calendar.medium.range.round

The amount to round the corner of a day in range when medium.

boolean

true

false

string

"xsmall"

"small"

"medium"

"large"

"xlarge"

"full"

"any CSS size"

object

{ size: "...", corner: "..." }

where corner could be:

"top"

"left"

"bottom"

"right"

"top-left"

"top-right"

"bottom-left"

"bottom-right"

calendar.medium.range.round.start

The amount to round the corner of a day in range when medium.

boolean

true

false

string

"xsmall"

"small"

"medium"

"large"

"xlarge"

"full"

"any CSS size"

object

{ size: "...", corner: "..." }

where corner could be:

"top"

"left"

"bottom"

"right"

"top-left"

"top-right"

"bottom-left"

"bottom-right"

calendar.medium.range.round.end

The amount to round the corner of a day in range when medium.

boolean

true

false

string

"xsmall"

"small"

"medium"

"large"

"xlarge"

"full"

"any CSS size"

object

{ size: "...", corner: "..." }

where corner could be:

"top"

"left"

"bottom"

"right"

"top-left"

"top-right"

"bottom-left"

"bottom-right"

global.size.large

The width of the calendar when large.

string

"768px"

calendar.large.day.round

The amount to round the corner of a day when large.

boolean

true

false

string

"xsmall"

"small"

"medium"

"large"

"xlarge"

"full"

"any CSS size"

object

{ size: "...", corner: "..." }

where corner could be:

"top"

"left"

"bottom"

"right"

"top-left"

"top-right"

"bottom-left"

"bottom-right"

calendar.large.range.round

The amount to round the corner of a day in range when large.

boolean

true

false

string

"xsmall"

"small"

"medium"

"large"

"xlarge"

"full"

"any CSS size"

object

{ size: "...", corner: "..." }

where corner could be:

"top"

"left"

"bottom"

"right"

"top-left"

"top-right"

"bottom-left"

"bottom-right"

calendar.large.range.round.start

The amount to round the corner of a day in range when large.

boolean

true

false

string

"xsmall"

"small"

"medium"

"large"

"xlarge"

"full"

"any CSS size"

object

{ size: "...", corner: "..." }

where corner could be:

"top"

"left"

"bottom"

"right"

"top-left"

"top-right"

"bottom-left"

"bottom-right"

calendar.large.range.round.end

The amount to round the corner of a day in range when large.

boolean

true

false

string

"xsmall"

"small"

"medium"

"large"

"xlarge"

"full"

"any CSS size"

object

{ size: "...", corner: "..." }

where corner could be:

"top"

"left"

"bottom"

"right"

"top-left"

"top-right"

"bottom-left"

"bottom-right"

global.colors.icon

The color of a given icon.

string

A hex, name, or rgb value.

"black"

object

An object with a color for dark and light modes.

{ dark: #f8f8f8, light: #666666 }

global.edgeSize

The possible sizes for margin.

object


    {
      none: '0px',
      hair: '1px',
      xxsmall: '3px',
      xsmall: '6px',
      small: '12px',
      medium: '24px',
      large: '48px',
      xlarge: '96px',
      responsiveBreakpoint: 'small'
    }