Calendar

Month grid for date-based, single-day and multi-day events, with drag/move, resize, and optional creation callbacks.

Import

import { Calendar, calendar, type CalendarTypes } from '@atom-forge/ui';

When to use

Use for an all-day month schedule whose event dates are owned by the application.

Alternatives

Use Organizer for its separate scheduling model, GanttChart for tasks/dependencies, or ResourceManager for resource allocations.

Setup

Apply Getting Started CSS. Use local date strings in YYYY-MM-DD format and a zero-based month. No Calendar-specific external provider is required.

Minimal example

<script lang="ts">
  import { Calendar, type CalendarTypes } from '@atom-forge/ui';
  let events = $state<CalendarTypes.CalendarEvent[]>([
    { id: 'review', title: 'Review', startDate: '2026-10-06', endDate: '2026-10-07', color: 'blue' }
  ]);
  function updateDates(id: string, startDate: string, endDate: string) {
    events = events.map(event => event.id === id ? { ...event, startDate, endDate } : event);
  }
</script>

<Calendar year={2026} month={9} {events}
  onEventMove={updateDates} onEventResize={updateDates}/>

Behavior

End dates are inclusive. Moves preserve the start/end day difference. Resizes preview locally and report dates on mouse release. Event arrays are not mutated by those callbacks: apply updates yourself as above. viewOnly prevents move, resize, and creation, but event click callbacks remain available. Individual readOnly events cannot be moved/resized. Rest-day styling is independent from permission to place events on those dates. With wrapMultiDay={false}, an event is omitted from later weeks when its start is before that week.

API

Prop	Type	Default
year, month	number, bindable	Current local year/month (month 0–11)
events	CalendarTypes.CalendarEvent[]	[]
viewOnly	boolean	false
workdays	string of weekday digits, Sunday 0	'12345'
extraRest	CalendarTypes.RestDayEntry[]	[]
extraWork	string[]	[]
firstDayOfWeek	0 | 1	1 (Monday)
wrapMultiDay	boolean	true
allowCreate	boolean	false
onEventMove, onEventResize	(id: string, newStart: string, newEnd: string) => void	—
onEventCreate	(date: string) => void	—
onEventClick	(id: string) => void	—
class	string	''

CalendarEvent requires id, startDate, endDate, title strings; optional subtitle, icon (source types it as any for a Lucide component), color, class, and readOnly. CalendarEventColor is 'blue' | 'green' | 'red' | 'orange' | 'purple' | 'teal' | 'yellow'. RestDayEntry is a date string or { date: string; name?: string }. EventSlot has event, startCol, endCol (1–7), lane (zero-based), isStart, and isEnd.

Public calendar utilities

Function	Result
parseDate(s: string) / formatDate(d: Date)	Local Date / YYYY-MM-DD string.
addDays(dateStr: string, days: number)	Date string.
dayDiff(startStr: string, endStr: string)	Rounded day difference.
todayStr()	Today's local date string.
getCalendarWeeks(year: number, month: number, firstDayOfWeek: 0 | 1)	string[][] of full seven-day weeks.
isRestDay(dateStr, workdays, extraRest, extraWork)	Boolean; extraWork overrides extra rest and weekday rules.
getHolidayName(dateStr: string, extraRest: RestDayEntry[])	string | undefined.
computeWeekSlots(weekDays: string[], events: CalendarEvent[], wrapMultiDay: boolean, resizePreview?)	EventSlot[]; preview is { id: string; newStartDate?: string; newEndDate?: string }.
getDayNames(firstDayOfWeek: 0 | 1)	English day names.
getMonthName(year: number, month: number)	English month/year label.

Utility type names above are members of CalendarTypes.

Limitations

No time-of-day, recurrence, server persistence, date validation, or built-in month navigation UI is exposed by Calendar. Change year/month from your application. Date calculations use local dates, not a timezone-aware scheduling model. Browser pointer/drag APIs implement move/resize; do not assume equivalent keyboard editing.

Source: src/lib/controls/scheduling/calendar/{index.ts,types.ts,utils.ts,Calendar.svelte,CalendarGrid.svelte,EventBar.svelte}.