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>

RzCalendarProvider Parameters

Parameter	Type	Description
Mode	SelectionDatesMode	Must match the Mode of the child `RzCalendar`.
Value	DateOnly?	Initial date for `Single` mode.
Values	List<DateOnly>?	Initial dates for `Multiple` mode.
Range	CalendarDateRange?	Initial range for `MultipleRanged` mode.

JavaScript Scope API

The provider exposes these properties and methods to the Alpine scope (e.g., via x-on:click).

Name	Description
date	Get/Set the selected date string (YYYY-MM-DD).
formattedDate	Read-only localized string of the selected date.
dates	Raw array of selected date strings.
setToday()	Sets the selection to the current date.
addDays(n)	Adds `n` days to the current selection.
clear()	Clears all selected dates.