Rendered by GPUI’s web backend from the real component. Requires a browser with WebGPU.
The Selection catalogue has a month-and-year selector for the recording range. Use
display_month(date, window, cx) to jump directly to a different month. The
calendar keeps its selection and clamps the cursor day to the month's length
and configured bounds. A focused day follows the jump. An external month
selector retains focus.
CalendarState retains a CalendarSelection, the focused date, and the
visible month. Date is jiff's civil date (jiff::civil::Date), re-exported; no second date
model or timezone conversion is introduced. Create the state once:
let calendar = cx.new(|cx| {
let initial = Date::new(2026, 11, 9).unwrap();
CalendarState::new(initial, cx)
.bounds(
Date::new(2026, 1, 1).unwrap(),
Date::new(2027, 12, 31).unwrap(),
)
.default_selection(CalendarSelection::Single(Some(initial)))
});Without default_selection, selection starts as CalendarSelection::Single(None). Default bounds cover years
1–9998 (the six-week grid of December 9998 still fits jiff's range); bounds narrows the inclusive selectable range before mounting. The
grid exposes six complete weeks through days(), Monday-first by default. Adjacent-month
dates remain visible; dates outside the configured bounds are disabled.
Before mounting, .week_starts_on(Weekday::Sunday) changes the grid and Home/End
boundaries. Use weekdays() for matching header order; Weekday is re-exported
alongside Date. .disabled_dates(|date| ...) supplies application rules
such as weekends or booked dates. It filters existing single/multiple values and
clears ranges with unavailable endpoints. Default and programmatic setters reject
unavailable dates/endpoints; a range may include unavailable interior days.
Keep the predicate's result stable throughout the state's lifetime.
Render Calendar::new(id, &calendar) with an accessible month/year label. Use
ordinary identified div().id(...).role(Role::Row) containers for one seven-cell weekday header
and six date rows. Weekday headings use Role::ColumnHeader with zero-based
column indices. Each CalendarDay::new(&calendar, date) composes Button's
activation/focus behavior and supplies its native GridCell role, selected state,
disabled state, and row/column indices. The grid declares seven rows including
the weekday header. Render each date returned by days() exactly once, in order.
Keep each day's children non-interactive.
The application owns grid geometry, weekday names, localized full-date labels,
selected-day styles, and month navigation buttons. CalendarDay defaults to an
ISO date accessibility label, supports .accessibility_label(...), and accepts
ordinary GPUI styles plus Button's .styles(...) for selected/disabled states.
See Demo::calendar_content in the native example for the complete composition.
| Input | Result |
|---|---|
| Tab / Shift+Tab | Enter at the one retained day stop, or leave the grid |
| Left / Right | Move focus one physical cell, reversing chronological direction in RTL |
| Up / Down | Move focus by one week |
| Home / End | Move to the configured first / last day of the current week |
| Page Up / Page Down | Move by one month, clamping month-end dates |
| Shift+Page Up / Shift+Page Down | Move by one year |
| Enter / Space / click | Commit the enabled date; emit Change only if it changed |
Keyboard movement crosses months and clamps at selectable bounds without
changing the committed value. A newly focused day requests native reveal, which
a containing ScrollArea can satisfy. Month buttons call previous_month or
next_month, and use can_previous_month/can_next_month for disabled state.
Those methods retain an external navigation button's focus. Read focus_handle()
when explicitly moving focus into the calendar; its grid slot can change as the
visible month changes, so do not cache that handle as a permanent date identity.
Unavailable dates within bounds remain keyboard-focusable for discovery but cannot be activated by pointer, Enter or Space. Even an entirely unavailable calendar keeps one grid Tab stop; disabling the whole Calendar removes normal entry and navigation. Out-of-bounds cells stay outside focus traversal.
Calendar inherits DirectionProvider or accepts .direction(Direction::Rtl).
The application must apply the same Direction::row to weekday/date rows and
mirror weekday header column indices. CalendarDay projects physical columns and
horizontal keyboard direction from its enclosing Calendar. Labels and text
formatting remain application-owned; the Selection catalogue shows this layout.
CalendarSelection also supports Multiple(Vec<Date>) and
Range { start: Option<Date>, end: Option<Date> }. Configure an empty
range with .default_selection(CalendarSelection::Range { start: None, end: None }).
The first activation chooses its start; the second completes inclusive ordered
endpoints, including reverse or same-day selection. Activating a completed range
starts a new partial range. Multiple selection toggles dates, stored in ascending
order without duplicates. is_selected(date) covers every selected date in a range.
selection() returns the complete value, and selection().first_date() supports
summaries. set_selection(selection, window, cx) changes mode/value without a
user event; it rejects out-of-bounds dates, reversed ranges and an end without a
start. A nonempty value also updates the visible month and cursor; clearing
selection retains navigation. CalendarEvent::Change(selection) reports user
changes. set_disabled blocks user navigation/selection and normal Tab entry.
The calendar remains Gregorian. Non-Gregorian arithmetic, clocks and timezone conversion are not provided. The Selection catalogue demonstrates Sunday-first, weekend-disabled range/multiple dates and RTL; the session example retains its Monday-first single recording date.