Calendar Provider

The RzCalendarProvider is an orchestration component that bridges the gap between server-side rendering and client-side interactivity.

In RizzyUI's SSR architecture, UI components are rendered on the server. However, rich calendar interactions—like syncing two-way inputs, managing popover visibility based on selection, or applying quick-select presets—often require immediate feedback on the client without a server round-trip.

The RzCalendarProvider creates a reactive Alpine.js scope around the calendar. It serves as the "Client-Side Source of Truth," keeping the visual calendar synchronized with inputs, buttons, and other UI elements automatically.

Client-Side Feedback

By wrapping an RzCalendar in a provider, you can access the selected date reactively using Alpine.js (x-text="date"). This allows you to display selection feedback instantly.

Single Date

Selected:

Source

<RzCalendarProvider Mode="SelectionDatesMode.Single" Value="_date1">
    <RzCalendar />
    <p>Selected: <span x-text="date"></span></p>
</RzCalendarProvider>

@code {
    private DateOnly? _date1 = DateOnly.FromDateTime(DateTime.Now);
}

Presets & Controls

The provider exposes a public JavaScript API (setToday(), addDays(n), clear()) that external buttons can call directly within the provider's scope.

Source

<RzCalendarProvider Mode="SelectionDatesMode.Single" Value="_date1">
    <div class="flex">
        <div class="flex flex-col gap-2">
           <RzButton Variant="ThemeVariant.Default" Outline x-on:click="setToday()">Today</RzButton>
           <RzButton Variant="ThemeVariant.Default" Outline x-on:click="addDays(1)">Tomorrow</RzButton>
        </div>
        <RzCalendar />
    </div>
</RzCalendarProvider>

Popovers & Inputs

Combine RzPopover with RzCalendarProvider to create dropdown pickers. The provider exposes a formattedDate property (configured via FormatOptions) for display.

Date of birth

Two-Way Input Binding

Source

<!-- Popover Example -->
<RzCalendarProvider Mode="SelectionDatesMode.Single" Value="_date1">
    <RzPopover>
        <PopoverTrigger AsChild>
            <RzButton Variant="ThemeVariant.Default" Outline>
                <span x-text="formattedDate || 'Pick a date'"></span>
            </RzButton>
        </PopoverTrigger>
        <PopoverContent class="w-auto p-0">
            <div x-on:rz:calendar:click-day="open = false">
                <RzCalendar />
            </div>
        </PopoverContent>
    </RzPopover>
</RzCalendarProvider>

<!-- Input Example -->
<RzCalendarProvider Mode="SelectionDatesMode.Single" Value="_date1">
    <input type="text" x-model.debounce.500ms="date" placeholder="YYYY-MM-DD" />
</RzCalendarProvider>

Data Integration

In a real application, selecting a date often requires fetching data from the server. This example simulates a data fetch using client-side logic to update an event list instantly.

Source

<RzCalendarProvider Mode="SelectionDatesMode.Single" Value="_date1">
    <RzCard>
        <RzCalendar class="border-0 shadow-none" />
        <CardFooter>
             <div x-show="date">
                 <!-- In a real app, use HTMX here: 
                      hx-get="/api/events" 
                      hx-trigger="rz:calendar:click-day" -->
                 <div class="rounded-md bg-muted px-3 py-2 text-sm">
                     <div class="font-medium">Team Sync</div>
                 </div>
             </div>
        </CardFooter>
    </RzCard>
</RzCalendarProvider>

Component Parameters

The following table summarizes the key parameters for RzCalendarProvider.

Property	Description	Type	Default
`ChildContent`	Content rendered in the provider scope, usually one or more `RzCalendar` components and related UI.	`RenderFragment`	Required
`Mode`	Selection strategy used by the provider and child calendar instances.	`SelectionDatesMode`	`SelectionDatesMode.Single`
`Value`	Initial selected date for single-date mode.	`DateOnly?`	`null`
`Values`	Initial selected dates for multiple-date mode.	`List<DateOnly>?`	`null`
`Range`	Initial date range for ranged selection mode.	`CalendarDateRange?`	`null`
`Locale`	Locale used for the formatted Alpine date helpers.	`string?`	`null`
`FormatOptions`	Intl.DateTimeFormat options object used when generating `formattedDate` and `formattedRange`.	`IntlDateTimeFormatOptions?`	`null`

Alpine API

RzCalendarProvider uses the rzCalendarProvider Alpine x-data component.

Method	Parameters	Description
`setToday`	`—`	Sets today as the active selection.
`addDays`	`n: number`	Shifts the current selected date by `n` days.
`setDate`	`dateStr: string`	Sets the selection to a specific ISO date string (`YYYY-MM-DD`).
`clear`	`—`	Clears all selected dates.
`toggleDate`	`dateStr: string`	Toggles an ISO date in/out of the selection collection.
`syncToCalendar`	`—`	Forces provider state to sync to the underlying Vanilla Calendar instance.