Documentation

RollDate Events documentation

Installation, event model, views, configuration, and API reference for the Free public beta.

Try the live demo or explore the product overview.

Public Beta · 0.1.0-beta.0

Installation

Install from npm using the beta dist-tag while the public beta is active.

npm

npm install @rolldate/events@beta

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

Scrollable list grouped by date — full rows, no “+N more” truncation.

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, title, 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
`setDate(date)`	Jump to 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.

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.

Beta status

0.1.0-beta.0 is an early public beta. APIs may change before 1.0.0.

Report issues on GitHub.

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