@nomideusz/svelte-calendar v1.8.2

A themeable Svelte 5 calendar: day and week Planner time grids, a multi-week Scroll view, Agenda lists, a Month grid and touch-first Mobile layouts, with drag to move, resize and create events, timezones, a headless API, an embeddable web component, and a smart auto-theme that adapts to any page.

Installation#

pnpm add @nomideusz/svelte-calendar

Requirements:

• Svelte ^5.29.0 (peer dependency: the package uses attachments, {@attach}).
• Runtime dependencies (installed for you): date-fns, date-fns-tz, @chenglou/pretext.
• Node ≥ 22 is only needed to develop the package itself, not to use it.

Quick Start#

<script>
  import { Calendar, createMemoryAdapter } from '@nomideusz/svelte-calendar';

  // Today at a given hour, so the events land in the week the calendar opens on
  const today = new Date();
  const at = (hour) => new Date(today.getFullYear(), today.getMonth(), today.getDate(), hour);

  let events = $state([
    { id: '1', title: 'Team Sync', start: at(9),  end: at(10) },
    { id: '2', title: 'Lunch',     start: at(12), end: at(13) },
  ]);
  // A new adapter whenever the events change; the calendar reloads without blanking
  const adapter = $derived(createMemoryAdapter(events));

  // Drag on empty time (or press Enter on a day column) to create
  function create({ start, end }) {
    events = [...events, { id: crypto.randomUUID(), title: 'New event', start, end }];
  }
  // Drag an event to move it, or its edge to resize it
  function move(event, start, end) {
    events = events.map((e) => (e.id === event.id ? { ...e, start, end } : e));
  }
</script>

<Calendar {adapter} view="week-planner" oneventcreate={create} oneventmove={move} />

That's a working, editable calendar. The calendar stores nothing on create: without oneventcreate, dragging on empty time does nothing. Moves and resizes write to the adapter by themselves, and oneventmove keeps your own data in step, so a move survives the next new adapter. The default auto theme probes your page's background, accent color and fonts, so the calendar adapts to any design. Events without a color draw in ink; to color them automatically, give the adapter a palette.

Views#

Without view the calendar opens on day-planner, the first registered view. The Quick Start, the demo, the widget and createCalendar open on week-planner, so pass view="week-planner" for the week grid.

The default registry (defaultViews) holds eight views. Six are the ones you choose with view; the two *-mobile views are what the others swap to in a narrow container (see Mobile), so the demo's view list shows six.

<Calendar {adapter} view="week-planner" />
<Calendar {adapter} view="week-scroll" />
<Calendar {adapter} view="month-grid" />

Users switch with the built-in pills: Day / Week / Month for the mode, plus view-type pills (Planner / Scroll / Agenda) when a mode has more than one view. Hide them when your app controls the view (view stays reactive after mount):

<Calendar {adapter} view="day-planner" showModePills={false} />

Planner views are designed for direct manipulation:

• Move: drag an event to another day or time; a ghost previews the target before the move commits.
• Resize: drag an event's top/bottom grip to change its duration; minDuration/maxDuration clamp the result.
• Create: press on empty canvas and sweep to draw a range, or click for a default-length slot. Both go through the same validation (blocked slots, disabled dates, minDuration/maxDuration) and then fire oneventcreate.
• External drop: an HTML5 drag from outside the calendar (a class chip, a template) dropped on the planner or week-scroll fires onexternaldrop({ start, dataTransfer }).

week-scroll supports move, click-to-create and external drops. In week-agenda with columns and an oneventmove handler, a card can be dragged to another day (it keeps its time of day); that move goes straight to oneventmove without writing the adapter.

The month grid shows up to three chips per day. Clicking a day or its "+N more" fires ondayclick(date); without ondayclick it opens that date in a day view (the day view of the type you last used).

Keyboard#

When focus is inside the calendar:

• t: go to today.
• ← / →: previous / next period (mirrored in RTL). Ignored while typing in a field or inside a pill group, where arrows move between pills.
• In month-grid: arrow keys move between days, Enter / Space opens the focused day (ondayclick).
• In week-planner / day-planner: the day columns are one tab stop; ← / → move between days, Enter / Space creates an event (oneventcreate) at the next slot today, or 09:00. On a focused event, Alt+↑ / Alt+↓ move it one snapInterval, Alt+← / Alt+→ move it a day, and Alt+Shift+↑ / Alt+Shift+↓ move its end; each goes through the same validation as a drag and fires oneventmove.

Custom Views#

The views prop replaces the registry. Spread defaultViews to add your own view and keep the built-ins:

<script lang="ts">
  import { Calendar, defaultViews, type CalendarView } from '@nomideusz/svelte-calendar';
  import KanbanDay from './KanbanDay.svelte';

  const views: CalendarView[] = [
    ...defaultViews,
    { id: 'day-kanban', label: 'Kanban', mode: 'day', component: KanbanDay, props: { columns: 3 } },
  ];
</script>

<Calendar {adapter} {views} view="day-kanban" />

A CalendarView is { id, label, mode: 'day' | 'week' | 'month', component, props? }. label names the view-type pill; views sharing a label across modes are what the Day/Week/Month pills switch between.

