Documentation

RollDate Events documentation

One public API reference for Events Lite and Events Pro 1.0.1 — installation, event model, views, options, and methods.

Try the Lite demo, the Pro live demo, or the product overview.

Stable · Events 1.0.x · Pro 1.0.1

Need recurring series, drag/resize workflows or a resource Timeline? Those capabilities ship in Events Pro.

Events Pro · Live Demo

Capability	Lite	Pro
Month / Week / Day / Agenda	Included	Included
Timed, all-day, multi-day events	Included	Included
Programmatic CRUD + navigation API	Included	Included
Resource Timeline view	—	Pro
Recurring expansion (`series` / `this`)	—	Pro
Drag and resize (Week / Day / Timeline)	—	Pro
Signed offline license	—	Pro

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`	Resource lane id. Used by Timeline Pro
`recurring`	`object`	Lite renders the base occurrence only. Expansion is Pro
`editable`	`boolean`	Pro Per-event drag/resize lock
`allowedResourceIds`	`string[]`	Pro Restricts Timeline resource changes

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.

Resource Timeline Pro

Available in Events Pro. Day-based horizontal resource strip (~7 visible days), drag between resources, and resize along the day axis.

const calendar = new RollDateEvents('#calendar', {
  licenseKey: purchasedLicense,
  defaultView: 'timeline',
  resources: [
    { id: 'anna', title: 'Anna', color: '#609ef1' },
    { id: 'bohdan', title: 'Bohdan', color: '#5ecf8a' }
  ],
  events: [{ id: 1, title: 'Design', start: '2026-08-20T10:00:00', end: '2026-08-20T11:00:00', resourceId: 'anna' }]
})

Events Pro · View live demo

Configuration options

Option	Default	Description
`events`	`[]`	Initial events
`defaultView`	`'month'`	`month \| week \| day \| agenda`; Pro also `timeline`
`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`	—	Navigable / droppable day bounds
`licenseKey`	—	Pro Signed license object or JSON string
`resources`	—	Pro Timeline resource lanes
`editable`	`true` when unlocked	Pro Calendar-level drag/resize
`allowedResourceIds`	—	Pro Restricts resource changes only. Intersects with `event.allowedResourceIds`
`allowOverlap`	`true`	Pro `false` blocks overlapping move/resize (`[start, end)`)
`resolveEventChangeScope`	—	Pro Return `'this' \| 'series'` for recurring gestures

Install Events Pro Pro

Available in Events Pro. The package is not on the public npm registry — install the versioned .tgz from purchase or recovery.

npm install ./rolldate-events-pro-1.0.1.tgz

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

const calendar = new RollDateEvents('#calendar', {
  licenseKey: purchasedLicense,
  defaultView: 'week'
})

Events Pro

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
onDayOpen(info) — day jump from headers
beforeEventMove(info) Pro
beforeEventResize(info) Pro
onEventChange(event, reason, context) Pro — includes context.revert and transaction

Available in Events Pro. Persist multi-mutation transactions from context.transaction.mutations when detaching recurring occurrences.

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.

Lite does not expand recurring series, unlock drag/resize, or enable Resource Timeline. Those ship in Events Pro.

Pro 1.0.1 includes Timeline, recurring expansion, and drag/resize under a signed license. Features marked Unreleased in the repository SPEC are not part of this package.

Report Lite issues on GitHub.