Skip to content

Getting started ​

Calends is two packages:

  • @calends/core is plain TypeScript: layouts, navigation, and the date math behind drag and resize. It imports no framework.
  • @calends/vue is the headless Vue primitives built on it.
sh
npm install @calends/vue @calends/core

vue 3.5+ is the only peer dependency. Every primitive takes as and as-child, which work as they do in Reka UI.

Requirements ​

  • Native Temporal at runtime. No polyfill is bundled. If you support browsers without it, load a polyfill yourself before the calendar runs. Without one, CalendarRoot throws an error that says so.
  • TypeScript 6.0 or later for types, with ESNext (or esnext.temporal) in lib. The Temporal types come from TypeScript's own lib, which first has them in 6.0, rather than from a copy Calends ships. Plain JavaScript projects don't need it.

To polyfill only where it's needed, load one before your app mounts:

ts
if (typeof Temporal === 'undefined') {
    await import('temporal-polyfill/global');
}

A first calendar ​

CalendarRoot holds the state and provides it to every primitive inside it. The primitives render the structure and ARIA roles and expose state as data attributes. You supply the markup's styling.

vue
<script setup lang="ts">
import { ref } from 'vue';
import {
    CalendarHeading,
    CalendarNav,
    CalendarRoot,
    EventBar,
    MonthDay,
    MonthGrid,
    MonthWeek,
    MonthWeekday,
} from '@calends/vue';

const date = ref(Temporal.Now.plainDateISO());
const events = [
    { id: 1, title: 'Offsite', start: '2026-10-12', end: '2026-10-14' },
    { id: 2, title: 'Standup', start: '2026-10-15T09:00:00', end: '2026-10-15T09:15:00' },
];
</script>

<template>
    <CalendarRoot
        v-model:date="date"
        :events="events"
        :max-lanes="4"
    >
        <header class="flex items-center gap-2">
            <CalendarNav action="prev">Previous</CalendarNav>
            <CalendarHeading />
            <CalendarNav action="today">Today</CalendarNav>
            <CalendarNav action="next">Next</CalendarNav>
        </header>

        <MonthGrid v-slot="{ weekdays, weeks }">
            <div
                role="row"
                class="grid grid-cols-7"
            >
                <MonthWeekday
                    v-for="weekday in weekdays"
                    :key="weekday.dayOfWeek"
                    :date="weekday"
                />
            </div>

            <MonthWeek
                v-for="week in weeks"
                :key="week.start.toString()"
                :week="week"
                class="grid grid-cols-7"
            >
                <MonthDay
                    v-for="day in week.days"
                    :key="day.date.toString()"
                    :day="day"
                    class="relative min-h-28 data-outside:opacity-50 data-today:font-bold"
                >
                    {{ day.date.day }}

                    <EventBar
                        v-for="segment in day.segments"
                        v-slot="{ event }"
                        :key="segment.event.id"
                        :segment="segment"
                        class="absolute top-[calc(1.75rem+var(--event-lane)*1.5rem)] h-5 w-[calc(var(--event-span)*100%)] data-highlighted:bg-blue-200"
                    >
                        {{ event.source.title }}
                    </EventBar>
                </MonthDay>
            </MonthWeek>
        </MonthGrid>
    </CalendarRoot>
</template>

That's a working month view. For a finished one, start from a recipe: a styled, copy-in component built on these primitives, like the one on the month view page.

Events ​

Pass any objects with an id and a start. Extra fields (like title) are left alone and come back to you as event.source.

FieldTypeNotes
idstring | numberRequired, and unique.
startISO string, Date, or a Temporal valueRequired.
endSame as start, optionalInclusive last day for all-day events, exclusive end for timed ones.
allDayboolean, optionalDefaults to true when start is a date with no time.

Strings with an offset or Z are instants, moved into the calendar's time zone. Strings without one are wall-clock times already in it. A timed event that ends exactly at midnight doesn't spill into the next day.

Calends doesn't expand recurring events. Pass the instances you want shown, for the range in view. The month grid pads its weeks with days from the months either side, and visibleMonthRange covers them (give it the same week-starts-on and fixed-weeks as the calendar). CalendarRoot's slot has the same range as visible-range, for whichever view is showing.

