Calendar

The <x-wirekit::calendar> component renders a standalone month grid for single-date selection. It supports full keyboard navigation (arrow keys, Page Up/Down, Home/End) and integrates with forms via a hidden input. The implementation follows the WAI-ARIA Date Picker Dialog pattern.

Usage

<x-wirekit::calendar name="birthday" value="2026-04-15" />

Multi-month & quick navigation

Render several months side by side with months, or swap the static month label for native month + year jump selects with selectable-header. Both are opt-in, so the default single-month calendar is unchanged.

<x-wirekit::calendar name="jump-demo" value="2026-04-15" selectable-header />

Date range

Add the range flag and the calendar takes two clicks: the first sets the start, the second the end. A second click before the start simply becomes the start — there is no rule to learn about which end to pick first. While only the start is set, the day under the pointer stands in for the end, so the shading answers the question a reader is actually asking: what am I about to choose.

value reads and writes YYYY-MM-DD/YYYY-MM-DD, the same spelling date-picker uses with its own range flag — a value moves between the two without translation. The form receives name[start] and name[end] alongside the combined name field, so a handler written for a single date still gets something it understands.

<x-wirekit::calendar name="stay" range months="2" value="2026-08-11/2026-08-18" />

<x-wirekit::calendar name="range-demo" value="2026-04-15" :months="2" />

In a multi-month view the day grids stay fully keyboard-navigable: arrow keys cross between the displayed grids before shifting the whole window.

Week start

Weeks begin on Monday by default. Pass week-starts-on to change it — 0 for a Sunday-first week, 1 for Monday. The app-wide default lives in config/wirekit.php under components.calendar.week-starts-on.

<x-wirekit::calendar name="sunday-demo" value="2026-04-15" :week-starts-on="0" />

Pre-selected Date

Pass an ISO 8601 date string (YYYY-MM-DD) to the value prop. The calendar opens on that date's month with the day highlighted.

<x-wirekit::calendar name="start_date" value="2026-01-10" />

No Initial Value

Without a value, the calendar defaults to the current month with today's date visually highlighted (ring indicator, not selected).

<x-wirekit::calendar name="appointment" />

Inside a Form

The calendar renders a hidden <input> with the given name attribute. When a date is selected, the hidden input's value updates and dispatches an input event — making it compatible with standard form submission and wire:model.

<form wire:submit="save">
    <x-wirekit::field label="Start Date">
        <x-wirekit::calendar name="start_date" wire:model="startDate" />
    </x-wirekit::field>

    <x-wirekit::button type="submit">Save</x-wirekit::button>
</form>

With Livewire

The hidden input dispatches a native input event on selection, so wire:model bindings work automatically.

<x-wirekit::calendar name="event_date" wire:model.live="eventDate" />

Visual States

Keyboard

The calendar grid supports full keyboard navigation following the WAI-ARIA Grid pattern:

When arrow keys move past the first or last day of the month, the calendar navigates to the previous or next month automatically.

Date Format

The calendar uses ISO 8601 (YYYY-MM-DD) format internally and in the hidden input value. The month/year header displays a localized English format (e.g., "April 2026") using Date.toLocaleDateString('en-US', { month: 'long', year: 'numeric' }).

European / German Format

The header locale is currently set to en-US. To display the month header in German (e.g., "April 2026" → "April 2026" in German, or "Dezember 2026" for December), you can override the monthLabel getter via Alpine:

<x-wirekit::calendar name="termin" value="2026-04-15"
    x-init="
        Object.defineProperty($data, 'monthLabel', {
            get() {
                const d = new Date(this.viewYear, this.viewMonth, 1);
                return d.toLocaleDateString('de-DE', { month: 'long', year: 'numeric' });
            }
        });
    "
/>

This changes the month header to the German locale — "April 2026", "Dezember 2026", "März 2026", etc.

// In your Livewire component or controller
$formatted = Carbon::parse($this->startDate)->format('d.m.Y');     // 15.04.2026
$written   = Carbon::parse($this->startDate)->translatedFormat('d. F Y'); // 15. April 2026

Optimistic UI

Pass the name of the Livewire method the calendar should call and the date lands immediately, then confirms or undoes itself when the server answers:

