API reference

This reference covers the API used throughout these guides, as implemented in version 0.1.0. Everything except the Lite API section belongs to SuperScheduler Pro (super-scheduler). Defaults are the values the control uses when you omit an option; "none" means the option has no value until you set one. The guides explain how to combine these pieces; the examples show them in working applications.

A few conventions hold everywhere:

• DateInput is SuperScheduler.Date | string. Strings are civil ISO 8601 values with seconds ('2026-10-01T14:00:00') or dates ('2026-10-01'). Event ends are exclusive.
• Resource, event and link ids are string | number and compared strictly: 1 and '1' are different.
• Options are props of SuperSchedulerComponent, keys of control.update(options) and live properties of the control.
• Handlers run with this set to the control. Their return values are ignored, and an async handler is not awaited: use the async and loaded() protocol where it exists.

#Entry points

Every entry ships ESM, CommonJS and type declarations. React 18.2 or later, or 19, is a peer dependency (React DOM too for Pro); there are no runtime dependencies. All modules can be imported on a server without a DOM.

#Components

#SuperSchedulerComponent

SuperSchedulerComponent hosts one control. Its props (SchedulerProps) are all options and handlers below plus controlRef. It renders an unstyled <div>, has no className, style or id props, and forwards to control.update() only the props whose identity changed since the last render; a prop that disappears goes back to its default.

The component from super-scheduler/react-render accepts the same props plus renderEvent, renderCell, renderRowHeader, renderTimeHeader, renderArea, renderCorner, eventHover, the onBefore*DomAdd and onBefore*DomRemove handlers, and renderOptions (see react-render).

import { useEffect, useRef } from 'react'
import { SuperScheduler, SuperSchedulerComponent, useSchedulerControl } from 'super-scheduler'
import { useScheduler } from 'super-scheduler/hooks'

const CONFIG = {
  startDate: '2026-10-01',
  days: 31,
  scale: 'Day',
} satisfies SuperScheduler.SchedulerConfig

// 1. A class ref: `ref.current.control` exists after mount.
export function WithRef() {
  const ref = useRef<SuperSchedulerComponent>(null)
  useEffect(() => ref.current?.control.scrollTo('2026-10-15', true, 'middle'), [])
  return <SuperSchedulerComponent ref={ref} {...CONFIG} />
}

// 2. The control as React state: null until mount, then the live control.
export function WithHook() {
  const { controlRef, control } = useSchedulerControl()
  useEffect(() => control?.scrollTo(SuperScheduler.Date.today()), [control])
  return <SuperSchedulerComponent controlRef={controlRef} {...CONFIG} />
}

// 3. Control plus tracked state topics, published after changes settle.
export function WithState() {
  const { controlRef, state } = useScheduler({ track: ['zoom', 'viewport'] })
  return (
    <>
      <p>
        {state.viewport === undefined
          ? ''
          : `${state.viewport.start.toString('d MMM')} to ${state.viewport.end.toString('d MMM')}`}
      </p>
      <SuperSchedulerComponent controlRef={controlRef} {...CONFIG} />
    </>
  )
}

// 4. Imperative, without React: init() before use, dispose() on teardown.
export function mount(host: HTMLElement): () => void {
  const control = new SuperScheduler.Scheduler(host, CONFIG)
  control.init()
  return () => control.dispose()
}

#Types

#Data shapes

#Events

SuperScheduler.EventData<T> has no index signature: declare extra fields through the type parameter, for example EventData<{ guest: string }>.

#Resources

SuperScheduler.ResourceData<T> accepts extra fields.

#Links, headers, zoom levels and separators

#Options

#Time axis

#Rows

#Events and editing

#Selection

#Zoom and level of detail

#Size and layout

#Appearance

#Links

#Keyboard

#Menus and bubbles

#Data, loading and extensions

#React content

Only with SuperSchedulerComponent from super-scheduler/react-render:

#Callbacks

#Conventions

• Before and after. onEventMove runs before a change and can cancel it; onEventMoved runs after it. Most pairs follow this pattern.
• Cancel. Handlers whose arguments have preventDefault() can cancel: the click family, onEventSelect, onEventDelete, onEventMove, onEventResize, onTimeRangeSelect, onTimeRangeClick and its double and right variants, onRectangleSelect, onRowClick and variants, onRowSelect, onResourceExpand, onResourceCollapse, onTimeHeaderClick, onTimeHeaderRightClick, onGridMouseDown, onKeyDown, onKeyboardFocusChange and onLinkClick. Cancelling a click also skips its "-ed" handler and the follow-up action.
• Async confirmation. onEventMove and onEventResize support args.async = true and a later args.loaded(); preventDefault() before loaded() cancels, and newStart, newEnd and newResource set before loaded() are applied.
• Steering. onEventMoving, onEventResizing, onTimeRangeSelecting and onRectangleSelecting run on every shadow change; assign args.allowed, args.start, args.end, args.cssClass or args.html.

#Events

e is a SuperScheduler.Event: e.data is the data object, and e.id(), e.start(), e.end(), e.text(), e.resource() and e.duration() read it.

#Drag and resize

#Time ranges and rectangles

#Rows and headers

