Event Calendar

A scheduling calendar for displaying events across month, week, and agenda views. The month view is a day grid with event pills and a "+N more" overflow; the week view is an hour-row time grid with overlap-split event blocks and a current-time line; the agenda view is a chronological list grouped by day. Navigation (previous / next / today) and the view switcher recompute the visible window. Clicking an event emits an event-click event you handle in Livewire.

This is the scheduling grid — distinct from calendar, which is a date-picker widget. It is token-themed with no third-party calendar library.

Month View

The default view — a 7-column day grid. Events render as pills; days with more than three events show a "+N more" indicator. All-day events and day markers (see Day Markers below) appear as full-width labels at the top of the cell.

A pill carries its start time to the right of the title, formatted in your application's locale — the same one the rest of the calendar is written in, and overridable per calendar with the locale prop. The title truncates to make room, because a clipped time is unreadable while a clipped title is still recognizable. An all-day event shows no time — the cell it sits in is already the date.

There is no prop to turn it off, and that is deliberate: the pill's accessible name has always ended with the time, so a screen-reader user heard "Sprint planning, Monday June 8, 10:00 AM" where a sighted reader saw only "Sprint planning". Making the visible time optional would let that gap be re-created. If the time is not wanted at all, pass the events as allDay — a day cell already says which day it is.

<x-wirekit::event-calendar
    view="month"
    date="2026-06-15"
    aria-label="Team schedule"
    :day-markers="[
        ['date' => '2026-06-19', 'label' => 'Company holiday', 'type' => 'holiday'],
        ['date' => '2026-06-25', 'label' => 'Office closed', 'type' => 'holiday', 'blocked' => true],
    ]"
    :events="[
        ['id' => 1, 'title' => 'Sprint planning', 'start' => '2026-06-08T10:00:00', 'end' => '2026-06-08T11:00:00', 'intent' => 'accent'],
        ['id' => 2, 'title' => 'Design review', 'start' => '2026-06-10T14:00:00', 'end' => '2026-06-10T15:00:00', 'intent' => 'success'],
        ['id' => 3, 'title' => 'Standup', 'start' => '2026-06-12T09:00:00', 'end' => '2026-06-12T09:15:00', 'intent' => 'accent'],
        ['id' => 4, 'title' => 'Release 2.6', 'start' => '2026-06-12T11:00:00', 'end' => '2026-06-12T12:00:00', 'intent' => 'danger'],
        ['id' => 5, 'title' => 'Code review', 'start' => '2026-06-12T14:00:00', 'end' => '2026-06-12T15:00:00', 'intent' => 'success'],
        ['id' => 6, 'title' => 'Retro', 'start' => '2026-06-12T16:00:00', 'end' => '2026-06-12T17:00:00', 'intent' => 'warning'],
        ['id' => 7, 'title' => 'All-hands', 'start' => '2026-06-18T09:00:00', 'end' => '2026-06-18T10:00:00', 'intent' => 'warning'],
        ['id' => 8, 'title' => 'Team offsite', 'start' => '2026-06-22T09:00:00', 'allDay' => true, 'intent' => 'success'],
    ]"
/>

Week View

The time grid positions each event by its start and duration. Overlapping events split into side-by-side columns; a red line marks the current time on today's column. All-day events and day markers sit in a dedicated band above the hour grid (timed events have an hour position; all-day ones do not).

