Skip to content

OrigamCalendar ​

Full in-house calendar component. Four views (month, week, day, agenda), an integrated toolbar with view-switcher, drag-select on the grid to request new events, and RRULE-driven recurring events. Zero external dependency — no FullCalendar, no Vue-Cal, no event-source. SSR-safe.

The four views ​

ViewWhat you see
month6×7 grid; each cell shows up to 3 event chips with a "+N more" overflow.
week7-column vertical timeline; events absolute-positioned by start/duration.
daySame as week but for a single day (full width per event).
agendaFlat list grouped by day. Empty days are skipped.

Quick start ​

vue
<template>
    <origam-calendar
        v-model:view="view"
        v-model:current-date="currentDate"
        :events="events"
        :first-day-of-week="1"
        :time-format="'24h'"
        locale="fr-FR"
        :selectable="true"
        :category-colors="{ meeting: 'primary', focus: 'success' }"
        @event-click="onEventClick"
        @date-click="onDateClick"
        @range-select="onRangeSelect"
        @create-event-request="onCreateRequest"
    />
</template>

<script setup lang="ts">
    import { ref } from 'vue'

    const view = ref<'month' | 'week' | 'day' | 'agenda'>('month')
    const currentDate = ref(new Date())
    const events = [
        { id: 1, title: 'Standup', start: '2026-05-14T10:00', end: '2026-05-14T10:15', category: 'meeting' }
    ]
</script>

Props ​

PropTypeDefaultNotes
view'month' | 'week' | 'day' | 'agenda''month'v-model:view.
currentDateDate | stringnew Date()v-model:currentDate.
eventsIEvent[][]Recurring events expanded internally to the visible range.
firstDayOfWeek0..610 = Sunday, 1 = Monday, 6 = Saturday.
timeFormat'12h' | '24h''24h'Drives hour-label rendering in week / day views.
localestringautoBCP 47 tag — falls back to <html lang> and 'en-US'.
selectablebooleantrueEnables click + drag-select on cells / slots.
eventColorKey'category' | 'color' | string'category'Which IEvent prop drives the chip colour.
categoryColorsRecord<string, TIntent | string>{}Map category → intent (token) or raw CSS colour.
weekendHighlightbooleantrueTint Sat/Sun cells.
showWeekNumbersbooleanfalseISO week-number column on the left of the grid.
dayStartHournumber0First hour rendered in week / day views.
dayEndHournumber24Last hour rendered in week / day views.
slotDurationnumber (minutes)30Granularity of the timeline rows + drag-create resolution.
minDateDate | string—Lower navigation bound (disables <).
maxDateDate | string—Upper navigation bound (disables >).
disabledDatesArray<Date | string> | (d: Date) => boolean—Cells to grey out.

Cross-cutting surface ​

Like every other origam component, the calendar carries the standard Commons surface — consumed through the shared composables, so it paints / sizes / spaces consistently with the rest of the system.

PropTypeDefaultNotes
bgColorTIntent | <css-color>—Paints the header band (toolbar + weekday row). Day cells keep their own light surface.
colorTIntent | <css-color>—Drives the text colour. On the painted header it auto-contrasts; on the day cells it applies directly.
roundedTRounded | number | string | boolean8pxCorner radius (root). overflow:hidden clips the grid to it.
elevationnumber / shadow rung—Drop shadow rung.
border'thin' | 'thick' | number | string | boolean1pxBorder width.
borderColorTIntent | <css-color>subtleIntent keywords resolve to their token.
borderStyle'solid' | 'dashed' | 'dotted' | …solidBorder style.
density'default' | 'compact' | 'comfortable'—Compresses / expands toolbar padding + day-cell height.
width / height / minWidth / maxWidth / minHeight / maxHeightnumber | string—Root dimensions.
padding* / margin*number | string—Use a CSS unit (40px, 1rem); a bare number string is ignored.

Contrast is region-aware. bgColor paints only the header band, never the day cells. The header text always contrasts that painted surface (readability wins), while the day cells — which keep their light surface — render color directly. So color="primary" + bgColor="primary" gives a primary header with white text and primary-tinted day numbers, instead of bleeding white text onto the white cells. With no bgColor, the header adopts color like the body.

Emits ​

EventPayloadNotes
update:viewTCalendarViewTwo-way binding for the toolbar tabs.
update:currentDateDateTwo-way binding for navigation + keyboard arrows.
event-click(event: IEvent, dom: MouseEvent)Fires when a chip / timeline event / agenda row is clicked.
date-click(date: Date)Fires on a single cell / slot click that wasn't part of a drag.
range-select(start: Date, end: Date)Fires on mouseup after a drag spans at least 2 cells / slots.
create-event-request(start: Date, end: Date)Convenience alias of range-select — wire your "create event" modal here.
view-changeTCalendarViewConvenience — re-emits update:view.
navigate'prev' | 'next' | 'today'Fires before the side-effect on currentDate.

IEvent interface ​

ts
interface IEvent {
    id: string | number
    title: string
    description?: string
    start: string | Date              // ISO 8601 strings accepted
    end?: string | Date
    allDay?: boolean
    category?: string                 // used as the categoryColors key
    color?: TIntent | string          // direct override
    rrule?: string                    // RRULE subset — see below
    metadata?: Record<string, unknown>
}

RRULE subset ​

<OrigamCalendar> ships a minimal in-house RRULE parser. The subset handles 95% of business-calendar patterns ("every Monday/Wednesday at 10am", "the 14th of every month", "every 2 weeks until July") without dragging in rrule.js.

DirectiveSupported
FREQDAILY / WEEKLY / MONTHLY
INTERVALYes
COUNTYes
UNTILYes (YYYYMMDD or YYYYMMDDTHHMMSSZ)
BYDAYYes (only for FREQ=WEEKLY)
BYMONTHNo — ignored
BYMONTHDAYNo — ignored
BYSETPOSNo — ignored
WKSTNo — ignored
EXDATENo — ignored

