Documentation

RollDate Events documentation

Installation, event model, views, configuration, and API reference for RollDate Events v1.

Try the live demo or explore the product overview.

Stable · 1.0.0

Installation

Install from npm.

npm

npm install @rolldate/events

Styles

import '@rolldate/events/styles'

Quick start

import { RollDateEvents } from '@rolldate/events'
import '@rolldate/events/styles'

const calendar = new RollDateEvents('#calendar', {
  defaultView: 'month',
  events: [{ id: 1, title: 'Standup', start: '2026-08-20T09:00:00', end: '2026-08-20T09:30:00' }]
})

Event object

Field	Type	Description
`id`	`string \| number`	Unique identifier
`title`	`string`	Display title
`start`, `end`	`Date \| string`	Start and end
`allDay`	`boolean`	All-day event
`color`	`string`	Accent color
`location`	`string`	Optional location
`description`	`string`	Optional description
`resourceId`	`string`	Reserved — not used by Free views
`recurring`	`object`	Reserved — Free renders base occurrence only

Timed events

Use ISO or local date-time strings. Week and Day views place events on the timed grid.

All-day events

Set allDay: true with date-only start / end.

Multi-day events

All-day events spanning multiple days use inclusive date ranges.

Month view

Continuous vertical week strip with event chips; compact dots when narrow.

Week view

Horizontal week strip, timed grid, all-day band, overlap layout.

Day view

Single-day timed grid with vertical day navigation.

Agenda view

Compact list of events grouped by date — full rows, no “+N more” truncation. Days without events are skipped. Day, Week, and Month still show free and busy time.

Configuration options

Option	Default	Description
`events`	`[]`	Initial events
`defaultView`	`'month'`	`month \| week \| day \| agenda`
`defaultDate`	today	Initial date
`locale`	`'en'`	Locale string
`firstDayOfWeek`	`1`	`0` Sunday, `1` Monday
`theme`	`'dark'`	`light \| dark \| auto`
`header`	`true`	Nav, date navigator, view tabs
`visibleHours`	`9–18`	Week/Day grid hours
`eventLimit`	`3`	Month chips before “+N more”
`minDate`, `maxDate`	—	Navigation bounds

Methods

Method	Description
`setView(view)`	Switch view
`getView()`	Current view name
`setDate(date)`	Jump to date
`getDate()`	Current cursor date
`setEvents(events)`	Replace all events
`getEvents()`	Return events array
`addEvent(event)`	Add one event
`updateEvent(id, patch)`	Update by id
`removeEvent(id)`	Remove by id
`today()`	Go to today
`next()`, `prev()`	Navigate
`destroy()`	Remove DOM and listeners

Read-only: currentView, currentDate, el (equivalent to getView() / getDate()).

Date navigator

Click the header period (for example August 2026 ▾) to open a month/year picker. Navigation respects minDate and maxDate. Programmatic setDate(...) stays synchronized with the header.

Callbacks

onEventClick(event, nativeEvent)
onDateClick(date, nativeEvent)
onViewChange(view)
onVisibleRangeChange({ from, to }) — useful for lazy loading

Responsive behavior

Layout adapts to container width via ResizeObserver. Compact mode at ≤640px.

Large datasets

Events indexed by day; bounded segment buffers; use onVisibleRangeChange to load data for visible ranges.

Browser support

Modern evergreen browsers with ES modules, CSS custom properties, and ResizeObserver.

Limitations (v1)

RollDate Events uses native JavaScript Date in the local timezone. There is no built-in IANA timezone conversion in v1.

Report issues on GitHub.

Not in v1: drag and drop, resizing, resource timeline, recurring expansion.