Calendar
Displays dates and days of the week, facilitating date-related interactions.
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 |
Heads up!
Before diving into this component, it's important to understand how dates/times work in Bits UI. Please read the Dates documentation to learn more!
Structure
Placeholder
The placeholder
prop for the Calendar.Root
component determines what date our calendar should start with when the user hasn't selected a date yet. It also determines the current "view" of the calendar.
As the user navigates through the calendar, the placeholder
will be updated to reflect the currently focused date in that view.
By default, the placeholder
will be set to the current date, and be of type CalendarDate
.
Managing Placeholder State
Bits UI offers several approaches to manage and synchronize the component's placeholder state, catering to different levels of control and integration needs.
1. Two-Way Binding
For seamless state synchronization, use Svelte's bind:placeholder
directive. This method automatically keeps your local state in sync with the component's internal state.
Key Benefits
- Simplifies state management
- Automatically updates
myPlaceholder
when the internal state changes - Allows external control (e.g., changing the placeholder via a separate button/programmatically)
2. Change Handler
For more granular control or to perform additional logic on state changes, use the onPlaceholderChange
prop. This approach is useful when you need to execute custom logic alongside state updates.
Use Cases
- Implementing custom behaviors on placeholder change
- Integrating with external state management solutions
- Triggering side effects (e.g., logging, data fetching)
3. Fully Controlled
For complete control over the component's placeholder state, use the controlledPlaceholder
prop. This approach requires you to manually manage the state, giving you full control over when and how the component responds to change events.
To implement controlled state:
- Set the
controlledPlaceholder
prop totrue
on theCalendar.Root
component. - Provide a
placeholder
prop toCalendar.Root
, which should be a variable holding the current state. - Implement an
onPlaceholderChange
handler to update the state when the internal state changes.
When to Use
- Implementing complex logic
- Coordinating multiple UI elements
- Debugging state-related issues
Note
While powerful, fully controlled state should be used judiciously as it increases complexity and can cause unexpected behaviors if not handled carefully.
For more in-depth information on controlled components and advanced state management techniques, refer to our Controlled State documentation.
Managing Value State
Bits UI offers several approaches to manage and synchronize the component's value state, catering to different levels of control and integration needs.
1. Two-Way Binding
For seamless state synchronization, use Svelte's bind:value
directive. This method automatically keeps your local state in sync with the component's internal state.
Key Benefits
- Simplifies state management
- Automatically updates
myValue
when the internal state changes - Allows external control (e.g., changing the value via a separate button/programmatically)
2. Change Handler
For more granular control or to perform additional logic on state changes, use the onValueChange
prop. This approach is useful when you need to execute custom logic alongside state updates.
Use Cases
- Implementing custom behaviors on value change
- Integrating with external state management solutions
- Triggering side effects (e.g., logging, data fetching)
3. Fully Controlled
For complete control over the component's value state, use the controlledValue
prop. This approach requires you to manually manage the state, giving you full control over when and how the component responds to change events.
To implement controlled state:
- Set the
controlledValue
prop totrue
on theCalendar.Root
component. - Provide a
value
prop toCalendar.Root
, which should be a variable holding the current state. - Implement an
onValueChange
handler to update the state when the internal state changes.
When to Use
- Implementing complex logic
- Coordinating multiple UI elements
- Debugging state-related issues
Note
While powerful, fully controlled state should be used judiciously as it increases complexity and can cause unexpected behaviors if not handled carefully.
For more in-depth information on controlled components and advanced state management techniques, refer to our Controlled State documentation.
Default Value
Often, you'll want to start the Calendar.Root
component with a default value. Likely this value will come from a database in the format of an ISO 8601 string.
You can use the parseDate
function from the @internationalized/date
package to parse the string into a CalendarDate
object.
Validation
Minimum Value
You can set a minimum value for the calendar by using the minValue
prop on Calendar.Root
. If a user selects a date that is less than the minimum value, the calendar will be marked as invalid.
Maximum Value
You can set a maximum value for the calendar by using the maxValue
prop on Calendar.Root
. If a user selects a date that is greater than the maximum value, the calendar will be marked as invalid.
Unavailable Dates
You can specify specific dates that are unavailable for selection by using the isDateUnavailable
prop. This prop accepts a function that returns a boolean value indicating whether a date is unavailable or not.
Disabled Dates
You can specify specific dates that are disabled for selection by using the isDateDisabled
prop.
API Reference
The root calendar component which contains all other calendar components.
Property | Type | Description |
---|---|---|
type required | enum | Whether or not multiple dates can be selected. Default: undefined |
value $bindable | union | The selected date(s). If Default: undefined |
onValueChange | function | A function that is called when the selected date changes. Default: undefined |
controlledValue | boolean | Whether or not the value is controlled or not. If Default: false |
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 programmatically control the calendar's view. Default: undefined |
onPlaceholderChange | function | A function that is called when the placeholder date changes. Default: undefined |
controlledPlaceholder | boolean | Whether or not the placeholder is controlled or not. If Default: false |
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 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: 'en' |
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 Default: false |
disableDaysOutsideMonth | boolean | Whether or not to disable days outside the current month. Default: false |
ref $bindable | HTMLDivElement | The underlying DOM element being rendered. You can bind to this to get a reference to the element. Default: undefined |
children | Snippet | The children content to render. Default: undefined |
child | Snippet | Use render delegation to render your own element. See delegation docs for more information. Default: undefined |
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. |
The header of the calendar.
Property | Type | Description |
---|---|---|
ref $bindable | HTMLElement | The underlying DOM element being rendered. You can bind to this to get a reference to the element. Default: undefined |
children | Snippet | The children content to render. Default: undefined |
child | Snippet | Use render delegation to render your own element. See delegation docs for more information. Default: undefined |
Data Attribute | Value | Description |
---|---|---|
data-disabled | '' | Present on the header element when the calendar is disabled. |
data-readonly | '' | Present on the header element when the calendar is readonly. |
data-calendar-header | '' | Present on the header element. |
The heading of the calendar.
Property | Type | Description |
---|---|---|
ref $bindable | HTMLDivElement | The underlying DOM element being rendered. You can bind to this to get a reference to the element. Default: undefined |
children | Snippet | The children content to render. Default: undefined |
child | Snippet | Use render delegation to render your own element. See delegation docs for more information. Default: undefined |
Data Attribute | Value | Description |
---|---|---|
data-disabled | '' | Present on the heading element when the calendar is disabled. |
data-readonly | '' | Present on the heading element when the calendar is readonly. |
data-calendar-heading | '' | Present on the heading element. |
The next button of the calendar.
Property | Type | Description |
---|---|---|
ref $bindable | HTMLButtonElement | The underlying DOM element being rendered. You can bind to this to get a reference to the element. Default: undefined |
children | Snippet | The children content to render. Default: undefined |
child | Snippet | Use render delegation to render your own element. See delegation docs for more information. Default: undefined |
Data Attribute | Value | Description |
---|---|---|
data-disabled | '' | Present on the next button element when the calendar or this button is disabled. |
data-calendar-next-button | '' | Present on the next button element. |
The previous button of the calendar.
Property | Type | Description |
---|---|---|
ref $bindable | HTMLButtonElement | The underlying DOM element being rendered. You can bind to this to get a reference to the element. Default: undefined |
children | Snippet | The children content to render. Default: undefined |
child | Snippet | Use render delegation to render your own element. See delegation docs for more information. Default: undefined |
Data Attribute | Value | Description |
---|---|---|
data-disabled | '' | Present on the prev button element when the calendar or this button is disabled. |
data-calendar-prev-button | '' | Present on the prev button element. |
A cell 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 |
ref $bindable | HTMLTableCellElement | The underlying DOM element being rendered. You can bind to this to get a reference to the element. Default: undefined |
children | Snippet | The children content to render. Default: undefined |
child | Snippet | Use render delegation to render your own element. See delegation docs for more information. Default: undefined |
Data Attribute | Value | Description |
---|---|---|
data-disabled | '' | Present when the day is disabled. |
data-unavailable | '' | Present when the day is unavailable. |
data-today | '' | Present when the day is today. |
data-outside-month | '' | Present when the day is outside the current month. |
data-outside-visible-months | '' | Present when the day is outside the visible months. |
data-focused | '' | Present when the day is focused. |
data-selected | '' | Present when the day is selected. |
data-value | '' | The date in the format "YYYY-MM-DD". |
data-calendar-cell | '' | Present on the cell element. |
A day in the calendar grid.
Property | Type | Description |
---|---|---|
ref $bindable | HTMLDivElement | The underlying DOM element being rendered. You can bind to this to get a reference to the element. Default: undefined |
children | Snippet | The children content to render. Default: undefined |
child | Snippet | Use render delegation to render your own element. See delegation docs for more information. Default: undefined |
Data Attribute | Value | Description |
---|---|---|
data-disabled | '' | Present when the day is disabled. |
data-unavailable | '' | Present when the day is unavailable. |
data-today | '' | Present when the day is today. |
data-outside-month | '' | Present when the day is outside the current month. |
data-outside-visible-months | '' | Present when the day is outside the visible months. |
data-focused | '' | Present when the day is focused. |
data-selected | '' | Present when the day is selected. |
data-value | '' | The date in the format "YYYY-MM-DD". |
data-calendar-day | '' | Present on the day element. |
The grid of dates in the calendar, typically representing a month.
Property | Type | Description |
---|---|---|
ref $bindable | HTMLTableElement | The underlying DOM element being rendered. You can bind to this to get a reference to the element. Default: undefined |
children | Snippet | The children content to render. Default: undefined |
child | Snippet | Use render delegation to render your own element. See delegation docs for more information. Default: undefined |
Data Attribute | Value | Description |
---|---|---|
data-disabled | '' | Present on the grid element when the calendar is disabled. |
data-readonly | '' | Present on the grid element when the calendar is readonly. |
data-calendar-grid | '' | Present on the grid element. |
The body of the grid of dates in the calendar.
Property | Type | Description |
---|---|---|
ref $bindable | HTMLTableSectionElement | The underlying DOM element being rendered. You can bind to this to get a reference to the element. Default: undefined |
children | Snippet | The children content to render. Default: undefined |
child | Snippet | Use render delegation to render your own element. See delegation docs for more information. Default: undefined |
Data Attribute | Value | Description |
---|---|---|
data-disabled | '' | Present on the grid element when the calendar is disabled. |
data-readonly | '' | Present on the grid element when the calendar is readonly. |
data-calendar-grid-body | '' | Present on the grid body element. |
The head of the grid of dates in the calendar.
Property | Type | Description |
---|---|---|
ref $bindable | HTMLTableSectionElement | The underlying DOM element being rendered. You can bind to this to get a reference to the element. Default: undefined |
children | Snippet | The children content to render. Default: undefined |
child | Snippet | Use render delegation to render your own element. See delegation docs for more information. Default: undefined |
Data Attribute | Value | Description |
---|---|---|
data-disabled | '' | Present on the grid head element when the calendar is disabled. |
data-readonly | '' | Present on the grid head element when the calendar is readonly. |
data-calendar-grid-head | '' | Present on the grid head element. |
A row in the grid of dates in the calendar.
Property | Type | Description |
---|---|---|
ref $bindable | HTMLTableRowElement | The underlying DOM element being rendered. You can bind to this to get a reference to the element. Default: undefined |
children | Snippet | The children content to render. Default: undefined |
child | Snippet | Use render delegation to render your own element. See delegation docs for more information. Default: undefined |
Data Attribute | Value | Description |
---|---|---|
data-disabled | '' | Present on the grid row element when the calendar is disabled. |
data-readonly | '' | Present on the grid row element when the calendar is readonly. |
data-calendar-grid-row | '' | Present on the grid row element. |
A cell in the head of the grid of dates in the calendar.
Property | Type | Description |
---|---|---|
ref $bindable | HTMLTableCellElement | The underlying DOM element being rendered. You can bind to this to get a reference to the element. Default: undefined |
children | Snippet | The children content to render. Default: undefined |
child | Snippet | Use render delegation to render your own element. See delegation docs for more information. Default: undefined |
Data Attribute | Value | Description |
---|---|---|
data-disabled | '' | Present on the head cell element when the calendar is disabled. |
data-readonly | '' | Present on the head cell element when the calendar is readonly. |
data-calendar-head-cell | '' | Present on the head cell element. |