A safety net caps expansion at 1 098 occurrences (3 years of daily events) so a malformed FREQ=DAILY without COUNT / UNTIL can't run away.

Composable — useCalendar ​

ts
import { useCalendar } from '@origam/composables'

const cal = useCalendar(
    {
        events: () => events.value,
        view: () => view.value,
        currentDate: () => currentDate.value,
        firstDayOfWeek: () => 1,
        slotDuration: () => 30,
        dayStartHour: () => 0,
        dayEndHour: () => 24
    },
    (next) => view.value = next,
    (next) => currentDate.value = next
)

cal.visibleDateRange.value       // { start: Date, end: Date }
cal.expandedEvents.value         // events expanded via RRULE + filtered
cal.navigate('next')             // 'prev' | 'next' | 'today'
cal.setView('week')
cal.buildMonthGrid(date)         // Date[][] — 6 × 7
cal.buildWeekGrid(date)          // ICalendarTimeSlot[][] — 7 × N
cal.buildDayGrid(date)           // ICalendarTimeSlot[]
cal.buildAgenda(range?)          // [{ date, events }]
cal.eventsOnDay(date)            // IEvent[]
cal.positionEvent(event, dayStart, pxPerMin)  // { top, height }

Slots ​

SlotScoped bindingsNotes
header{ view, title, canPrev, canNext, setView, navigate }Replace the built-in toolbar (title + nav + view switcher).
event{ event, view, isPast, isToday }Replace the event card body. Rendered for every visible event in month/week/day/agenda views.
day{ date, events, isToday, isPast, isOutside, isWeekend, isDisabled }Replace a month-view day cell content (the date label + events chips).
dayHeader{ date }Replace a day header (week / day views).
empty{ view }Rendered when the agenda view has no events in range.
vue
<origam-calendar :events="events">
    <template #header="{ title, navigate, setView }">
        <my-toolbar :title="title" @prev="navigate('prev')" @next="navigate('next')" />
    </template>

    <template #event="{ event, isPast }">
        <my-event-card :event="event" :dim="isPast" />
    </template>

    <template #day="{ date, events }">
        <my-day-cell :date="date" :events="events" />
    </template>

    <template #dayHeader="{ date }">
        <my-day-header :date="date" />
    </template>

    <template #empty>
        <my-empty-state>Create your first event</my-empty-state>
    </template>
</origam-calendar>

Accessibility ​

  • Root: role="application" + aria-label="Calendar".
  • Toolbar: role="toolbar".
  • View switcher: role="group" (named via aria-label) wrapping native <button type="button" aria-pressed> toggle buttons — deliberately not a tablist. Each view is its own tab stop (no roving tabindex): a tablist would owe its user ←/→ between tabs, but those keys are already claimed by date navigation (see below), and only the active view has a DOM node to point aria-controls at (v-if, not v-show). See OrigamCalendar.aria.spec.ts for the full reasoning — that file is the guard against silently reintroducing role="tab".
  • Month grid: role="grid" > role="row" > role="gridcell", full aria-label per day (weekday, month, day, year). Roving tabindex: exactly ONE day cell is a tab stop (tabindex="0", matching currentDate) — every other cell is tabindex="-1", per the WAI-ARIA APG grid pattern. Pressing an arrow key moves both the tab stop AND real DOM focus to the new cell.
  • Event chips: native <button type="button"> + aria-label combining title + start time.
  • Keyboard, when focus is on a day cell:
    • ← / → move the current date by 1 day (and moves focus with it).
    • ↑ / ↓ move it by 7 days (and moves focus with it).
    • Page Up / Page Down move it by 1 month (and moves focus with it).
    • Enter / Space activate the focused day cell (same effect as clicking it — fires date-click unless the cell is disabled).

i18n ​

Weekday and month names come from Intl.DateTimeFormat(locale, …). Pass the BCP 47 tag via the locale prop, or leave it unset and the calendar will read <html lang> (defaulting to 'en-US').

Time labels follow timeFormat ('12h' / '24h'). The locale's AM/PM marker is honoured automatically — passing locale="fr-FR"

  • timeFormat="12h" will still render 1:00 PM style labels because French speakers reading mixed-locale calendars expect it.

Tokens ​

Component-level CSS variables are declared in packages/ds/src/assets/css/tokens/light.css and dark.css (SCSS twins under packages/ds/src/assets/scss/tokens/), under the --origam-calendar---* prefix. Override them on <OrigamThemeProvider> or a single instance via inline style.

Notable variables:

  • --origam-calendar---background-color
  • --origam-calendar__day-cell---bg-color-today
  • --origam-calendar__day-cell---bg-color-weekend
  • --origam-calendar__day-cell---bg-color-hover — mouse hover on a non-disabled, non-today day cell (the cell already carries cursor: pointer and is keyboard-focusable; hover now matches that affordance)
  • --origam-calendar__event---bg-color-default
  • --origam-calendar__timeline---slot-height
  • --origam-calendar__range-select---bg-color
  • --origam-calendar__week-number---color

Performance ​

The calendar is intentionally un-virtualised. The 42-cell month grid is always rendered (≈ 50ms paint cost). The week view emits 24 × 2 = 48 slot rows × 7 cols = 336 nodes; the day view caps at 48 rows.

For schedules with ≥ 500 distinct events per visible window:

  1. Pre-filter events in the parent (the calendar will still expand recurring events to the visible window — but smaller events means less to expand).
  2. Consider switching to the agenda view (no grid math, no absolute-positioning maths per event).

A virtualised week timeline is on the roadmap but isn't a v1 concern.