php artisan aura:add calendar

composer require bluestarsystem/aura-ui
php artisan aura:install

• Overview
• Basic Usage
• Props
  • Event Object Structure
• Views
  • Month View
  • Week View
  • Day View
• Examples
  • Sunday as First Day
  • Italian Locale
  • Custom Business Hours
  • Livewire Integration
  • Color-Coded Categories
• Slots
• Accessibility

Need interactivity (drag, click-to-create)? See the Pro Scheduler.

Overview#

The Calendar component renders an interactive calendar with three views: month, week, and day. Events are shown as colored labels on their respective dates. It supports configurable locale for month/day names, start of week (Monday or Sunday), custom event field mapping, and timed events with business hours. Built with Alpine.js for smooth navigation and view switching.

Basic Usage#

<x-aura::calendar :events="[
    ['title' => 'Team Meeting', 'date' => now()->format('Y-m-d'), 'color' => 'blue'],
    ['title' => 'Product Launch', 'date' => now()->addDays(2)->format('Y-m-d'), 'color' => 'green'],
    ['title' => 'Deadline', 'date' => now()->addDays(5)->format('Y-m-d'), 'color' => 'red'],
]" />

<x-aura::calendar :events="$events" />

Props#

Event Object Structure#

Each event in the events array should follow this structure:

// All-day event (shown in month grid and all-day section in week/day views)
[
    'title' => 'Team Meeting',
    'date' => '2026-02-15',      // YYYY-MM-DD format
    'color' => 'blue',           // Optional: CSS color name, hex, or Aura color name
]

// Timed event (shown in time grid in week/day views)
[
    'title' => 'Standup',
    'date' => '2026-02-15',
    'start' => '09:00',          // HH:MM format
    'end' => '09:30',            // Optional: HH:MM format
    'color' => '#6366f1',
]

Views#

The calendar supports three views, switchable via the view switcher in the header:

Month View#

Displays a full month grid with 6 weeks. Events appear as colored pills on their dates.

<x-aura::calendar
    view="month"
    :events="[
        ['title' => 'Sprint Planning', 'date' => now()->format('Y-m-d'), 'color' => 'blue'],
        ['title' => 'Design Review', 'date' => now()->addDays(2)->format('Y-m-d'), 'color' => 'purple'],
        ['title' => 'Product Launch', 'date' => now()->addDays(4)->format('Y-m-d'), 'color' => 'green'],
    ]"
/>

<x-aura::calendar view="month" :events="$events" />

Week View#

Displays the current week with day columns and a time grid. All-day events appear at the top. Timed events are positioned in the hour grid.

<x-aura::calendar
    view="week"
    :events="[
        ['title' => 'All-Day Workshop', 'date' => now()->format('Y-m-d'), 'color' => 'purple'],
        ['title' => 'Standup', 'date' => now()->format('Y-m-d'), 'start' => '09:00', 'end' => '09:30', 'color' => 'blue'],
        ['title' => 'Lunch Meeting', 'date' => now()->addDay()->format('Y-m-d'), 'start' => '12:00', 'end' => '13:00', 'color' => 'green'],
        ['title' => 'Code Review', 'date' => now()->addDays(2)->format('Y-m-d'), 'start' => '15:00', 'end' => '16:00', 'color' => 'orange'],
    ]"
/>

<x-aura::calendar view="week" :events="$events" />

Day View#

Displays a single day with a time grid. All-day events appear at the top. Timed events are positioned in the hour grid.

<x-aura::calendar
    view="day"
    :events="[
        ['title' => 'Team Offsite', 'date' => now()->format('Y-m-d'), 'color' => 'purple'],
        ['title' => 'Morning Standup', 'date' => now()->format('Y-m-d'), 'start' => '09:00', 'end' => '09:15', 'color' => 'blue'],
        ['title' => 'Design Sprint', 'date' => now()->format('Y-m-d'), 'start' => '10:00', 'end' => '12:00', 'color' => 'green'],
        ['title' => 'Lunch', 'date' => now()->format('Y-m-d'), 'start' => '12:30', 'end' => '13:30', 'color' => 'orange'],
        ['title' => '1:1 with Manager', 'date' => now()->format('Y-m-d'), 'start' => '14:00', 'end' => '14:30', 'color' => 'red'],
    ]"
