Troubleshooting

Find the symptom, check the cause, apply the fix. Sections apply to Pro and Lite unless they name one edition. If your problem is not here, the API reference lists every implemented option with its default, and its reserved APIs section lists what is typed but not implemented.

#The scheduler renders without styles

Symptom. Rows and events appear, but without grid lines, colors or aligned headers.

Cause. The stylesheet is not loaded, or the wrong edition's stylesheet is.

Fix. Import it once, in your entry point or root layout: import 'super-scheduler/styles.css' for Pro, import 'super-scheduler-lite/styles.css' for Lite. The Pro stylesheet lives in @layer super-scheduler with zero-specificity selectors, so any unlayered rule of yours wins; a broad reset such as * { border: 0 } therefore removes the library's borders too (see Tailwind). unstyled turns the library's visual rules off on purpose.

#The scheduler is 0 px tall or not the height you set

Symptom. Nothing is visible, or the grid is shorter or taller than expected.

Causes and fixes (Pro).

• heightSpec defaults to 'Max': height (600 by default) is a ceiling, and the grid is as tall as its rows up to that value. Two rows with height={320} render about 130 px tall. Use heightSpec="Fixed" for a constant box.
• height="100%" fills the component's host element, an unstyled <div> that SuperSchedulerComponent renders inside your wrapper. If that <div> has no height, the scheduler collapses to 0 px. Give the wrapper a definite height and the host 100%:

import { SuperSchedulerComponent } from 'super-scheduler'
import type { SuperScheduler } from 'super-scheduler'

interface Props {
  readonly rooms: SuperScheduler.ResourceData[]
  readonly events: SuperScheduler.EventData[]
}

// height="100%" fills the component's own host <div>: .fill sizes it (see the CSS below).
export function FillParent({ rooms, events }: Props) {
  return (
    <div className="fill">
      <SuperSchedulerComponent
        height="100%"
        startDate="2026-10-01"
        days={31}
        scale="Day"
        resources={rooms}
        events={events}
      />
    </div>
  )
}

.fill {
  height: 70vh; /* or a flex item with min-height: 0 */
}
.fill > div {
  height: 100%;
}

• heightSpec="Auto" sizes the control to its content with no vertical scrollbar, so the page scrolls instead.
• SchedulerPanes takes its own numeric height for all panes together.

In Lite, height is always a fixed number of pixels (400 by default). In both editions, when the wrapper is a flex item, give it min-width: 0 in a row (or min-height: 0 in a column); otherwise the flex item's automatic minimum size can let the grid push the layout wider or taller instead of scrolling.

#ref.current or control is null

Cause. The control is created in componentDidMount. During the first render, on the server and after unmount, there is no live control: ref.current is null before mount, and ref objects passed as controlRef are reset to null on unmount.

Fix. Read the control in effects and event handlers, never during render. useSchedulerControl() returns the control as state, so an effect can depend on it:

import { useEffect } from 'react'
import { SuperScheduler, SuperSchedulerComponent, useSchedulerControl } from 'super-scheduler'

const START = SuperScheduler.Date.today().addDays(-30)

export function Planning({ rooms }: { rooms: SuperScheduler.ResourceData[] }) {
  // `control` is null during the first render and the live control after mount.
  const { controlRef, control } = useSchedulerControl()

  useEffect(() => {
    if (control === null || control.disposed()) return
    control.scrollTo(SuperScheduler.Date.today(), false, 'middle')
  }, [control])

  return (
    <SuperSchedulerComponent
      controlRef={controlRef}
      startDate={START}
      days={90}
      scale="Day"
      resources={rooms}
    />
  )
}

In Pro, a function controlRef is called with the control on mount and is not called with null on unmount. A control reference kept from before an unmount points to a disposed control: check control.disposed() in asynchronous code. With the imperative API, call init() before anything else; update() before init() throws SuperScheduler.Exception.

#Nothing shows in the grid

Check these in order:

1. Range. days defaults to 1 and startDate to today. In Pro, scale also defaults to hourly cells ('CellDuration' with 60 minutes). Set startDate, days and scale="Day" to the period your data covers. Datasets from super-scheduler/datasets start on 2026-01-01 by default.
2. Date strings. '2026-10-01T10:00' throws SchedulerDate: "2026-10-01T10:00" is not an ISO 8601 date. Use '2026-10-01' or '2026-10-01T10:00:00'. Native Date objects do not type-check; convert them (see civil dates).
3. Resource ids. An event's resource must equal a resource id exactly: 1 and '1' are different. Events of unknown resources are not drawn.
4. Trees (Pro). children render only with treeEnabled, and a parent shows its children only when it has expanded: true.
5. Filters and flags. An active control.events.filter() or control.rows.filter(), or hidden: true on the event, hides it.
6. Empty state. With no visible rows, Pro shows emptyState if you set it; Lite shows "No resources" by default.

