Calendar

0.1.0

Features Section titled Features

Supports single, multiple and range selection
Full keyboard navigation
Focus management of the calendar cells

Installation Section titled Installation

npm install @corvu/calendar

The calendar is also included in the main corvu package under corvu/calendar.

Usage Section titled Usage

import Calendar from '@corvu/calendar' // 'corvu/calendar'
// or
// import { Root, Nav, ... } from '@corvu/calendar'

Anatomy Section titled Anatomy

<Calendar>
  <Calendar.Nav action="prev-month" />
  <Calendar.Label />
  <Calendar.Nav action="next-month" />
  <Calendar.Table>
    <thead>
      <tr>
        <Index each={props.weekdays}>
          {(weekday) => (
            <Calendar.HeadCell />
          )}
        </Index>
      </tr>
    </thead>
    <tbody>
      <Index each={props.weeks}>
        {(week) => (
          <tr>
            <Index each={week()}>
                {(day) => (
                  <Calendar.Cell day={day()}>
                    <Calendar.CellTrigger day={day()} />
                  </Calendar.Cell>
                )}
              </Index>
            </tr>
          )}
      </Index>
    </tbody>
  </Calendar.Table>
</Calendar>

Philosophy Section titled Philosophy

This calendar is designed to be simple and lightweight. It handles functionality and accessibility to cover the common use cases but leaves things like internationalization and more individual behavior up to the user to implement. If you feel like a crucial functionality or feature is missing that is difficult or impossible to implement in userland, feel free to open an issue in the corvu Github repository.

Usage with SSR/SSG Section titled Usage with SSR/SSG

It is important to be aware of potential hydration mismatches when rendering the calendar on the server.

Make sure to set initialFocusedDay and initialMonth manually to avoid using new Date() as default, as this can lead to hydration errors due to different timezones (or even due to the delay between server and client).

Examples Section titled Examples

Range selection Section titled Range selection

Use mode="range" to set the selection mode to range. By defining numberOfMonths={2} we can display two months at once:

Disabling dates Section titled Disabling dates

You can disable specific dates by passing a callback to the disabled prop. This function receives the date as an argument and should return a boolean.

This function is reactive, meaning you can access signals and it will update the calendar when any of it’s dependencies change.

<Calendar
  // Disable weekends
  disabled={(date) => date.getDay() === 0 || date.getDay() === 6}
/>

Date Picker Section titled Date Picker

We can combine the calendar with the Popover primitive to create a date picker:

Accessibility Section titled Accessibility

Adheres to the calendar part of the Date Picker Dialog WAI-ARIA design pattern.

Accessible nav buttons Section titled Accessible nav buttons

Make sure to describe the purpose of the navigation buttons using the aria-label attribute if they only contain non-text elements:

<Calendar.Nav
  action="prev-month"
  aria-label="Go to previous month"
>
  <CaretLeft size="18" />
</Calendar.Nav>

Key	Behavior
`Space`	Selects the focused day.
`Enter`	Selects the focused day.
`ArrowRight`	Moves focus to the previous day.
`ArrowLeft`	Moves focus to the next day.
`ArrowUp`	Moves focus to the same day of the previous week.
`ArrowDown`	Moves focus to the same day of the next week.
`Home`	Moves focus to the first day of the week.
`End`	Moves focus to the last day of the week.
`PageUp`	Moves focus to the same day of the previous month.
`PageDown`	Moves focus to the same day of the next month.
`Shift + PageUp`	Moves focus to the same day of the previous year.
`Shift + PageDown`	Moves focus to the same day of the next year.

API reference Section titled API reference

<Root />

Component

Context wrapper for the calendar. Is required for every calendar you create.

Props