ts
import { computed } from 'vue';
import { visibleMonthRange } from '@calends/core';

const events = computed(() => {
    const { start, end } = visibleMonthRange(date.value);
    const standups = [];

    for (let day = start; Temporal.PlainDate.compare(day, end) <= 0; day = day.add({ days: 1 })) {
        if (day.dayOfWeek === 1) {
            const at = day.toPlainDateTime('09:00');

            standups.push({
                id: `standup-${day}`,
                title: 'Standup',
                start: at.toString(),
                end: at.add({ minutes: 15 }).toString(),
            });
        }
    }

    return [...oneOffEvents.value, ...standups];
});

For RRULE strings, a library like rrule does the same job: expand the rule between the range's ends, and give each instance its own id.

CalendarRoot props ​

PropTypeDefaultWhat it does
v-model:dateTemporal.PlainDatetodayAny day in the period shown.
eventsreadonly T[][]See Events.
view'month' | 'week' | 'day''month'The period navigation pages by. A month's last day pages to the next month's last day, so Jan 31 doesn't drift.
week-starts-on1–7 (ISO: 1 is Monday, 7 is Sunday)7
time-zoneIANA zone stringthe runtime's zoneWhere timed events are placed.
localeBCP 47 stringthe runtime'sFor titles, weekday names, and labels.
todayTemporal.PlainDatefrom nowOverride for data-today, past events, and the today button. The now line stays on now's date.
nowTemporal.ZonedDateTimethe clockOverride for the current time, for the now line and past timed events. See Server rendering.
fixed-weeksbooleanfalseAlways draw six weeks in the month grid.
max-lanesnumberunlimitedLanes per month week, counting the "+N more" lane.
resourcesreadonly { id }[]Rows for the resource and timeline views.
get-resource-ids(event: T) => idsWhich resources an event belongs to.
unassignedbooleanfalseAdds a row for events that match no resource.
slot-min-minutesnumber0Start of the time grid and timeline's daily window, in minutes from midnight.
slot-max-minutesnumber1440End of that window.
slot-minutesnumber60Minutes per timeline header slot.
gantt-scale'day' | 'week' | 'month''week'Column width of the Gantt view.
gantt-linksreadonly { id, from, to, kind? }[]Dependency and related lines between Gantt rows.
editablebooleanfalseLets events be moved and resized.
selectablebooleanfalseLets people drag across empty space to select a range.
snap-minutesnumber15What timed drags and selections snap to.
can-edit(event: T) => booleanall eventsLimits editing to some events.
as / as-child'div'The rendered element, as in Reka UI.

It emits event-drop, event-resize, and range-select. The calendar never changes events: your app applies the change, then passes the updated events back in. See Interactions.

Its default slot gets:

Slot propTypeWhat it is
dateTemporal.PlainDateThe bound date.
titlestringThe period's title in locale, as CalendarHeading shows it.
visible-range{ start, end }The first and last days on screen: whole weeks in the month view, the period otherwise. Use it to fetch events.
prev / next() => voidPage back or forward by the view.
go-to-today() => voidJump to today.

Server rendering ​

By default, the current time comes from the rendering machine's clock and time zone, so a server and a browser can disagree about today, which events are past, and where the now line sits. To hydrate cleanly, pass time-zone and a now the server and the client share, or render the calendar on the client only. today and the starting date follow now unless you set them.

With Nuxt, for example, useState carries the server's value to the client:

ts
const timeZone = 'America/Chicago';
const nowIso = useState('calendar-now', () => Temporal.Now.zonedDateTimeISO(timeZone).toString());
const now = computed(() => Temporal.ZonedDateTime.from(nowIso.value));

const tick = () => (nowIso.value = Temporal.Now.zonedDateTimeISO(timeZone).toString());
let timer: ReturnType<typeof setInterval>;

onMounted(() => {
    tick();
    timer = setInterval(tick, 60_000);
});
onUnmounted(() => clearInterval(timer));
html
<CalendarRoot
    :time-zone="timeZone"
    :now="now"
></CalendarRoot>

now replaces the clock, so the calendar stops ticking on its own. The update after mounting keeps the now line moving.

Released under the MIT License.