Report an issue

Range Calendar

Presents a calendar view tailored for selecting date ranges.

December 2024
Su
Mo
Tu
We
Th
Fr
Sa
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
9
10
11

Structure

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

API Reference

RangeCalendar.Root

The root range calendar component which contains all other calendar components.

Property Type Description
value
DateRange

The selected date range.

Default:  —— undefined
onValueChange
function

A function that is called when the selected date range changes.

Default:  —— undefined
placeholder
DateValue

The placeholder date, which is used to determine what month to display when no date range 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
weekdayFormat
enum

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

Default: 'narrow'
weekStartsOn
number

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

Default: 0
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
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
startValue
union

The start value of the date range, which can exist prior to the true value being set, which is only set once a start and end value are selected. You can bind:startValue to a value to receive updates, but modifying this value outside the component will have no effect. To programmatically control the start value, use bind:value and update the start property of the DateRange object. This is provided as a convenience for use cases where you want to display the selected start value outside the component before the value is set.

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

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

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

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

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

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

RangeCalendar.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-selection-start
——

Present on the element when the date is the start of the selection.

data-selection-end
——

Present on the element when the date is the end of the selection.

data-highlighted
——

Present on the element when the date is in the range as its still being selected.

data-focused
——

Present on the element when the date is focused.

data-calendar-day
——

Present on the day element.

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

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

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

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

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