Calendar
A month grid for selecting one date, a date range, or multiple dates.
Use Calendar when date selection benefits from visible month context. Compose it inside a Popover, Modal, or Sheet when the calendar should open from another control.
Installation
The copied source is available in the registry JSON. The canonical implementation lives in packages/react/src/components/calendar.tsx.
Usage
const [date, setDate] = useState<Date | null>(null);
<Calendar mode="single" value={date} onValueChange={setDate} />The value type follows mode: Date | null for single, DateRange for range, and Date[] for multiple selection.
Examples
Range and multiple selection
Range selection builds an inclusive start and end. Multiple selection independently toggles each chosen date.
Date constraints
Combine minimum, maximum, and predicate constraints. Disabled dates remain visible but cannot be selected.
API reference
| Prop | Type | Default | Description |
|---|---|---|---|
| mode | "single" | "range" | "multiple" | "single" | Selects the value contract and selection behavior. |
| value / onValueChange | Date | null | DateRange | Date[] / (value) => void | - | Controls selection using the value shape associated with mode. |
| defaultValue | Date | null | DateRange | Date[] | - | Sets initial selection when state is uncontrolled. |
| weekStartsOn | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 0 | Sets the first weekday, where 0 is Sunday and 1 is Monday. |
| fromDate / toDate | Date / Date | - | Sets inclusive minimum and maximum selectable dates. |
| disabledDates | (date: Date) => boolean | - | Disables dates for which the predicate returns true. |
Use defaultMonth when the initially visible month should differ from the selected value. The native disabled prop disables the complete calendar.
Selection behavior
- In range mode, the first selection sets
from. The second setsto, or swaps the endpoints when it precedesfrom. - Selecting the same range start twice clears the range.
- Days from adjacent months remain selectable and move the visible month when chosen.
- Today receives a neutral outline when it is not selected.
Accessibility
- Month navigation buttons have accessible Previous month and Next month labels.
- Every date is a native button named with its full date and exposes selection through
aria-pressed. - Tab moves through the interactive buttons. Enter or Space activates the focused navigation or date button.
- Constrained dates use the native disabled state and cannot receive focus.
- Provide a visible field label outside Calendar when it participates in a form.