Event Calendar

Installation#

# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add event-calendar

Usage#

import { EventCalendar, type CalendarEvent } from "@/components/ui/event-calendar"

const initial: CalendarEvent[] = [
  { id: "1", title: "Standup", start: new Date(2026, 9, 12, 9, 30), end: new Date(2026, 9, 12, 9, 45), color: "neutral" },
  { id: "2", title: "Offsite", start: new Date(2026, 9, 19), end: new Date(2026, 9, 21), allDay: true, color: "info" },
]

export function Schedule() {
  const [events, setEvents] = React.useState(initial)
  return (
    <EventCalendar
      events={events}
      onEventChange={(next) => setEvents((all) => all.map((ev) => (ev.id === next.id ? next : ev)))}
    />
  )
}

Anatomy#

import {
  EventCalendar,
  EventCalendarHeader,
  EventCalendarTitle,
  EventCalendarNav,
  EventCalendarViewSwitch,
  EventCalendarBody,
} from "@/components/ui/event-calendar"

<EventCalendar>
  <EventCalendarHeader>
    <EventCalendarTitle />
    <EventCalendarNav />
    <EventCalendarViewSwitch />
  </EventCalendarHeader>
  <EventCalendarBody />
</EventCalendar>

Drag, resize and keys#

In the week and day grid, drag an event to another time or day, or pull its top or bottom edge to change its length, in steps of snapMinutes. Events that overlap sit side by side. The event in hand lifts and glides from step to step, a dashed outline marks where it came from, the events around it stay put, and the grid scrolls when you reach its edge. Escape puts it back. A press without movement is still a click. Nothing changes until you let go: then onEventChange gets the updated event, and you write it back into events. With an event focused, the arrow keys do the same: up and down move it by snapMinutes, left and right by a day, and Shift with up or down changes its length. Click empty space to create an event through onSlotClick.

Month#

Timed events show as a dot, a time and a title; all-day events as a tinted bar, listed first. A day with more than maxEventsPerDay ends in "+N more", which opens that day. Drag an event to another cell, or move it with the arrow keys: a day sideways, a week up or down. Click a day number to open that day.

Day#

One column fits a sidebar or a phone. Pass a single entry to views and the view switch goes away.

Read only#

editable={false} turns off dragging and the keys; events still open through onEventClick. The header is made of parts: this one leaves out the view switch. startHour, endHour and hourHeight fit a working day into a shorter card.

Colours#

color tints the block and its bar with one of the theme's roles, so events stay readable in all four themes. Without it, an event uses brand.

API reference#

FAQ#