;
};
The Calendar component renders a month view for selecting dates. It supports single date, multiple date, and date range selection. Selected dates are stored in client state as ISO strings.
## Basic Usage
```python Python icon="python" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
from prefab_ui.components import Calendar
Calendar()
```
```json Protocol icon="brackets-curly" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
{"view": {"name": "calendar_1", "type": "Calendar", "mode": "single"}}
```
## Initial Value
Pass a `datetime.date` to `value` to pre-select a date:
```python Python icon="python" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
import datetime
from prefab_ui.components import Calendar
Calendar(value=datetime.date(2026, 7, 4))
```
```json Protocol icon="brackets-curly" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
{
"view": {
"name": "calendar_2",
"value": "2026-07-04T12:00:00.000Z",
"type": "Calendar",
"mode": "single"
},
"state": {"calendar_2": "2026-07-04T12:00:00.000Z"}
}
```
## Range Selection
Set `mode="range"` to let users select a start and end date. The value is a dict with `"from"` and `"to"` keys:
```python Python icon="python" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
import datetime
from prefab_ui.components import Calendar
Calendar(
mode="range",
value={
"from": datetime.date(2025, 6, 10),
"to": datetime.date(2025, 6, 20),
},
)
```
```json Protocol icon="brackets-curly" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
{
"view": {
"name": "calendar_3",
"value": "{\"from\": \"2025-06-10T12:00:00.000Z\", \"to\": \"2025-06-20T12:00:00.000Z\"}",
"type": "Calendar",
"mode": "range"
},
"state": {
"calendar_3": "{\"from\": \"2025-06-10T12:00:00.000Z\", \"to\": \"2025-06-20T12:00:00.000Z\"}"
}
}
```
## Multiple Selection
Select multiple individual dates with `mode="multiple"`. The value is a list of dates:
```python Python icon="python" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
import datetime
from prefab_ui.components import Calendar
Calendar(
mode="multiple",
value=[
datetime.date(2025, 6, 10),
datetime.date(2025, 6, 15),
datetime.date(2025, 6, 22),
],
)
```
```json Protocol icon="brackets-curly" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
{
"view": {
"name": "calendar_4",
"value": "[\"2025-06-10T12:00:00.000Z\", \"2025-06-15T12:00:00.000Z\", \"2025-06-22T12:00:00.000Z\"]",
"type": "Calendar",
"mode": "multiple"
},
"state": {
"calendar_4": "[\"2025-06-10T12:00:00.000Z\", \"2025-06-15T12:00:00.000Z\", \"2025-06-22T12:00:00.000Z\"]"
}
}
```
## Reading the Value
Use `.rx` to get a reactive reference to the calendar's current selection. What `.rx` holds depends on the mode: an ISO date string for single mode, a `{"from": ..., "to": ...}` object for range mode, or an array of ISO strings for multiple mode. The `.date()` pipe formats a single ISO string for display:
```python Python icon="python" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
import datetime
from prefab_ui.components import Calendar, Column, Input, Label, Row
with Row(gap=6):
cal = Calendar(value=datetime.date(2026, 7, 4))
with Column(gap=2, justify="center"):
Label("Selected date")
Input(value=cal.rx.date("long"), read_only=True)
```
```json Protocol icon="brackets-curly" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
{
"view": {
"cssClass": "gap-6",
"type": "Row",
"children": [
{
"name": "calendar_5",
"value": "2026-07-04T12:00:00.000Z",
"type": "Calendar",
"mode": "single"
},
{
"cssClass": "gap-2 justify-center",
"type": "Column",
"children": [
{"type": "Label", "text": "Selected date", "optional": false},
{
"name": "input_1",
"value": "{{ calendar_5 | date:long }}",
"type": "Input",
"inputType": "text",
"disabled": false,
"readOnly": true,
"required": false
}
]
}
]
},
"state": {"calendar_5": "2026-07-04T12:00:00.000Z"}
}
```
Click a date and the input updates instantly. The `.date("long")` pipe formats an ISO string like `"2025-01-15"` into `"January 15, 2025"`.
## API Reference
Selection mode: `"single"`, `"multiple"`, or `"range"`.
Initial selected date(s). Single: a `datetime.date`. Range: `{"from": date, "to": date}`. Multiple: a list of dates. Any position also accepts an `Rx` for reactive binding.
State key for storing the selected date. Single mode stores an ISO string; range mode stores `{"from": "...", "to": "..."}`.
Action(s) triggered when the selection changes.
Additional Tailwind CSS classes.
## Protocol Reference
```json Calendar theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
{
"type": "Calendar",
"id?": "string",
"onMount?": "any",
"name?": "string",
"value?": "string | object | string[]",
"mode?": "single | multiple | range",
"onChange?": "Action | Action[]",
"cssClass?": "string"
}
```
For the complete protocol schema, see [Calendar](/protocol/calendar).