#Changes do not appear

• Mutated in place. The React component forwards a prop only when its identity changes. Pushing into the same events or resources array and re-rendering sends nothing. Pass a new array, or call control.update() after an in-place edit.
• The array changes by itself (Pro). The control adopts the events array you pass and splices it when events are added, removed or committed. Pass a copy (useMemo(() => events.slice(), [events])) if that array is shared state. A frozen array, as some state libraries produce in development, makes control.events.add, update and remove throw TypeError.
• Updating an unknown id. control.events.update(data) does nothing when the id is not loaded; use add for new events. add throws on a duplicate id.
• defaultEvents changed. It is read once at init(); later values are ignored with a development warning. Use controlled events for data that changes.
• Cell hooks (Pro). onBeforeCellRender results are cached per cell. If a cell depends on events, set cellsAutoUpdated: true on its resource or call control.update().
• A prop removed. A prop that disappears between renders returns to its default value.

#Import errors and wrong subpaths

Only these entry points exist; anything else, such as super-scheduler/dist/..., fails with a "not exported" error from your bundler or Node:

• Pro: super-scheduler, /styles.css, /react-render, /history, /minimap, /panes, /zoom-ui, /views, /ranges, /hooks, /tailwind, /datasets and /core.
• Lite: super-scheduler-lite and super-scheduler-lite/styles.css only. Pro modules are not part of Lite.

TypeScript resolves these through the package exports with moduleResolution set to bundler, node16 or nodenext; the older node setting works through the package's typesVersions. With noUncheckedSideEffectImports (TypeScript 5.6 and later), a stylesheet import needs a declare module '*.css' declaration, which bundler client types such as vite/client already provide. super-scheduler/tailwind is a CommonJS-style preset: load it with require('super-scheduler/tailwind'), or with a default import where your config supports CommonJS interop.

#Console messages

Pro prints these warnings only when NODE_ENV is not production, and reserved-API warnings only once per feature. Lite's errors are thrown in every build.

#"Invalid hook call" or two copies of React

Symptom. "Invalid hook call" from useSchedulerControl or useScheduler, React content in render slots that cannot see your context providers, or portal errors.

Cause. The library resolves a different copy of React than your app. Both editions declare React as a peer dependency and never bundle it, so this happens when the install or a link brings a second copy: a linked or locally built package, a monorepo with several React versions, or unmet peer ranges (18.2 or later, or 19).

Fix. npm ls react react-dom must show one version. Install the Pro tarball instead of linking a local copy. In Vite, add resolve: { dedupe: ['react', 'react-dom'] }; in webpack, alias react and react-dom to your app's copies.

#Content Security Policy errors

The library needs no inline scripts and no 'unsafe-inline' styles: it loads as modules and writes geometry through element.style. If the console reports violations, check three things: lazily loaded chunks must be allowed by script-src; the Pro stylesheet's small data: SVG images need img-src data:; and inline style attributes inside HTML strings you pass (html, bubbleHtml) are blocked, so use classes. Details and a sample policy are in Server rendering.

#Tailwind removes borders or overrides the scheduler

Tailwind v3's preflight is unlayered and resets borders on every element, which beats the library's layered rules. Put preflight in a layer below SuperScheduler:

@layer tw-base, super-scheduler;

@import 'super-scheduler/styles.css';

@layer tw-base {
  @tailwind base;
}
@tailwind components;
@tailwind utilities;

With Tailwind v4, declare the layer order before the imports so the library sits between base and your utilities:

@layer theme, base, super-scheduler, components, utilities;

@import 'tailwindcss';
@import 'super-scheduler/styles.css';

See Theming for the Tailwind preset and token mapping.

#Other surprises

• Events snap to whole days (Pro). useEventBoxes defaults to 'Always', which draws events over whole cells. Use 'Never' to draw exact times, and add eventMoveByCell if dragging should stay anchored to cells.
• A click leaves a selection behind (Pro). A click on an empty cell is a one-cell selection reported to onTimeRangeSelected with origin: 'click', and its shadow stays until the next selection or a click elsewhere. Call args.control.clearSelection() in the handler.
• Keys do nothing (Pro). keyboardEnabled defaults to false. keyboardMode="Full" needs it too. With several schedulers on a page, set keyboardTarget="component".
• Dates became objects (Pro). After a drag or resize, the event's start and end are SuperScheduler.Date objects. String(date) and JSON.stringify give the civil ISO value; date.toString('d MMM', locale) formats it.
• Wrong weekday. SuperScheduler.Date#getDay() returns the day of the month. Use getDayOfWeek() (0 is Sunday) or dayOfWeekISO() (1 is Monday).

Related guides: React integration, Controlled state, Server rendering and Virtualization and performance.