Property	Default	Type/Description
mode	-	'single' \| 'multiple' \| 'range' The mode of the calendar.
value	-	Date \| null \| Date[] \| { from: Date \| null, to: Date \| null, } The value of the calendar.
onValueChange	-	(value: Date \| null) => void \| (value: Date[]) => void \| (value: { from: Date \| null, to: Date \| null, }) => void Callback fired when the value changes.
initialValue	`null`	Date \| null \| Date[] \| { from: Date \| null, to: Date \| null, } The initial value of the calendar.
month	-	Date The month to display in the calendar. Is always the first month if multiple months are displayed.
onMonthChange	-	(month: Date) => void Callback fired when the month changes.
initialMonth	`new Date()`	Date The initial month to display in the calendar.
focusedDay	-	Date The day that is currently focused in the calendar grid.
onFocusedDayChange	-	(focusedDay: Date) => void Callback fired when the focused day changes.
initialFocusedDay	`new Date()`	Date The initial date that should be focused in the calendar grid.
startOfWeek	`1`	number The first day of the week. (0-6, 0 is Sunday)
required	`false`	boolean Whether the value is required. Prevents unselecting the value.
disabled	-	(day: Date) => boolean Callback to determine if any given day is disabled.
numberOfMonths	`1`	number The number of months to display in the calendar.
disableOutsideDays	`true`	boolean Whether to disable outside days (Days falling in the previous or next month).
fixedWeeks	`false`	boolean Whether to always display 6 weeks in a month.
textDirection	`ltr`	'ltr' \| 'rtl' The text direction of the calendar.
min	`null`	number \| null The minimum number of days that have to be selected.
max	`null`	number \| null The maximum number of days that can be selected.
excludeDisabled	`false`	boolean Whether to reset the range selection if a disabled day is included in the range.
labelIds	`createUniqueId()`	string[] The `id` attribute of the calendar label element(s). There can be multiple labels for each month that is being displayed.
contextId	-	string The `id` of the calendar context. Useful if you have nested calendars and want to create components that belong to a calendar higher up in the tree.

<Label />

Component

Label element to announce the calendar to accessibility tools.

Props

Property	Default	Type/Description
index	-	number The index of the calendar table that this label is describing. Is optional as it's not required if only one month is rendered.
as	`h2`	ValidComponent Component to render the dynamic component as.
contextId	-	string The `id` of the calendar context to use.

Data attributes

Data attributes present on <Label /> components.

Property	Description
data-corvu-calendar-label	Present on every calendar label element.

<Nav />

Component

Button to navigate the calendar.

Props

Property	Default	Type/Description
action	-	`${'prev' \| 'next'}-${'month' \| 'year'}` \| (date: Date) => Date The action to perform when pressing this navigation button.
as	`button`	ValidComponent Component to render the dynamic component as.
contextId	-	string The `id` of the calendar context to use.

Data attributes

Data attributes present on <Nav /> components.

Property	Description
data-corvu-calendar-nav	Present on every calendar nav element.

<Table />

Component

Table element for the calendar grid.

Props

Property	Default	Type/Description
index	-	number The index of this calendar table. Is optional as it's not required if only one month is rendered.
as	`table`	ValidComponent Component to render the dynamic component as.
contextId	-	string The `id` of the calendar context to use.

Data attributes

Data attributes present on <Table /> components.

Property	Description
data-corvu-calendar-table	Present on every calendar table element.

<HeadCell />

Component

Calendar column header cell.

Props

Property	Default	Type/Description
as	`th`	ValidComponent Component to render the dynamic component as.

Data attributes

Data attributes present on <HeadCell /> components.

Property	Description
data-corvu-calendar-headcell	Present on every calendar headcell element.

<Cell />

Component

Calendar cell element.

Props

Property	Default	Type/Description
as	`td`	ValidComponent Component to render the dynamic component as.

Data attributes

Data attributes present on <Cell /> components.

Property	Description
data-corvu-calendar-cell	Present on every calendar cell element.

<CellTrigger />

Component

Button that selectes a day in the calendar.

Props

Property	Default	Type/Description
day	-	Date
month	-	Date The month that this cell trigger belongs to. Is optional as it's not required if only one month is rendered.
as	`button`	ValidComponent Component to render the dynamic component as.
contextId	-	string The `id` of the calendar context to use.

Data attributes

Data attributes present on <CellTrigger /> components.

Property	Description
data-selected	Present on selected calendar cell triggers.
data-disabled	Present on disabled calendar cell triggers.
data-today	Present on today's calendar cell trigger. Only rendered on the client to avoid hydration mismatches
data-range-start	Present on the start of a day range. (Only present in range mode)
data-range-end	Present on the end of a day range. (Only present in range mode)
data-in-range	Present on calendar cell trigger elements that are within a day range. (Including start and end, only present in range mode)
data-corvu-calendar-celltrigger	Present on every calendar celltrigger element.

useContext

Context

Context which exposes various properties to interact with the calendar. Optionally provide a contextId to access a keyed context.

Returns