/>

<x-aura::calendar view="day" :events="$events" />

Examples#

Sunday as First Day#

<x-aura::calendar
    :startOfWeek="0"
    :events="[
        ['title' => 'Standup', 'date' => now()->format('Y-m-d'), 'color' => 'blue'],
        ['title' => 'Review', 'date' => now()->addDays(2)->format('Y-m-d'), 'color' => 'green'],
    ]"
/>

<x-aura::calendar
    :startOfWeek="0"
    :events="$events"
/>

Italian Locale#

<x-aura::calendar
    locale="it"
    :events="[
        ['title' => 'Riunione di squadra', 'date' => now()->format('Y-m-d'), 'color' => 'blue'],
        ['title' => 'Lancio prodotto', 'date' => now()->addDays(2)->format('Y-m-d'), 'color' => 'green'],
        ['title' => 'Scadenza progetto', 'date' => now()->addDays(4)->format('Y-m-d'), 'color' => 'red'],
    ]"
/>

<x-aura::calendar
    locale="it"
    :events="$events"
/>

Custom Business Hours#

Display an extended time range for businesses that operate early mornings or late evenings.

<x-aura::calendar
    view="day"
    :businessHoursStart="6"
    :businessHoursEnd="23"
    :events="[
        ['title' => 'Early Shift', 'date' => now()->format('Y-m-d'), 'start' => '06:00', 'end' => '07:00', 'color' => 'blue'],
        ['title' => 'Evening Class', 'date' => now()->format('Y-m-d'), 'start' => '21:00', 'end' => '22:30', 'color' => 'purple'],
    ]"
/>

<x-aura::calendar
    view="day"
    :businessHoursStart="6"
    :businessHoursEnd="23"
    :events="$events"
/>

Livewire Integration#

<!-- Blade view -->
<div>
    <x-aura::calendar
        :events="$events"
        locale="en"
    />
</div>

// Livewire component
class AppointmentCalendar extends Component
{
    public array $events = [];

    public function mount(): void
    {
        $this->loadEvents();
    }

    private function loadEvents(): void
    {
        $this->events = Appointment::query()
            ->get()
            ->map(fn ($apt) => [
                'title' => $apt->customer->name,
                'date' => $apt->starts_at->format('Y-m-d'),
                'start' => $apt->starts_at->format('H:i'),
                'end' => $apt->ends_at->format('H:i'),
                'color' => $apt->status->color(),
            ])
            ->toArray();
    }
}

Color-Coded Categories#

<x-aura::calendar :events="[
    ['id' => 1, 'title' => 'Meeting', 'date' => now()->format('Y-m-d'), 'color' => 'blue'],
    ['id' => 2, 'title' => 'Deadline', 'date' => now()->addDays(2)->format('Y-m-d'), 'color' => 'red'],
    ['id' => 3, 'title' => 'Holiday', 'date' => now()->addDays(5)->format('Y-m-d'), 'color' => 'green'],
    ['id' => 4, 'title' => 'Training', 'date' => now()->addDays(7)->format('Y-m-d'), 'color' => 'yellow'],
]" />

<x-aura::calendar :events="[
    ['id' => 1, 'title' => 'Meeting', 'date' => '2026-02-15', 'color' => 'blue'],
    ['id' => 2, 'title' => 'Deadline', 'date' => '2026-02-17', 'color' => 'red'],
    ['id' => 3, 'title' => 'Holiday', 'date' => '2026-02-20', 'color' => 'green'],
    ['id' => 4, 'title' => 'Training', 'date' => '2026-02-22', 'color' => 'yellow'],
]" />

Slots#

The calendar renders its own internal UI for navigation controls (previous/next, view switcher) and event display. Customize appearance through Tailwind classes on the wrapper or via CSS variables.

Accessibility#

• Navigation buttons (previous, next, today) are keyboard accessible with dynamic labels that reflect the current view.
• View switcher buttons have descriptive aria-labels (Month view, Week view, Day view).
• Events are displayed with their title as text content.
• The calendar uses a semantic grid layout with day headers.
• Month navigation preserves keyboard focus.
• Event colors provide additional visual categorization.
• Week and day views include an all-day section and a scrollable time grid with hour labels.