Calendar

Overview

Calendar implements its own month grid, selection state, and keyboard navigation entirely in C#; the only interop it uses is the built-in ElementReference.FocusAsync (no JS Calendar library, no Navius primitive underneath). It supports three selection modes (single, range, multiple), min/max/disabled-day constraints, and rendering multiple months side by side.

Install

navius add calendar --to ./src/MyApp --namespace MyApp.Ui

Usage

@using Zits.Ui.Components

<ZitsCalendar @bind-Selected="_date" />

@code {
    private DateOnly? _date = new(2026, 6, 12);
}

Parts and props

Calendar is a single root (ZitsCalendar) composing an internal ZitsCalendarDay for each cell; ZitsCalendarDay is an implementation detail (focus-aware button wrapper), not a public part.

Prop	Type	Default	Description
Mode	string	"single"	single, range, or multiple. Selects which of the three value/binding trios below is active.
Selected / SelectedChanged / DefaultSelected	DateOnly?	null	Controlled/uncontrolled selection for single mode. Bind with @bind-Selected.
SelectedRange / SelectedRangeChanged / DefaultSelectedRange	(DateOnly? Start, DateOnly? End)	(null, null)	Controlled/uncontrolled selection for range mode. Bind with @bind-SelectedRange.
SelectedDates / SelectedDatesChanged / DefaultSelectedDates	IReadOnlyList<DateOnly>	[]	Controlled/uncontrolled selection for multiple mode. Bind with @bind-SelectedDates.
DefaultMonth	DateOnly?	null	Month shown first when there is no selection; defaults to today.
DisabledMatcher	Func<DateOnly, bool>?	null	Predicate making matched days unselectable.
MinDate / MaxDate	DateOnly?	null	Bounds; days outside are disabled.
FirstDayOfWeek	DayOfWeek	Sunday	Reorders the header row and grid.
NumberOfMonths	int	1	How many months render side by side.
ShowOutsideDays	bool	true	Renders faded leading/trailing days of adjacent months.

Styling surface

Attributes on ZitsCalendar is forwarded to the root div and merged with the base class via Cn.Merge. Day-cell styling is computed per day and exposed via both classes and the data attributes below, so a caller can restyle via CSS instead of props.

Parameter	Values
Mode	single · range · multiple

Data attribute hooks

Part	Attribute	Description
Day	data-selected	Present when the day is part of the current selection.
Day	data-range-start / data-range-end / data-range-middle	Range-mode boundary and mid-range markers.
Day	data-today	Present on the current date.
Day	data-outside	Present on a leading/trailing day from an adjacent month.
Day	data-disabled	Present when MinDate/MaxDate/DisabledMatcher excludes the day.
Day	data-day	The day’s yyyy-MM-dd value, for CSS/test targeting.

Calendar implements its own accessibility mechanism rather than delegating to a primitive: the grid uses role="grid" with <thead>/<tbody> and role="presentation" cells, each day carries aria-label (full date) and aria-selected/aria-disabled where relevant, and the month heading is an aria-live="polite" region. Keyboard support is a roving tabindex (one day is tabindex="0", the rest -1): arrow keys move by day/week, Home/End jump to the week’s ends, PageUp/PageDown shift by month, and moving focus calls ElementReference.FocusAsync on the target day after re-render. Enter/Space fall through to the day button’s native click.