GPUI Deck

Calendar

Single/multiple/range date selection, separate focus, date-disabled rules, configurable week start, bounded navigation and RTL.

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.

InputResult
Tab / Shift+TabEnter at the one retained day stop, or leave the grid
Left / RightMove focus one physical cell, reversing chronological direction in RTL
Up / DownMove focus by one week
Home / EndMove to the configured first / last day of the current week
Page Up / Page DownMove by one month, clamping month-end dates
Shift+Page Up / Shift+Page DownMove by one year
Enter / Space / clickCommit 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.