<x-wirekit::event-calendar
    view="week"
    date="2026-06-08"
    aria-label="Weekly schedule"
    :day-markers="[
        ['date' => '2026-06-11', 'label' => 'Holiday', 'type' => 'holiday'],
    ]"
    :events="[
        ['id' => 1, 'title' => 'Standup', 'start' => '2026-06-08T09:00:00', 'end' => '2026-06-08T09:15:00', 'intent' => 'accent'],
        ['id' => 2, 'title' => '1:1 with Sam', 'start' => '2026-06-08T09:15:00', 'end' => '2026-06-08T10:00:00', 'intent' => 'success'],
        ['id' => 3, 'title' => 'Lunch', 'start' => '2026-06-09T12:00:00', 'end' => '2026-06-09T13:00:00'],
        ['id' => 4, 'title' => 'Demo', 'start' => '2026-06-10T15:00:00', 'end' => '2026-06-10T16:30:00', 'intent' => 'warning'],
        ['id' => 5, 'title' => 'Conference', 'start' => '2026-06-10T09:00:00', 'allDay' => true, 'intent' => 'accent'],
        ['id' => 6, 'title' => 'Sprint planning & backlog refinement', 'start' => '2026-06-12T09:00:00', 'end' => '2026-06-12T10:00:00', 'intent' => 'accent'],
        ['id' => 7, 'title' => 'Architecture review with the platform team', 'start' => '2026-06-12T10:00:00', 'end' => '2026-06-12T11:00:00', 'intent' => 'success'],
        ['id' => 8, 'title' => 'Customer onboarding — Acme Corp (kickoff)', 'start' => '2026-06-12T11:00:00', 'end' => '2026-06-12T12:30:00', 'intent' => 'warning'],
        ['id' => 9, 'title' => 'Design critique: checkout flow redesign', 'start' => '2026-06-12T13:00:00', 'end' => '2026-06-12T14:30:00', 'intent' => 'danger'],
    ]"
/>

Agenda View

A compact chronological list — the best view on mobile and for a quick "what's next" glance.

<x-wirekit::event-calendar
    view="agenda"
    date="2026-06-08"
    aria-label="Upcoming events"
    :day-markers="[
        ['date' => '2026-06-11', 'label' => 'Public holiday', 'type' => 'holiday'],
    ]"
    :events="[
        ['id' => 1, 'title' => 'Standup', 'start' => '2026-06-08T09:00:00', 'end' => '2026-06-08T09:30:00', 'intent' => 'accent'],
        ['id' => 2, 'title' => 'Design review', 'start' => '2026-06-08T14:00:00', 'end' => '2026-06-08T15:00:00', 'intent' => 'success'],
        ['id' => 3, 'title' => 'Release 2.6', 'start' => '2026-06-10T16:00:00', 'end' => '2026-06-10T17:00:00', 'intent' => 'danger'],
        ['id' => 4, 'title' => 'Team offsite', 'start' => '2026-06-12T09:00:00', 'allDay' => true],
    ]"
/>

Day Markers

dayMarkers is a day-level dimension, separate from timed events — use it to mark holidays, working exception days, or notes. Each marker carries a date, a label, an optional type, and an optional blocked flag, and renders across all three views: a full-width band in month, a chip in the week all-day band, and its own line in agenda.

<x-wirekit::event-calendar
    view="month"
    date="2026-12-20"
    aria-label="December schedule"
    :day-markers="[
        ['date' => '2026-12-24', 'label' => 'Christmas Eve', 'type' => 'working'],
        ['date' => '2026-12-25', 'label' => 'Christmas Day', 'type' => 'holiday', 'blocked' => true],
        ['date' => '2026-12-26', 'label' => 'Boxing Day', 'type' => 'holiday', 'blocked' => true],
        ['date' => '2027-01-01', 'label' => 'New Year', 'type' => 'holiday', 'blocked' => true],
    ]"
    :events="[
        ['id' => 1, 'title' => 'Year-end sync', 'start' => '2026-12-22T10:00:00', 'end' => '2026-12-22T11:00:00', 'intent' => 'accent'],
    ]"
/>

A blocked day reads as unavailable — a muted surface with a diagonal hatch, plus an "unavailable" suffix in its accessible name, so the state is never conveyed by color or texture alone. WireKit renders the visual and semantic state only; enforce any booking logic in your own application behind a blocked day.

Day-Marker Shape

Week Start

weekStartsOn sets the first column of the month and week grids — 0 for Sunday through 6 for Saturday (1, Monday, is the default). Set it per instance or globally in config/wirekit.php.