The component receives CalendarViewProps (plus your props); declare only the ones it uses:

<!-- KanbanDay.svelte -->
<script lang="ts">
  import { useCalendarContext, type CalendarViewProps } from '@nomideusz/svelte-calendar';

  let { events, oneventclick, columns = 3 }:
    Pick<CalendarViewProps, 'events' | 'oneventclick'> & { columns?: number } = $props();

  const ctx = useCalendarContext(); // viewState, drag, labels, config…
</script>

<h3>{ctx.labels.today}</h3>
{#each events as ev (ev.id)}
  <button onclick={() => oneventclick(ev)}>{ev.title}</button>
{/each}

useCalendarContext() (type CalendarContext) gives a view the running Calendar's engines and config: viewState, drag, commitDrag, labels, readOnly, snapInterval, minColumnWidth, blockedSlots, disabledDates / disabledSet, minDuration / maxDuration, hideDays, equalDays, showDates, compact, columns, isMobile, autoHeight, timezone, oneventmove, oneventhover, ondayclick, eventSnippet, emptySnippet, dayHeaderSnippet and loadRange (a view can widen the range the store loads). Call it at component init, inside a <Calendar>.

The raw view components (Planner, PlannerScroll, Agenda, Mobile, MonthGrid) are exported so you can register them under your own ids. Building blocks for custom views are exported as primitives: EventBlock (an event card), TimeGutter (hour labels), DayHeader, NowIndicator, EmptySlot (click-to-create target) and FloatingPanel (see Event details panel).

Mobile#

When the calendar's container is narrower than 768px, it swaps to touch-first Mobile views with swipe navigation and a compact header:

<!-- Auto-detect (default): switches at a 768px container width -->
<Calendar {adapter} view="week-planner" />

<!-- Force mobile layout -->
<Calendar {adapter} mobile={true} />

<!-- Force desktop layout -->
<Calendar {adapter} mobile={false} />

• MobileDay: vertical time grid with hour labels, swipe left/right to change days, all-day chips at the top, tap-to-create, stable columns for overlapping events.
• MobileWeek: vertical day list with relative labels (Today, Tomorrow, …) and accessible event buttons in each row.

In mobile mode every view except *-agenda and *-mobile is swapped for the {mode}-mobile entry of the same mode when one is registered, custom views included. Agenda views keep their list layout; month-grid has no mobile entry and stays. The mobile header shows only the Day/Week/Month pills.

With 'auto', the first render (and the server render) is the desktop layout; the container is measured on mount, so SSR hydrates cleanly.

Callbacks#

<Calendar
  {adapter}
  oneventclick={(event, anchor) => console.log('Clicked', event.title, anchor)}
  oneventcreate={(range) => console.log('New slot', range.start, range.end)}
  oneventmove={(event, start, end) => console.log('Moved', event.title, start, end)}
  onexternaldrop={({ start, dataTransfer }) => console.log('Dropped', start, dataTransfer.getData('text/plain'))}
  onviewchange={(viewId) => console.log('View', viewId)}
  ondatechange={(date) => console.log('Date', date)}
  ondayclick={(date) => console.log('Day', date)}
  onerror={(error) => console.error('Calendar', error)}
/>

oneventcreate, oneventmove and onexternaldrop receive real instants, also with timezone. None of the write callbacks fire when readOnly is set.

To show a newly created or moved event, update your data and give the Calendar a new adapter. The store reloads on a new adapter identity without blanking the grid:

<script lang="ts">
  import { Calendar, createMemoryAdapter, type TimelineEvent } from '@nomideusz/svelte-calendar';

  let events = $state<TimelineEvent[]>([]);
  const adapter = $derived(createMemoryAdapter(events));
</script>

<Calendar
  {adapter}
  oneventcreate={({ start, end }) => (events = [...events, { id: crypto.randomUUID(), title: 'New', start, end }])}
/>

Read-only#

Set readOnly to disable drag, resize, click-to-create and external drops:

<Calendar {adapter} readOnly />

To lock single events, set data.readOnly: true on them: views refuse to move or resize those events, which can still be clicked. The recurring adapter uses this for its projected occurrences.

Event details panel#

FloatingPanel is a non-modal panel that opens beside the clicked block's rect (to its right, or left near the viewport edge), can be dragged by its header, and becomes a bottom sheet below a 640px viewport. Escape, its close button or a click outside closes it; the outside click is spent on closing, so it doesn't also open the event under it.

<script lang="ts">
  import { Calendar, FloatingPanel, type TimelineEvent } from '@nomideusz/svelte-calendar';

  let open = $state<{ ev: TimelineEvent; anchor?: DOMRect } | null>(null);
</script>

<Calendar {adapter} oneventclick={(ev, anchor) => (open = { ev, anchor })} />

{#if open}
  <FloatingPanel title={open.ev.title} anchor={open.anchor} onclose={() => (open = null)}>
    <p>{open.ev.location}</p>
  </FloatingPanel>
{/if}

More options#

Hide nav controls (prev/next/today) and treat all days equally (no past-day dimming):

<!-- Fixed weekly schedule, no browsing, all days equal -->
<Calendar
  {adapter}
  view="week-agenda"
  readOnly
  showNavigation={false}
  showDates={false}
  equalDays
/>

Hide weekends for a workweek view:

<Calendar {adapter} view="week-planner" hideDays={[6, 7]} />

Control which date the calendar shows from your app:

<script>
  let date = $state(new Date());
</script>

<Calendar
  {adapter}
  currentDate={date}
  ondatechange={(d) => date = d}
/>

Show a rolling 3-day view (week views other than 7 days start at the focused date):

<Calendar {adapter} view="week-planner" days={3} />

Block lunch hours and enforce 30–120 min events:

<script>
  import type { BlockedSlot } from '@nomideusz/svelte-calendar';

  const blocked: BlockedSlot[] = [
    { start: 12, end: 13, label: 'Lunch' },           // every day 12–1 PM
    { day: 6, start: 0, end: 24, label: 'Saturday' }, // block all Saturday (ISO weekday)
  ];
</script>

<Calendar {adapter} blockedSlots={blocked} minDuration={30} maxDuration={120} />

Disable specific dates:

<Calendar
  {adapter}
  disabledDates={[new Date('2026-03-25'), new Date('2026-04-01')]}
/>

Disabled dates refuse creating or moving events into those days, which suits holidays or fully booked days. In the planner, agenda and mobile views their existing events stay visible and clickable; month-grid dims a disabled day, and its chips ignore clicks.

Custom day headers and hover previews:

<Calendar {adapter} oneventhover={(ev) => showTooltip(ev)}>
  {#snippet dayHeader({ date, isToday, dayName })}
    <span style:font-weight={isToday ? 'bold' : 'normal'}>{dayName}</span>
  {/snippet}
</Calendar>

Replace the built-in navigation or the entire header chrome with your own controls:

<Calendar {adapter}>
  {#snippet navigation({ prev, next, goToday, isViewOnToday, mode })}
    <button onclick={prev}>‹</button>
    {#if !isViewOnToday}<button onclick={goToday}>Today</button>{/if}
    <button onclick={next}>›</button>
  {/snippet}
</Calendar>

<Calendar {adapter}>
  {#snippet header({ dateLabel, mode, modes, switchMode, prev, next, goToday })}
    <nav class="my-toolbar">
      <h2>{dateLabel}</h2>
      {#each modes as m}
        <button class:active={mode === m} onclick={() => switchMode(m)}>{m}</button>
      {/each}
      <button onclick={prev}>←</button>
      <button onclick={goToday}>Today</button>
      <button onclick={next}>→</button>
    </nav>
  {/snippet}
</Calendar>

Let agenda content determine height instead of forcing a fixed box, for a calendar inside a scrolling page:

<Calendar {adapter} view="week-agenda" height="auto" compact />

Themes#

Three built-in presets:

<script>
  import { Calendar, neutral, midnight } from '@nomideusz/svelte-calendar';
</script>

<Calendar {adapter} />                     <!-- auto: adapts to host page -->
<Calendar {adapter} theme={neutral} />     <!-- explicit light mode -->
<Calendar {adapter} theme={midnight} />    <!-- explicit dark mode -->

presets maps the names to the strings (presets.neutral); the type PresetName is 'auto' | 'neutral' | 'midnight'.

Smart Auto Theme#

The default auto preset probes the page around the calendar and generates a theme that blends in. It detects:

• Background color: from common CSS variables on :root (--bg, --background, --color-bg, --bs-body-bg, …), inline styles, or computed styles
• Light/dark mode: from background luminance
• Accent/brand color: from common CSS variables (--accent, --primary, --brand, --bs-primary, …), link colors, or button colors
• Text color: validated for contrast against the background
• Fonts: the host's computed font stack; the mono stack from --font-mono and similar variables

It watches for changes (a dark-mode toggle on <html>/<body>, the system color scheme) and updates automatically.

The probing engine is exported for standalone use: probeHostTheme(element, options?) returns a --dt-* CSS string for the page around element; observeHostTheme(element, callback, options?) re-probes on theme changes and returns a stop function.

Fine-tune auto-detection with the autoTheme prop (AutoThemeOptions):

<!-- Force dark mode even if the page background is light -->
<Calendar {adapter} autoTheme={{ mode: 'dark' }} />

<!-- Override the accent color (skip probing) -->
<Calendar {adapter} autoTheme={{ accent: '#e11d48' }} />

<!-- Override the font stack -->
<Calendar {adapter} autoTheme={{ font: '"Poppins", sans-serif' }} />

<!-- Disable probing entirely: inherit --dt-* from ancestors -->
<Calendar {adapter} autoTheme={false} />

Your own tokens#

The calendar writes its theme inline on its own root element, so it wins over --dt-* values set on an ancestor or :root. With the default auto theme it writes a full probed set. To use your own values:

• Change a few tokens: append them to a preset (later declarations win):

  Copy

  import { neutral } from '@nomideusz/svelte-calendar';
  
  const custom = `${neutral}; --dt-accent: #e11d48;`;
  

  Copy

  <Calendar {adapter} theme={custom} />
  

• Write your own theme string: any --dt-* declarations; tokens you leave out are inherited from ancestors or fall back to neutral defaults.

• Inherit from the page: pass autoTheme={false} (keeping the default auto theme). The calendar then writes no tokens and reads whatever --dt-* its ancestors define:

  Copy

  <div style="--dt-accent: #e11d48; --dt-bg: #1a1a2e; --dt-text: rgba(255,255,255,0.87);">
    <Calendar {adapter} autoTheme={false} />
  </div>
  

Component fallbacks use system fonts and a neutral blue accent, so the package stays clean in apps that set no tokens.

Events#

TimelineEvent#

Cancelled events render with a strikethrough but stay visible, so the slot isn't mistaken for free time.

Event colors#

An event with a color draws its bar in that color. An event without one draws in ink: --dt-event, which the presets set to the text color. Nothing is colored for you unless you ask.

To color events automatically, pass a palette to the memory, recurring or mapped adapter. Events without a color then take a palette color, grouped by category (or title):

import { createMemoryAdapter, VIVID_PALETTE } from '@nomideusz/svelte-calendar';

const events = [
  { id: '1', title: 'Yoga',    category: 'wellness', start, end },
  { id: '2', title: 'Pilates', category: 'wellness', start, end },  // same color
  { id: '3', title: 'Standup', start, end },                        // different color
];

const adapter = createMemoryAdapter(events, { palette: VIVID_PALETTE });

Or generate a theme-harmonious palette from any accent color:

import { createMemoryAdapter, generatePalette } from '@nomideusz/svelte-calendar';

const palette = generatePalette('#e11d48'); // (accent?, count = 15)
const adapter = createMemoryAdapter(events, { palette });

Events are transparent by default: a bar in the event's colour, ink text on the paper. To give them a background, or change the bar:

<Calendar {adapter} eventFill={0.15} />            <!-- a light wash in each event's colour -->
<Calendar {adapter} eventFill={0.15} eventBar={0} /> <!-- wash only, no bar -->
<Calendar {adapter} eventBar={5} />                <!-- a heavier bar -->

Related exports: VIVID_PALETTE (the vivid palette, the default before 1.4) and extractAccent(themeString) (the accent color of a --dt-* theme string).

Multi-day & All-day#

Events spanning multiple days or flagged allDay: true render in a strip above timed events:

const events = [
  { id: '1', title: 'Conference', start: new Date('2026-03-15'), end: new Date('2026-03-18'), allDay: true },
  { id: '2', title: 'Sprint',     start: new Date('2026-03-15T00:00'), end: new Date('2026-03-17T00:00') },
];

Custom Event Rendering#

The event snippet replaces the event content in every view (the interactive shell for click, keyboard, drag and selection stays intact). The empty snippet replaces the empty state of the day agenda, the day on mobile, and an empty planner week:

<Calendar {adapter}>
  {#snippet event(ev)}
    <div style="padding: 4px 8px;">
      <strong>{ev.title}</strong>
      {#if ev.subtitle}<small>{ev.subtitle}</small>{/if}
    </div>
  {/snippet}
  {#snippet empty()}
    <p>Nothing booked. Drag on the grid to add a class.</p>
  {/snippet}
</Calendar>

Adapters#

The calendar reads its events through an adapter. Which one:

REST Adapter#

Connect to any REST API:

import { createRestAdapter } from '@nomideusz/svelte-calendar';

type ApiItem = { id: string; name: string; startAt: string; endAt: string };

const adapter = createRestAdapter({
  baseUrl: 'https://api.example.com/v1',
  headers: { Authorization: 'Bearer TOKEN' },
  // Optional: map your API's list shape to TimelineEvent[]
  mapEvents: (data) =>
    (data as { items: ApiItem[] }).items.map((item) => ({
      id: item.id,
      title: item.name,
      start: new Date(item.startAt),
      end: new Date(item.endAt),
    })),
});

The adapter calls GET {baseUrl}/events?start=…&end=… (ISO strings), POST /events, PATCH /events/:id and DELETE /events/:id, sending JSON with your headers. By default a list response must be an array of events and a single response one event; start/end are parsed into Dates. Override with mapEvents(data) for lists and mapEvent(data) for single events. A non-2xx response or invalid JSON throws.

JMAP Adapter#

Read events from a JMAP Calendars server (Fastmail, Stalwart, Cyrus):

import { createJmapAdapter, type JmapClient } from '@nomideusz/svelte-calendar';

const client: JmapClient = {
  request: (calls) =>
    fetch('https://api.example.com/jmap', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${token}` },
      body: JSON.stringify({ using: ['urn:ietf:params:jmap:calendars'], methodCalls: calls }),
    }).then((r) => r.json()),
};

const adapter = createJmapAdapter(client, {
  getAccountId: () => accountId,
  calendarId: 'primary',          // optional: restrict to one calendar
  timeZone: 'Europe/Warsaw',      // optional: default Etc/UTC
});

Read-only. Expands recurrences server-side and handles all-day events, ISO-duration ends and per-calendar colors (pass calendars: [{ id, name, color }], or a function returning them).

iCalendar (.ics)#

Every calendar app speaks iCalendar: Google Calendar, Apple Calendar / iCloud, Outlook / Microsoft 365, Thunderbird, Proton, Fastmail, Nextcloud. One adapter reads all of them, from a file or a feed:

<script>
  import { Calendar, createIcsAdapter } from '@nomideusz/svelte-calendar';

  let adapter = $state(createIcsAdapter(''));
  async function importFile(e) {
    const file = e.currentTarget.files?.[0];
    if (file) adapter = createIcsAdapter(await file.text());
  }
</script>

<input type="file" accept=".ics,.ical,.ifb,text/calendar" onchange={importFile} />
<Calendar {adapter} />

A subscription URL loads on the first fetch (webcal:// reads as https://); refreshInterval refetches once the copy is older than that many ms:

// Google: Settings → your calendar → "Secret address in iCal format"
// Outlook: Settings → Calendar → Shared calendars → Publish → ICS link
// iCloud: share the calendar as "Public Calendar" → webcal:// link
const adapter = createIcsAdapter({ url: '/api/calendar-feed', refreshInterval: 15 * 60_000 });

Google, Outlook and iCloud send no CORS headers, so a browser can't fetch their feeds directly: serve them through a route of your own (the feed URL is a secret, so keep it on the server anyway):

// src/routes/api/calendar-feed/+server.ts
export const GET = async ({ fetch }) => new Response(await (await fetch(FEED_URL)).text(), {
  headers: { 'content-type': 'text/calendar; charset=utf-8' },
});

• Recurrence is expanded per viewed range: RRULE (daily, weekly, monthly, yearly; INTERVAL, COUNT, UNTIL, BYDAY with ordinals like -1FR, BYMONTHDAY, BYMONTH, BYSETPOS, WKST), RDATE, EXDATE, and moved or edited occurrences (RECURRENCE-ID).
• Times keep their zone: UTC, IANA TZIDs, and the VTIMEZONE blocks Outlook writes under Windows zone names. Floating times read in the calendar's X-WR-TIMEZONE, else the browser's. All-day dates are local midnights, end exclusive.
• SUMMARY → title, LOCATION → location, STATUS → status, the first of CATEGORIES → category, COLOR → color, UID → externalId, DESCRIPTION / URL → data.description / data.url. Events without a colour take options.color, else the calendar's own (X-APPLE-CALENDAR-COLOR).
• Read-only: each occurrence carries data.readOnly, and a write throws CalendarReadOnlyError, so in a composite a drag reaches oneventmove.
• The source may also be a function returning the text: createIcsAdapter(() => loadIt()).

To use the events outside an adapter (copy an import into your own store), parse once and expand any range:

import { parseIcs } from '@nomideusz/svelte-calendar';

const cal = parseIcs(text);           // { name, color, events(range) }
const imported = cal.events({ start, end });

Export. toIcs(events, { name }) writes an .ics file that Google, Apple and Outlook import, or subscribe to when you serve it from a URL. For a single event, googleCalendarUrl(event) and outlookCalendarUrl(event, { work }) (personal outlook.live.com, or Microsoft 365) open the app's "add event" page:

import { toIcs, googleCalendarUrl, outlookCalendarUrl } from '@nomideusz/svelte-calendar';

const file = new Blob([toIcs(events, { name: 'Studio' })], { type: 'text/calendar' });
const href = URL.createObjectURL(file);   // <a {href} download="studio.ics">

Mapped Adapter#

Wrap any static array of external records (class schedules, appointments, timetables) without writing a custom adapter. Supply a declarative field mapping (or a mapEvent function for full control) and the adapter handles parsing, colors, tags and status:

import { createMappedAdapter } from '@nomideusz/svelte-calendar';

const adapter = createMappedAdapter(rawClasses, {
  fields: {
    title: 'class_name',
    start: 'starts_at_iso',
    end: 'ends_at_iso',
    subtitle: 'teacher',
    location: 'room',
    externalId: 'reference_id',
    status: 'is_cancelled',           // boolean → 'cancelled' / 'confirmed'
    tags: ['is_free', 'is_bookable_online'],
  },
});

• Works without options too: it looks for common keys (id, title/name, start/end, starts_at_iso/ends_at_iso, date + start_time/end_time, room/location, is_cancelled). A missing end defaults to one hour after the start.
• start/end accept ISO strings, Dates or millisecond timestamps. When records split date and time (date: "2026-03-03", startTime: "07:00"), map date + startTime / endTime; times may be 7:00, 07:00 or 07:00:00.
• Source colors are kept. Records without one draw in ink, unless you pass a palette to fill them by category/title. autoColor: true ignores the source colors and colors every event from palette (default VIVID_PALETTE).
• includeData (default '*') copies unmapped source fields into event.data; pass a list of keys to limit it.

For full control, pass mapEvent(raw, index) and skip fields:

const adapter = createMappedAdapter(rawData, {
  mapEvent: (raw) => ({
    id: raw.uid,
    title: raw.procedure_name,
    start: new Date(raw.scheduled_at),
    end: new Date(raw.scheduled_end),
    location: raw.office,
    resourceId: raw.doctor_id,
  }),
});

Mapped adapters are read-only by default (writes throw a read-only error, so drags reach oneventmove). Set readOnly: false to allow writes; supply onMutate: { onCreate, onUpdate, onDelete } to persist them (each returns the stored source record, which is mapped again), or omit it to keep changes in memory.

Composite Adapter#

Merge several adapters into one, e.g. a recurring weekly schedule plus one-off events:

import { createMemoryAdapter, createRecurringAdapter, createCompositeAdapter } from '@nomideusz/svelte-calendar';

const memory    = createMemoryAdapter(oneOffEvents);
const recurring = createRecurringAdapter(weeklySchedule);

const adapter = createCompositeAdapter([memory, recurring]);

• Reads query every child in parallel and merge the results (the first event with a given id wins).
• Creates go to the primary child: the first by default, or primaryIndex.
• Updates and deletes go to the child that returned the event. If that child can't write, the composite refuses with a read-only error (so oneventmove reaches the host). An id no fetch returned is offered to each writable child in turn.
• onFetchError(error, adapterIndex): with it, a failing child is reported to you and the others still load; without it, one failing child fails the whole load (surfacing through onerror).

const adapter = createCompositeAdapter([recurring, memory], {
  primaryIndex: 1,
  onFetchError: (error, i) => console.warn(`source ${i} failed`, error),
});

Custom Adapter#

Implement the CalendarAdapter interface to connect any data source. Only fetchEvents is required:

import type { CalendarAdapter, DateRange, TimelineEvent } from '@nomideusz/svelte-calendar';

const adapter: CalendarAdapter = {
  // Required: events overlapping the range
  fetchEvents: async (range: DateRange) => { /* return TimelineEvent[] */ },
  // Optional: the same answer synchronously, when the data is already in memory
  fetchEventsSync: (range) => { /* return TimelineEvent[], or undefined to go async */ },
  // Optional writes; omit them for a read-only source
  createEvent: async (event) => { /* return the created TimelineEvent with its id */ },
  updateEvent: async (id, patch) => { /* return the updated TimelineEvent */ },
  deleteEvent: async (id) => { /* void */ },
};

WritableCalendarAdapter is the same interface with all three write methods required.

fetchEventsSync lets the first render (the server render too) hold the events instead of a loading state. The memory, recurring and seeded adapters implement it. To seed an async adapter with events you already loaded on the server, wrap it:

import { createRestAdapter, withInitialEvents } from '@nomideusz/svelte-calendar';

// data.events: TimelineEvent[] for the range the page opens on
const adapter = withInitialEvents(createRestAdapter({ baseUrl: '/api' }), data.events);

The first load is answered synchronously from the seed; every later load (navigation, refresh) goes to the wrapped adapter.

Refusing a write#

The Calendar tells two refusals apart when updateEvent throws:

An adapter without updateEvent counts as read-only. Plain Errors whose message contains read-only (lower case) or not found (any case) are read the same way, so older adapters keep working. isReadOnlyError(e) and isNotFoundError(e) test both forms.

Recurring Schedules#

For fixed repeating events (class timetables, office hours):

<script>
  import { Calendar, createRecurringAdapter } from '@nomideusz/svelte-calendar';

  const adapter = createRecurringAdapter([
    { id: '1', title: 'Yoga',    dayOfWeek: 1, startTime: '07:00', endTime: '08:30' },
    { id: '2', title: 'Standup', frequency: 'daily', startTime: '09:00', endTime: '09:15',
      startDate: '2026-03-01', until: '2026-03-31' },
    { id: '3', title: 'Review',  frequency: 'monthly', dayOfMonth: 15,
      startTime: '10:00', endTime: '11:00' },
    { id: '4', title: 'Night shift', dayOfWeek: [5, 6], startTime: '22:00', endTime: '02:00' },
  ]);
</script>

<Calendar {adapter} view="week-planner" />

Options (RecurringAdapterOptions): mondayStart (default true), palette (colors rules without a color; off by default), movable (default false).

Occurrences get the id `${rule.id}--YYYYMMDD` and data.recurringId. The adapter projects and stores nothing, so by default every occurrence carries data.readOnly and can't be dragged (it can still be clicked). With movable: true the views allow the drag and the adapter refuses the write with a read-only error, so oneventmove fires and the host stores the move: add the date to the rule's excludeDates and keep the moved occurrence with your one-off events (for example the memory side of a composite adapter).

Headless API#

For full control over rendering, skip <Calendar> and drive everything from reactive state. createCalendar() returns computed layouts, navigation actions, drag helpers and the raw engines. Zero DOM: bring your own UI. Call it during component initialisation.

<script lang="ts">
  import { createCalendar, createMemoryAdapter } from '@nomideusz/svelte-calendar';

  const adapter = createMemoryAdapter([/* ... */]);
  const cal = createCalendar({ adapter, view: 'week-planner' });
</script>

<header>
  <button onclick={cal.prev}>←</button>
  <span>{cal.headerContext.dateLabel}</span>
  <button onclick={cal.next}>→</button>
  <button onclick={cal.goToday}>Today</button>
</header>

{#each cal.weeks as week}
  <div class="week-row">
    {#each week.days as day}
      <div class:today={day.isToday} class:past={day.isPast}>
        <h3>{day.dayNum}</h3>
        {#each day.events as ev}
          <div style:background={ev.color}>{ev.title}</div>
        {/each}
      </div>
    {/each}
  </div>
{/each}

Options (HeadlessCalendarOptions) mirror the Calendar props: adapter, view (default 'week-planner'), mondayStart, initialDate, timezone, locale, visibleHours, snapInterval, equalDays, hideDays, blockedSlots, disabledDates, days, readOnly, minDuration, maxDuration, and the callbacks oneventclick, oneventcreate, oneventmove.

cal.days gives flat HeadlessDay[] with events attached; cal.weeks groups them into periods (HeadlessWeek). cal.todayQueue returns { past, current, upcoming } for today (TodayQueue), updated every second. cal.hours yields the visible hour numbers. Drag is fully wired: beginDragMove, beginDragCreate, updateDrag, commitDrag (validates like the Calendar), cancelDrag, plus isDragging / dragPayload / dragMode. headerContext / navigationContext match the Calendar's header / navigation snippet contexts. Raw engines (store, viewState, selection, dragState, clock) are exposed for advanced cases.

The engine factories are exported individually (createEventStore(adapter), createViewState(options), createSelection(), createDragState(), createClock(timezone?)) if you want to compose your own calendar loop (types: EventStore, ViewState, ViewStateOptions, CalendarSelection, DragState, DragMode, DragPayload, CalendarViewId, BuiltInViewId, ViewMode).

createAgenda#

A live single-day list: createAgenda({ adapter, initialDate?, locale?, lookahead?, timezone? }).

<script lang="ts">
  import { createAgenda, createMemoryAdapter } from '@nomideusz/svelte-calendar';

  const adapter = createMemoryAdapter([/* ... */]);
  const agenda = createAgenda({ adapter });
</script>

<h2>{agenda.dateLabel}</h2>
{#each agenda.upcoming as ev}
  <div>
    <time>{agenda.fmtTime(ev.start)}</time>
    <span>{ev.title}</span>
    <small>{agenda.eta(ev)}</small>
  </div>
{/each}

It returns dayEvents, allDay, past, current, upcoming, upcomingSlots (TimeSlot[]: overlapping events grouped as { startMs, endMs, events }), count, eta(ev), progress(ev), fmtTime / fmtDuration / fmtRange, and prev / next / goToday / setDate.

createRangeAgenda#

A window of days with events grouped per day; no clock, drag or selection. Built for read-only schedule surfaces (public timetables, embeds):

<script lang="ts">
  import { createRangeAgenda } from '@nomideusz/svelte-calendar';

  const agenda = createRangeAgenda({ adapter, days: 7, locale: 'pl-PL', timezone: 'Europe/Warsaw' });
</script>

<button onclick={agenda.prev}>←</button>
<button onclick={agenda.next}>→</button>

{#each agenda.days.filter((d) => d.events.length > 0) as day (day.ms)}
  <h3>{day.date.toLocaleDateString()}</h3>
  {#each day.events as ev (ev.id)}
    <p>{agenda.fmtRange(ev)} {ev.title}</p>
  {/each}
{/each}

Options (RangeAgendaOptions): adapter (or a getter), days (default 7), initialDate (the first day, not aligned to a week start), locale, timezone. It returns days (RangeAgendaDay[]: ms, date, weekday, isToday, isPast, events), range, count, loading, error, prev(), next(), goToday(), setDate(date), refresh(), fmtTime(date), fmtDuration(ev), fmtRange(ev).

Localization (i18n)#

The locale prop controls date/time formatting (BCP 47). Without it, the global default locale is used: 'en-US' unless you call setDefaultLocale():

<Calendar {adapter} locale="de-DE" />

setDefaultLocale('de-DE') sets it for every calendar and formatter; getDefaultLocale() reads it back; is24HourLocale(tag?) tells you how times will format. An RTL locale (ar-SA, he-IL, …) sets dir="rtl" where the browser reports the locale's text direction (Intl.Locale text info); pass dir to be explicit.

Override UI labels per calendar with the labels prop. It's reactive (swap it to switch language live) and instance-scoped (two calendars on one page can carry different languages):

<Calendar {adapter} locale="de-DE" labels={{
  today: 'Heute', day: 'Tag', week: 'Woche', month: 'Monat',
  noEvents: 'Keine Termine',
  nMore: (n) => `+${n} weitere`,
}} />

Or set labels globally before mount:

import { setLabels } from '@nomideusz/svelte-calendar';

setLabels({ today: 'Heute', day: 'Tag', week: 'Woche' });

Both take a Partial<CalendarLabels>, and that is the supported input: pass the keys you translate, and keys added in later minor releases fall back to English. The labels prop merges over the global set. resetLabels() restores English (defaultLabels exports it; getLabels() reads the active set). Global setLabels() calls after mount don't re-render mounted calendars; use the labels prop to switch language live. Standalone primitives (DayHeader, EventBlock, …) and the format helpers read the global set.

Timezone Support#

Render the whole calendar in any IANA timezone: events, the now-indicator and day boundaries all shift:

<Calendar {adapter} timezone="Europe/Warsaw" />

• initialDate and currentDate are instants, read in that zone.

• oneventcreate, oneventmove and onexternaldrop receive real instants.

• ondatechange and ondayclick receive instants too (the start of that day in the zone), so feeding one back is stable: currentDate={date} ondatechange={(d) => (date = d)}. To read the date, format it in the zone:

  Copy

  import { formatInTimeZone } from '@nomideusz/svelte-calendar';
  formatInTimeZone(d, 'Europe/Warsaw', { year: 'numeric', month: '2-digit', day: '2-digit' }, 'en-CA'); // "2026-10-24"
  

• Events handed to oneventclick / oneventmove / snippets are shifted the same way: their local fields show the zone's wall-clock time.

• timezone is read when the Calendar mounts. To change zones at runtime, remount it:

  Copy

  {#key timezone}
    <Calendar {adapter} {timezone} />
  {/key}
  

Under the hood the adapter is wrapped with wrapAdapterWithTimezone(adapter, zone) (also exported), so views do plain local-time math on a zoned wall-clock plane. Known limit shared by every wall-clock calendar: the repeated hour of a DST fall-back is ambiguous, and writes inside it resolve to one of the two instants.

The headless helpers take the same option: createCalendar({ timezone }), createAgenda({ timezone }), createRangeAgenda({ timezone }), plus createClock(timezone) and createViewState({ timezone }).

Convert dates manually with the built-in helpers:

import { toZonedTime, fromZonedTime, nowInZone, formatInTimeZone } from '@nomideusz/svelte-calendar';

// A Date whose local fields show the instant's wall-clock time in New York
const local = toZonedTime(utcDate, 'America/New_York');

// Back to the real instant before saving
const utc = fromZonedTime(local, 'America/New_York');

// Current time in a timezone (wall-clock Date)
const now = nowInZone('Asia/Tokyo');

// Format an instant directly in a timezone: (date, zone, Intl options?, locale?)
formatInTimeZone(utcDate, 'America/New_York', { hour: '2-digit', minute: '2-digit' });

Utilities#

Small helpers used by the built-in views, exported for custom rendering. Formatters take an optional locale (default: the global default locale); day helpers work on millisecond timestamps.

Embeddable Widget#

Drop into any HTML page, no build tools needed. Registers a <day-calendar> custom element:

<script src="https://cdn.jsdelivr.net/npm/@nomideusz/svelte-calendar/widget/widget.js"></script>

<day-calendar
  api="https://myschool.com/api/events"
  theme="neutral"
  view="week-planner"
  height="600"
  locale="en-US"
></day-calendar>

In a bundler, import '@nomideusz/svelte-calendar/widget' registers the same element.

The widget renders inside shadow DOM: host-page CSS cannot affect the calendar and calendar styles never leak out, while the auto theme still probes the host page's colors and fonts across the shadow boundary.

Each event in api responses and events needs start and end as date strings (ISO 8601) and may carry id, title, color, allDay, subtitle and location; other fields are ignored, as are events with an invalid or empty range. Changing an attribute updates the calendar in place.

All Props#

Every <Calendar> prop (CalendarProps), grouped by what it controls.

Troubleshooting#

• Dragging on empty time does nothing. Creating needs an oneventcreate handler (and no readOnly); see the Quick Start.
• A created event doesn't appear. The calendar stores nothing on create: add the event to your data and hand the Calendar a new adapter ($derived(createMemoryAdapter(events))).
• Moved events jump back after the next change. A new adapter is built from your array, so write each move into it in oneventmove.
• The auto theme picked the wrong colours. It probes the host page around the calendar, and probes again when <html>/<body> change class, style or data-theme, when the system scheme flips and when a background transition ends. Steer it with autoTheme, or set theme to a preset or your own tokens to opt out.
• Events are all one colour. Since 1.4 events without a color draw in ink; give the adapter a palette.
• The calendar stops at 600px. That's the default height; pass a number, or 'auto' to grow with the content.
• The phone layout shows on a wide page (or the desktop one in a narrow column). The switch reads the calendar's container, not the window; force it with mobile={false} or mobile={true}.

Versioning#

The package follows semver from 1.0:

• The public API is exactly what the . and ./widget entry points export. Deep imports into dist/ are not supported.
• TimelineEvent, CalendarAdapter and DateRange are stable shapes: fields may be added in minor releases, never renamed, removed or given new meaning outside a major.
• The --dt-* theme tokens are part of the contract, as are the <day-calendar> attributes.
• CalendarLabels gains keys in minor releases, so pass a Partial (see Localization).

Development#

pnpm install
pnpm dev              # demo site
pnpm check            # svelte-check
pnpm test             # vitest
pnpm run package      # build the library into dist/
pnpm run build:widget # build widget/widget.js

License#

MIT