Report an issue

Calendar

Displays dates and days of the week, facilitating date-related interactions.

May 2024
Su
Mo
Tu
We
Th
Fr
Sa
28
29
30
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
1
2
3
4
5
6
7
8

Structure

	<script lang="ts">
  import { Calendar } from "bits-ui";
</script>
 
<Calendar.Root let:months let:weekdays>
  <Calendar.Header>
    <Calendar.PrevButton />
    <Calendar.Heading />
    <Calendar.NextButton />
  </Calendar.Header>
 
  {#each months as month}
    <Calendar.Grid>
      <Calendar.GridHead>
        <Calendar.GridRow>
          {#each weekdays as day}
            <Calendar.HeadCell>
              {day}
            </Calendar.HeadCell>
          {/each}
        </Calendar.GridRow>
      </Calendar.GridHead>
      <Calendar.GridBody>
        {#each month.weeks as weekDates}
          <Calendar.GridRow>
            {#each weekDates as date}
              <Calendar.Cell {date}>
                <Calendar.Day {date} month={month.value} />
              </Calendar.Cell>
            {/each}
          </Calendar.GridRow>
        {/each}
      </Calendar.GridBody>
    </Calendar.Grid>
  {/each}
</Calendar.Root>

API Reference

Calendar.Root

The root calendar component which contains all other calendar components.

Property Type Description
value
DateValue

The selected date.

Default:  —— undefined
onValueChange
function

A function that is called when the selected date changes.

Default:  —— undefined
placeholder
DateValue

The placeholder date, which is used to determine what month to display when no date is selected. This updates as the user navigates the calendar, and can be used to programatically control the calendar's view.

Default:  —— undefined
onPlaceholderChange
function

A function that is called when the placeholder date changes.

Default:  —— undefined
pagedNavigation
boolean

Whether or not to use paged navigation for the calendar. Paged navigation causes the previous and next buttons to navigate by the number of months displayed at once, rather than by one month.

Default: false
preventDeselect
boolean

Whether or not to prevent the user from deselecting a date without selecting another date first.

Default: false
weekStartsOn
number

The day of the week to start the calendar on. 0 is Sunday, 1 is Monday, etc.

Default: 0
weekdayFormat
enum

The format to use for the weekday strings provided via the weekdays slot prop.

Default: 'narrow'
calendarLabel
string

The accessible label for the calendar.

Default:  —— undefined
fixedWeeks
boolean

Whether or not to always display 6 weeks in the calendar.

Default: false
isDateDisabled
function

A function that returns whether or not a date is disabled.

Default:  —— undefined
isDateUnavailable
function

A function that returns whether or not a date is unavailable.

Default:  —— undefined
maxValue
DateValue

The maximum date that can be selected.

Default:  —— undefined
minValue
DateValue

The minimum date that can be selected.

Default:  —— undefined
locale
string

The locale to use for formatting dates.

Default:  —— undefined
multiple
boolean

Whether or not multiple dates can be selected.

Default: false
numberOfMonths
number

The number of months to display at once.

Default: 1
disabled
boolean

Whether or not the accordion is disabled.

Default: false
readonly
boolean

Whether or not the calendar is readonly.

Default: false
initialFocus
boolean

If true, the calendar will focus the selected day, today, or the first day of the month in that order depending on what is visible when the calendar is mounted.

Default: false
asChild
boolean

Whether to use render delegation with this component or not.

Default: false
el
HTMLDivElement

The underlying DOM element being rendered. You can bind to this to programatically interact with the element.

Default:  —— undefined
Slot Property Type Description
months
Month[]

The current months to display in the calendar. Used to render the calendar.
weekdays
string[]

The days of the week to display in the calendar, typically used within the table header.
builder
object

The builder attributes and actions to apply to the element if using the asChild prop with delegation.
Data Attribute Value Description
data-invalid
——

Present on the root element when the calendar is invalid.

data-disabled
——

Present on the root element when the calendar is disabled.

data-readonly
——

Present on the root element when the calendar is readonly.

data-calendar-root
——

Present on the root element.

Calendar.Header

The header of the calendar.

Property Type Description
asChild
boolean

Whether to use render delegation with this component or not.

Default: false
el
HTMLElement

The underlying DOM element being rendered. You can bind to this to programatically interact with the element.

Default:  —— undefined
Slot Property Type Description
attrs
object

Additional attributes to apply to the element if using the asChild prop with delegation.
Data Attribute Value Description
data-calendar-header
——

Present on the header element.

Calendar.Heading

The heading of the calendar.

Property Type Description
asChild
boolean

Whether to use render delegation with this component or not.

Default: false
el
HTMLDivElement

The underlying DOM element being rendered. You can bind to this to programatically interact with the element.

Default:  —— undefined
Slot Property Type Description
builder
object

The builder attributes and actions to apply to the element if using the asChild prop with delegation.
headingValue
string

The heading value.
Data Attribute Value Description
data-calendar-heading
——

Present on the heading element.

Calendar.NextButton

The next button of the calendar.

Property Type Description
asChild
boolean

Whether to use render delegation with this component or not.

Default: false
el
HTMLButtonElement

The underlying DOM element being rendered. You can bind to this to programatically interact with the element.

Default:  —— undefined
Slot Property Type Description
builder
object

The builder attributes and actions to apply to the element if using the asChild prop with delegation.
Data Attribute Value Description
data-calendar-next-button
——

Present on the next button element.

Calendar.PrevButton

The previous button of the calendar.

Property Type Description
asChild
boolean

Whether to use render delegation with this component or not.

Default: false
el
HTMLButtonElement

The underlying DOM element being rendered. You can bind to this to programatically interact with the element.

Default:  —— undefined
Slot Property Type Description
builder
object

The builder attributes and actions to apply to the element if using the asChild prop with delegation.
Data Attribute Value Description
data-calendar-prev-button
——

Present on the prev button element.

Calendar.Cell

A cell in the calendar grid.

Property Type Description
date
DateValue

The date for the cell.

Default:  —— undefined
asChild
boolean

Whether to use render delegation with this component or not.

Default: false
el
HTMLTableCellElement

The underlying DOM element being rendered. You can bind to this to programatically interact with the element.

Default:  —— undefined
Slot Property Type Description
attrs
object

Additional attributes to apply to the element if using the asChild prop with delegation.
Data Attribute Value Description
data-disabled
——

Present on the element when the date is disabled.

data-calendar-cell
——

Present on the cell element.

Calendar.Day

A day in the calendar grid.

Property Type Description
date
DateValue

The date for the cell.

Default:  —— undefined
month
DateValue

The current month the date is being displayed in.

Default:  —— undefined
asChild
boolean

Whether to use render delegation with this component or not.

Default: false
el
HTMLDivElement

The underlying DOM element being rendered. You can bind to this to programatically interact with the element.

Default:  —— undefined
Slot Property Type Description
disabled
boolean

Whether or not the date is disabled.
unavailable
boolean

Whether or not the date is unavailable.
selected
boolean

Whether or not the date is selected.
builder
object

The builder attributes and actions to apply to the element if using the asChild prop with delegation.
Data Attribute Value Description
data-disabled
——

Present on the element when the date is disabled.

data-selected
——

Present on the element when the date is selected.

data-unavailable
——

Present on the element when the date is unavailable.

data-value
——

The date in the format "YYYY-MM-DD".

data-today
——

Present on the element when the date is today.

data-outside-month
——

Present on the element when the date is outside the current month.

data-outside-visible-months
——

Present on the element when the date is outside the visible months.

data-focused
——

Present on the element when the date is focused.

data-calendar-day
——

Present on the day element.

Calendar.Grid

The grid of dates in the calendar, typically representing a month.

Property Type Description
asChild
boolean

Whether to use render delegation with this component or not.

Default: false
el
HTMLTableElement

The underlying DOM element being rendered. You can bind to this to programatically interact with the element.

Default:  —— undefined
Slot Property Type Description
builder
object

The builder attributes and actions to apply to the element if using the asChild prop with delegation.
Data Attribute Value Description
data-calendar-grid
——

Present on the grid element.

Calendar.GridBody

The body of the grid of dates in the calendar.

Property Type Description
asChild
boolean

Whether to use render delegation with this component or not.

Default: false
el
HTMLTableSectionElement

The underlying DOM element being rendered. You can bind to this to programatically interact with the element.

Default:  —— undefined
Slot Property Type Description
attrs
object

Additional attributes to apply to the element if using the asChild prop with delegation.
Data Attribute Value Description
data-calendar-grid-body
——

Present on the grid body element.

Calendar.GridHead

The head of the grid of dates in the calendar.

Property Type Description
asChild
boolean

Whether to use render delegation with this component or not.

Default: false
el
HTMLTableSectionElement

The underlying DOM element being rendered. You can bind to this to programatically interact with the element.

Default:  —— undefined
Slot Property Type Description
attrs
object

Additional attributes to apply to the element if using the asChild prop with delegation.
Data Attribute Value Description
data-calendar-grid-head
——

Present on the grid head element.

Calendar.GridRow

A row in the grid of dates in the calendar.

Property Type Description
asChild
boolean

Whether to use render delegation with this component or not.

Default: false
el
HTMLTableRowElement

The underlying DOM element being rendered. You can bind to this to programatically interact with the element.

Default:  —— undefined
Slot Property Type Description
attrs
object

Additional attributes to apply to the element if using the asChild prop with delegation.
Data Attribute Value Description
data-calendar-grid-row
——

Present on the grid row element.

Calendar.HeadCell

A cell in the head of the grid of dates in the calendar.

Property Type Description
asChild
boolean

Whether to use render delegation with this component or not.

Default: false
el
HTMLTableCellElement

The underlying DOM element being rendered. You can bind to this to programatically interact with the element.

Default:  —— undefined
Slot Property Type Description
attrs
object

Additional attributes to apply to the element if using the asChild prop with delegation.
Data Attribute Value Description
data-calendar-head-cell
——

Present on the head cell element.