<x-wirekit::event-calendar
    view="month"
    date="2026-06-15"
    :week-starts-on="0"
    aria-label="Sunday-start schedule"
    :events="[
        ['id' => 1, 'title' => 'Brunch', 'start' => '2026-06-14T11:00:00', 'end' => '2026-06-14T12:00:00', 'intent' => 'success'],
        ['id' => 2, 'title' => 'Sprint planning', 'start' => '2026-06-15T10:00:00', 'end' => '2026-06-15T11:00:00', 'intent' => 'accent'],
    ]"
/>

Livewire Integration

Pass events from the server and handle clicks (and view changes) in your component:

{{-- 1. Open a detail modal when an event is clicked --}}
<x-wirekit::event-calendar
    :events="$this->events"
    view="month"
    x-on:event-click="$wire.openEvent($event.detail.id)"
    x-on:view-change="$wire.set('view', $event.detail.view)"
/>

// 2. Shape events for the calendar (start/end are ISO 8601)
public function getEventsProperty(): array
{
    return Appointment::query()
        ->whereBetween('starts_at', [now()->startOfMonth(), now()->endOfMonth()])
        ->get()
        ->map(fn ($a) => [
            'id' => $a->id,
            'title' => $a->title,
            'start' => $a->starts_at->toIso8601String(),
            'end' => $a->ends_at?->toIso8601String(),
            'intent' => $a->status === 'confirmed' ? 'success' : 'warning',
        ])
        ->all();
}

// 3. Open the clicked event
public function openEvent(int $id): void
{
    $this->editing = Appointment::find($id);
}

Event Shape

Props

The date the calendar is looking at

The Alpine scope exposes the focused date as focusedDate — a Date, the period the calendar currently shows. It is what the previous/next controls move and what the title is derived from, so a slot inside the component can read it:

<x-wirekit::event-calendar :events="$events">
    <span x-text="focusedDate.getFullYear()"></span>
</x-wirekit::event-calendar>

Accessibility

• Each event is a focusable button with a full accessible label ("Design review, Wednesday June 10, 2:00 PM"), so the schedule is operable without relying on the event's color.

• The week time grid carries tabindex="0" and a focus ring, so the scrolling grid is keyboard-reachable (WCAG 2.1.1) in every configuration.

• The week grid becomes a landmark only when you name it with weekLabel. It gets role="region" and that name, and shows up in a screen reader's landmark list. Without one it stays a plain focusable scroller — because role="region" plus a name is a landmark, and two calendars on one page would otherwise be two landmarks announcing the same thing, which is what axe reports as landmark-unique. It is a separate prop from ariaLabel on purpose: that one names the calendar, and a region borrowing the widget's name would announce the part as the whole.

  <x-wirekit::event-calendar view="week" week-label="Sprint 42 schedule" :events="$events" />
  

  Copy

• The title is an aria-live="polite" region, so navigating months / weeks is announced.

• Today carries aria-current="date" in every view — the month cell, the week column header and the agenda day heading. The accent pill and heavier weight are the visual half; without the attribute, "this is today" would reach a screen reader only as a color, which is what WCAG 1.4.1 rules out.

• The view switcher is a role="radiogroup" of role="radio" buttons with aria-checked + roving tabindex — arrow keys move and select, wrapping at the ends (the buttons own no tabpanels, so tab semantics would be a broken contract).

Keyboard Interaction

The view switcher is a radio group, not a tab list: it takes ONE tab stop, and the arrow keys move the selection inside it. That is why Tab steps past the whole switcher rather than through its three buttons.

Design Tokens

Customization

Set the default view and week start via config/wirekit.php:

'components' => [
    'event-calendar' => [
        'view' => 'week',
        'week-starts-on' => 0, // Sunday
    ],
],

Usage & Conventions

Further Reading

• WAI-ARIA Authoring Practices — Radio Group — the pattern the view switcher implements. This line used to point at the Tabs pattern, which is a different keyboard model and not the one this component follows: a tab list changes what is displayed alongside its own panels, a radio group picks one of a set of values, and the switcher does the second.
• MDN: Intl.DateTimeFormat