#Rendering hooks

#Other handlers

#Control API

The control is ref.current.control, the value of controlRef, args.control in most handlers, or new SuperScheduler.Scheduler(element, options) followed by init().

#Lifecycle and display

#Scrolling and viewport

#Events

#Rows

#Selection

#Zoom, links, cells and keyboard

#Static members

#The SuperScheduler namespace

#Subpath modules

#history

createHistory(options?) returns a history to pass as history={history} or in extensions. Options: limit (50), record (['move', 'resize']), keys ('root', 'document' or false; default 'root'), equals, fields, apply ('control' or a function for controlled events) and labels. Methods: undo(), redo(), clear(), push({ label, undo, redo }), record({ ops, control }), batch(label, run), revert(eventId), subscribe(listener); properties canUndo, canRedo, undoLabel, redoLabel. Loads and rejected changes are not recorded.

#minimap

createMinimap(control, container, options?) and the React component <SchedulerMinimap control={control} />. Options: series (default eventDensity(control)), height (28), peak ('relative' or 'absolute' with max), tone, marks (today, months, past, all true), range and labels. The widget has update(), refresh() and dispose().

#panes

<SchedulerPanes> takes the scheduler props plus panes ({ id, resources or rowFilter, size, minSize (48), hidden, props }), a required numeric height, timeHeader ('first'), scrollbar ('last'), splitter (true), crossPaneMove (true), component, onPaneResize and panesRef. linkPanes(controls, { zoom, rowHeaderWidth }) links existing controls and returns { dispose() }.

#zoom-ui

createZoomHud(control, { format, apiMs (700) }), createZoomSlider(control, container, { min, max, detents, scale ('log'), label }) and createLodBadge(control, container, labels?). Each returns { element, dispose() }.

#views

getViewState(control, include?) returns a JSON-safe state (zoom, scroll, density, collapsed, columns); applyViewState(control, state, { animate, when, timeout }) (when is 'now' or 'rows') returns a promise of boolean.

#ranges

createRangeLoader({ load, chunkDays (7), prefetch (1), cacheChunks (26), skeleton (true), onError }) returns a loader with reload(range?), clear() and loading. load({ start, end, signal }) returns the events overlapping [start, end).

#hooks

useScheduler({ track }) returns { controlRef, control, state } for the topics 'events', 'selection', 'zoom', 'viewport' and 'history'. useSchedulerState(control, topic), subscribeScheduler(control, topic, listener) (returns an unsubscribe function) and getSchedulerSnapshot(control, topic) give the same state outside the hook. Viewport state publishes after scrolling settles.

#react-render

SuperSchedulerComponent with the React content props. HTML or text fallback paints first; React content replaces it after the interaction ends. renderOptions.retain defaults to the smaller of 2,000 or twice the mounted items; sliceMs to 8.

#tailwind

A Tailwind CSS v3 preset: presets: [require('super-scheduler/tailwind')]. It adds super-scheduler colors, radii, shadows and transitions mapped to the CSS tokens.

#datasets

generateDataset(options) and generateScenario(id, overrides?) create deterministic hotel-style data (rows and days required, seed, start in ticks, density, events, times). toSuperSchedulerData(dataset) returns { resources, events }. Scenarios: S1 (120 rows, 730 days), S2 (1,000 rows, 730 days), S3 (5,000 rows, 1,500 days) and their dense variants. Data starts on 2026-01-01 by default.

#core

DOM-free helpers shared by the engine: SchedulerDate, Duration, registerLocale, resolveLocale, formatTicks, parseTicks, ticksFromParts(year, month, day, ...), partsOf, formatIso, parseIso, todayTicks, nowTicks, the MS_PER_* constants, and timeline, index and layout utilities. Use it for charts and tools next to the scheduler.

#Lite API

super-scheduler-lite is a read-only daily timeline. Options it does not implement throw SuperScheduler Lite: unsupported option "...", in every build.

The control (ref.current.control) has init(), update(options), dispose(), disposed(), scrollTo(date), scrollToResource(id), visibleStart() and visibleEnd(). The namespace has SuperScheduler.Date and SuperScheduler.Scheduler. Resource children, frozen, split and columns are rejected. Theme tokens on .super-scheduler-lite: --super-scheduler-background, -text, -border, -header, -event and -focus. See Migrating from Lite to Pro.

#Reserved APIs

These members are typed so that existing code compiles, but they are not implemented in 0.1.0. They do nothing, return empty values, and print super-scheduler: <feature> is not supported yet once in development builds.

Partially implemented:

• treeAnimation is accepted, but the expand animation is never played.
• eventClusters and onClusterClick are accepted and have no visible effect yet.
• The onBefore*DomAdd and onBefore*DomRemove handlers, the render* props and eventHover work only with the component from super-scheduler/react-render; the root component warns and ignores them.

Accepted tuning hints, ignored because virtualization is always on and tunes itself: beforeCellRenderCaching, cellSweeping, cellSweepingCacheSize, drawBlankCells, dynamicEventRendering and its margin and cache options, eventUpdateInplaceOptimization, progressiveRowRendering, progressiveRowRenderingPreload and the scrollDelay* options other than scrollDelayDynamic.