<x-wirekit::calendar
    name="due"
    :value="$due"
    optimistic="saveDue"
/>

Load wirekit-optimistic.js alongside whichever bundle you already use — below it, in your layout:

@wirekitScripts
<script src="{{ asset('vendor/wirekit/wirekit-optimistic.js') }}"></script>

Try it

The demo below runs the real path: the change shows immediately, the outline says it is provisional, and the server's answer either confirms it silently or takes it back.

{{-- In your app there is no host: your own Livewire component owns the method. --}}
<x-wirekit::calendar
    name="due"
    :value="$due"
    optimistic="saveDue"
/>

The <livewire:demos.…> wrapper above exists only on this site — it supplies the demo methods so the page can show a real round trip. The block under it is what you write.

The prop takes a method name rather than true because the component cannot know the action otherwise: server actions reach a WireKit component through the attribute bag, so it never sees your wire:click. optimistic replaces wire:model.live here rather than joining it — the method you name is what changes the value on the server; pass the current one with :value so the calendar knows where it started.

The displayed month does not roll back with the date. If you paged forward to March and the pick was refused, you are still looking at March — only the selection returns to what the server has. Where you are looking is yours; the value is the server's.

Props

Accessibility

• Grid: role="grid" on the <table> element
• Cells: role="gridcell" on each <td>
• Rows: role="row" on each <tr>
• Day headers: <th scope="col"> for column headers (Su, Mo, Tu, etc.)
• Selected day: aria-selected="true" on the active day button
• Roving tabindex: only the focused day has tabindex="0"; all others have tabindex="-1"
• Month label: aria-live="polite" announces month changes to screen readers
• Nav buttons: aria-label="Previous month" / aria-label="Next month"
• Chevron SVGs: aria-hidden="true" (decorative)
• Disabled days (adjacent months): disabled attribute prevents interaction
• selectableHeader: native <select> controls (full keyboard + screen-reader support) with sr-only labels and an aria-live month announcement
• Multi-month (months > 1): each month is its own role="grid"; arrow keys move between the displayed grids, keeping a single roving tabindex="0"

Day-cell size on touch

Day cells measure 36×36 and the month navigation buttons 28×28. Both clear the 24×24 minimum of WCAG 2.5.8 and both stay under the 44×44 of the AAA criterion 2.5.5 — a deliberate choice, not an oversight.

The reason is that the enlargement would defeat itself. In a seven-column grid at 36px pitch, a 44px hit area reaches 4px into both horizontal neighbors, and the cell painted last takes the taps meant for the other. A day that is slightly small is workable; a day that activates its neighbor is not. Reaching 44 here needs a bigger calendar, which is a layout decision — so if your app needs it, scale the component rather than only its hit areas.

Keyboard Interaction

Pitfalls

• Don't use calendar for date input. Use <x-wirekit::date-picker>. The calendar primitive is for displaying a month view — not collecting input.

• It needs 306px, and below that the last column goes over the edge. Seven columns of day cells do not shrink indefinitely: the grid stops at 280px, and with the panel's 12px padding either side plus its 1px border that makes 306px the narrowest container the calendar fits inside cleanly. Measured in a browser across a sweep from 330px down to 200px, not derived from the stylesheet.

  What happens below it is worth knowing, because it is quiet. The grid keeps its 280px and starts overrunning the panel's padding; nothing scrolls and nothing throws. Around 293px the seventh column crosses the panel's outer edge, and in a container that does not scroll a reader simply loses Sunday.

  On a 360px phone this is comfortable — a full-width block leaves well over 306px. It matters when the calendar sits in something narrower than the viewport: a preview frame, a sidebar, a split pane. Give it 306px or let its container scroll.

Design Tokens

Personalization

Override classes globally via WireKit::personalize():

use Pushery\WireKit\WireKit;

WireKit::personalize('calendar', [
    'base' => 'inline-block bg-white border rounded-lg shadow p-4 font-sans',
    'header' => 'flex items-center justify-between mb-2',
]);

Further Reading

• WAI-ARIA Date Picker Dialog Example — the reference implementation this component follows
• WAI-ARIA Grid Pattern — keyboard navigation pattern used for the day grid
• MDN: role="grid"
• MDN: aria-selected