Property	Type/Description
mode	Accessor<'single'> \| Accessor<'multiple'> \| Accessor<'range'> The mode of the calendar.
value	Accessor<Date \| null> \| Accessor<Date[]> \| Accessor<{ from: Date \| null, to: Date \| null, }> The value of the calendar.
setValue	Setter<Date \| null> \| Setter<Date[]> \| Setter<{ from: Date \| null, to: Date \| null, }> Setter to change the value of the calendar.
month	Accessor<Date> The month to display in the calendar. Is always the first month if multiple months are displayed.
setMonth	Setter<Date> Setter to change the month to display in the calendar. Automatically adjusts the focusedDay to be within the visible range.
focusedDay	Accessor<Date> The day that is currently focused in the calendar grid.
setFocusedDay	Setter<Date> Setter to change the focused day in the calendar grid. Automatically adjusts the month to ensure the focused day is visible.
startOfWeek	Accessor<number> The first day of the week. (0-6, 0 is Sunday)
required	Accessor<boolean> Whether the value is required. Prevents unselecting the value.
numberOfMonths	Accessor<number> The number of months to display in the calendar.
disableOutsideDays	Accessor<boolean> Whether to disable outside days (Days falling in the previous or next month).
fixedWeeks	Accessor<boolean> Whether to always display 6 weeks in a month.
textDirection	Accessor<'ltr' \| 'rtl'> The text direction of the calendar.
weekdays	Accessor<Date[]> Array of weekdays starting from the first day of the week.
months	Accessor<{ month: Date, weeks: Date[][], }[]> Array of the currently displayed months.
weeks	Accessor<Date[][]> Function to get the weeks of the current month. Useful if only one month is being rendered.
navigate	(action: `${'prev' \| 'next'}-${'month' \| 'year'}` \| (date: Date) => Date) => void Function to navigate the calendar.
min	Accessor<number \| null> The minimum number of days that have to be selected.
max	Accessor<number \| null> The maximum number of days that can be selected.
excludeDisabled	Accessor<boolean> Whether to reset the range selection if a disabled day is included in the range.
labelIds	Accessor<Accessor<string \| undefined>[]> The `id` attributes of the calendar label elements. Can be undefined if no `Calendar.Label` is present for the given month index.

RootChildrenProps

Type

Props that are passed to the Root component children callback.

Props

Property	Type/Description
mode	'single' \| 'multiple' \| 'range' The mode of the calendar.
value	Date \| null \| Date[] \| { from: Date \| null, to: Date \| null, } The value of the calendar.
setValue	Setter<Date \| null> \| Setter<Date[]> \| Setter<{ from: Date \| null, to: Date \| null, }> Setter to change the value of the calendar.
month	Date The month to display in the calendar. Is always the first month if multiple months are displayed.
setMonth	Setter<Date> Setter to change the month to display in the calendar. Automatically adjusts the focusedDay to be within the visible range.
focusedDay	Date The day that is currently focused in the calendar grid.
setFocusedDay	Setter<Date> Setter to change the focused day in the calendar grid. Automatically adjusts the month to ensure the focused day is visible.
startOfWeek	number The first day of the week. (0-6, 0 is Sunday)
required	boolean Whether the value is required. Prevents unselecting the value.
numberOfMonths	number The number of months to display in the calendar.
disableOutsideDays	boolean Whether to disable outside days (Days falling in the previous or next month).
fixedWeeks	boolean Whether to always display 6 weeks in a month.
textDirection	'ltr' \| 'rtl' The text direction of the calendar.
weekdays	Date[] Array of weekdays starting from the first day of the week.
months	{ month: Date, weeks: Date[][], }[] Array of the currently displayed months.
weeks	Date[][] Weeks of the current month. Useful if only one month is being rendered.
navigate	(action: `${'prev' \| 'next'}-${'month' \| 'year'}` \| (date: Date) => Date) => void Function to navigate the calendar.
min	number \| null The minimum number of days that have to be selected.
max	number \| null The maximum number of days that can be selected.
excludeDisabled	boolean Whether to reset the range selection if a disabled day is included in the range.
labelIds	[string \| undefined] The `id` attributes of the calendar label elements. Can be undefined if no `Calendar.Label` is present for the given month index.

Developed and designed by Jasmin

Calendar

Features Section titled Features

Installation Section titled Installation

Usage Section titled Usage

Anatomy Section titled Anatomy

Philosophy Section titled Philosophy

Usage with SSR/SSG Section titled Usage with SSR/SSG

Examples Section titled Examples

Range selection Section titled Range selection

Disabling dates Section titled Disabling dates

Date Picker Section titled Date Picker

Accessibility Section titled Accessibility

Accessible nav buttons Section titled Accessible nav buttons

Keyboard navigation Section titled Keyboard navigation

API reference Section titled API reference

<Root />

Props

<Label />

Props

Data attributes

<Nav />

Props

Data attributes

<Table />

Props

Data attributes

<HeadCell />

Props

Data attributes

<Cell />

Props

Data attributes

<CellTrigger />

Props

Data attributes

useContext

Returns

RootChildrenProps

Props