API Surface

A hand-written reference for @fluxgantt/core's public API. (An auto-generated reference will follow once the API stabilizes past 1.0.)

createGantt(config)

function createGantt(config: GanttConfig): GanttInstance;

Builds a headless GanttInstance. Throws if the initial tasks/dependencies are invalid (duplicate id, self-link, duplicate pair, or cycle).

Capability mixins

The base instance is state + compute only. Rendering, interaction and import/export each live behind an opt-in mixin on its own subpath, so a consumer only downloads what they compose:

import { createGantt } from '@fluxgantt/core';
import { withRender } from '@fluxgantt/core/render';
import { withInteraction } from '@fluxgantt/core/interaction';
import { withIo } from '@fluxgantt/core/io';
 
const gantt = withIo(withInteraction(withRender(createGantt({ tasks: [/* … */] }))));

Each mixin mutates and returns the SAME instance, so application order does not matter — but all of them must be applied before the first mount(): mount() reads the interaction hooks at mount time, so composing withInteraction onto an already-mounted instance takes effect only on the next mount.

The React and Vue wrappers compose withRender + withInteraction + withEditHooks + withViewport + withTheme + withRtl for you, and forward every GanttConfig field. All of them are construction-time only except onTaskChange and theme, which are reactive. The one deliberate deviation from "unset means core default": the wrappers' theme defaults to 'light', not 'auto' (wrapper charts have always been light); pass theme="auto" to follow the OS.

GanttConfig

GanttInstance methods

Tasks

Dependencies

Selection

Selection is hierarchical: selecting a parent selects every descendant with it, and the "selection" every method here reports is that flattened set.

Hierarchy (collapse / expand)

Base — always present, no mixin required; collapse state is headless.

History (undo / redo)

Every mutation through the facade — addTask, updateTask, moveTask, resizeTask, setProgress, removeTask, linkTasks, unlinkTasks, duplicateTask — records one undo entry per logical gesture, not per internal write. A cascade-grouped drag, a multi-select Delete, and a duplicateTask() that produced eight copies each undo in a single step.

None of these are gated by readOnly: that config governs rendered interactivity, not the method surface. All four throw after destroy() except canUndo/canRedo, which return false.

Wire buttons off the history:changed event rather than polling:

gantt.on('history:changed', ({ canUndo, canRedo }) => {
  undoButton.disabled = !canUndo;
  redoButton.disabled = !canRedo;
});

With withInteraction applied, a mounted chart also binds Ctrl/Cmd+Z and Ctrl/Cmd+Shift+Z to these — see the keyboard shortcut table.

Events emitted during an undo() or redo() carry a third meta argument, { source: 'undo' | 'redo' }, so a listener can tell a replayed change from a fresh one:

gantt.on('task:moved', (task, prevStart, meta) => {
  if (meta?.source) return; // replayed by undo/redo — don't re-persist it
  save(task);
});

Viewport (zoom)

The order is fixed: day → week → month → quarter → year. None of these are gated by readOnly — zoom changes no data. A mounted chart with withInteraction also binds Ctrl/Cmd+Plus / Ctrl/Cmd+Minus and Ctrl+wheel (which is how a macOS trackpad pinch arrives).

Scrolling and density

Added by withViewport (@fluxgantt/core/viewport). Call these after mount() — on a chart above 2000 tasks the Canvas renderer loads asynchronously, so wait for renderer:selected.

In SVG mode the mount container is the scroll viewport: give it a bounded height and overflow: auto (for example style="height: 420px; overflow: auto"). The SVG renderer does not make its container scrollable, so on a container without overflow the browser ignores the scroll offsets. The methods cannot detect that and still return true, because the return value reports that the target exists and a scroll was requested, not that the container moved. Canvas mode sets overflow-y: auto itself.

The date axis stays pinned to the top of the scroll viewport in both modes, and the label column is pinned to the inline-start edge on horizontal scroll as well (in Canvas mode it is a sticky sibling canvas.fg-timeline-canvas-labels, so select the chart with .fg-timeline-canvas, not container > canvas). In SVG mode everything lives in one wrapper, div.fg-timeline__layer, that holds the chart <svg> and three aria-hidden, position: sticky layers: the label column (svg.fg-timeline__sticky-column, clones of each row label and toggle), the date axis (svg.fg-timeline__sticky-header) and the top corner (svg.fg-timeline__sticky-corner). container.querySelector('svg') is still the chart (a container > svg child selector is not: the wrapper is in between), and the exported SVG never contains any layer. Consequences worth knowing:

• The container can be any display (block, flex, grid): the wrapper is a single in-flow child and aligns to start, so a flex column with an auto height has the chart's height and a flex row with a fixed height still pins.
• Container padding is a limit. A sticky box pins at the scroller's content edge, so with padding: P the band and the column stay P px inside the container and scrolled rows show in the strip. scrollToTask/scrollToDate are also off by P. Put the spacing on a wrapper.
• The pinned column's ground is opaque and is var(--fg-bg, #fff): set --fg-bg on the container (or an ancestor) to your page background, or a non-white page shows a white slab behind the names.
• The names are drawn by the clones; the real labels stay in the chart (accessible names, export) but are painted invisible live. A name wider than labelColumnWidth is therefore cut at the column edge on screen (the export keeps the full name); widen labelColumnWidth for long names.
• If the page itself scrolls (the container has no overflow), the layers pin to the browser viewport while the page scrolls through the chart. A fixed host navbar will cover the header.
• Right-to-left pages are supported: the layers follow the chart's inline-start edge.
• scrollToTask/scrollToDate use one model: align: 'start' parks the row directly under the 32px header, and the bar directly right of the pinned column; the usable area is clientHeight - 32 by clientWidth - labelColumnWidth, in SVG and Canvas alike.
• Pointer events: a click on a pinned label or toggle behaves exactly like one on the real label (select, Shift/Ctrl, collapse, task:activated, task:context-requested, touch pan). A click on the blank column or the date band clears the selection, like any blank chart space.
• Tests and host code that count [data-task-id], [data-row-index] or .fg-timeline__row-label over the whole container now also see the clones: scope them to svg.fg-timeline.
• While mounted, the container's inline scroll-padding-top is 32px so natively focus-scrolled rows stop below the header; your previous inline value is restored on unmount. Firefox ignores scroll-padding when it focuses an SVG row (it scrolls the container to the top); this predates the pinned header and Chromium and WebKit honour it.

behavior: 'smooth' falls back to an instant scroll under prefers-reduced-motion: reduce. None of these are gated by readOnly, and none is an undo step.

Calling setDensity() takes density ownership: withResponsive still adapts the label column and touch gestures but stops switching density. A host that pins 'compact' on a phone takes responsibility for touch-target size. The React/Vue density prop stays construction-time; call ref.setDensity() to change it later.

Computation

Schedule conflicts

Added by withConflicts (@fluxgantt/core/conflicts). Headless: it needs no withRender and no DOM.

import { createGantt } from '@fluxgantt/core';
import { withConflicts } from '@fluxgantt/core/conflicts';
 
const gantt = withConflicts(createGantt({ tasks, dependencies }));
gantt.detectConflicts(); // Conflict[] — the current state, a pure query
gantt.on('conflict:detected', (conflicts) => showWarnings(conflicts));

detectConflicts() reports where the schedule you authored contradicts a rule Core enforces elsewhere. That happens in schedulingMode: 'manual' (the default), after an import, after undo()/redo(), and for a task you drag earlier than its predecessor in 'auto' mode.

shortfallHours is exact up to a gap of about 100 years between the successor's start and requiredStart; beyond that it is a lower bound (it saturates), so one mistyped date cannot stall detection.

Under GanttConfig.rollup the renderers draw a summary task at its derived span, but dependency-violation uses the summary's authored start/end, exactly as the auto-scheduling cascade does. A dependency arrow that visibly runs backwards from or to a summary may therefore not be reported, and the reverse can also happen. Leaf-to-leaf dependencies are unaffected.

Conflicts come back in a stable order (kind, then id). The payload carries only ids, enums and numbers, never task names. Cycles, task constraints and resource over-allocation are not Core conflicts. Pass withConflicts(instance, { kinds: ['dependency-violation'] }) to opt out of a kind. The set of kinds may grow in minor releases, so keep a default branch in any switch (conflict.kind).

conflict:detected is a change notification, not a poll:

• It runs only while at least one listener is subscribed. With no listener there is no cost. Subscribing runs one full detection synchronously inside on(), and afterwards every store mutation (setProgress included) runs one detection per microtask turn. Measured with the polyfill on Node 24: about 10 ms per detection at 1,000 tasks / 2,000 dependencies when the dependencies are plain zero-lag FS/SS, about 0.3 to 0.8 s when every edge is violated or lagged, and 1.4 to 4.4 s in that worst case at 5,000 tasks. Native Temporal is faster. For very large charts, read detectConflicts() on demand instead of subscribing.
• It does not fire when you subscribe. Read the initial state with detectConflicts().
• It fires only when the set of conflicts changes (a conflict whose shortfallHours changes counts), with [] when the last conflict clears.
• It fires from a microtask, after the synchronous task:*, dependency:* and history:changed events of the mutation. A multi-step change (a cascading drag, an undo, an import) therefore produces one event and never announces a violation the same call fixes. Call detectConflicts() if you need the answer synchronously.

withConflicts is idempotent, so the wrappers do not need a prop for it. Options apply on the first call only: calling it again with different kinds logs a console.warn and keeps the first configuration. With React, seed the state with detectConflicts() because the event does not fire on subscribe:

const { instance } = useFluxGantt(config);
const [conflicts, setConflicts] = useState<readonly Conflict[]>([]);
useEffect(() => {
  const g = withConflicts(instance);
  setConflicts(g.detectConflicts());
  return g.on('conflict:detected', setConflicts);
}, [instance]);

In Vue, hold a shallowRef<readonly Conflict[]>([]), call withConflicts(instance) in onMounted, assign detectConflicts() to it, subscribe, and return the unsubscribe function from onUnmounted. Nothing is painted for a conflict yet: build your own indicator from the event and the data-task-id attributes the renderers expose.

Edit hooks

Added by withEditHooks (@fluxgantt/core/edit-hooks). FluxGantt ships no editor and no menu: it tells you what the user asked for, and your app (your form components, your i18n, your permissions) answers. It needs a mounted chart, and adds no methods. Pointer hooks work without withInteraction; keyboard access to every row needs it (see the keyboard note below).

import { withEditHooks } from '@fluxgantt/core/edit-hooks';
 
const gantt = withEditHooks(withInteraction(withRender(createGantt({ tasks }))));
 
gantt.on('task:activated', ({ taskId, clientX, clientY }) => {
  openEditor(gantt.getTask(taskId), { x: clientX, y: clientY });
});
gantt.on('task:context-requested', (p) => {
  p.preventDefault(); // suppress the browser's own menu
  gantt.select(p.taskId); // optional: right-click does not select by itself
  openMenu(p.taskId, p.clientX, p.clientY);
});

• part is 'bar', 'label' or 'row' (the grid or a dependency arrow). Keyboard gestures always report 'row'. The collapse toggle glyph, the header and empty space emit nothing. Canvas mode never reports 'bar' (its hit-test is row-wide): treat 'row' and 'bar' as "the task" and do not rely on 'bar'.

• Coordinates are viewport (client) coordinates. For keyboard gestures they are the centre of the focused row (the pinned label column, in both modes), an anchor for a popover.

• preventDefault() suppresses the native context menu (mouse, keyboard, and Android's touch menu) only if you call it synchronously inside the listener. With no listener, or a listener that does not call it, the browser menu opens as usual. This is deliberate: the React and Vue wrappers subscribe to every event, so "a listener exists" says nothing about whether you want the menu.

• Right-click does not select the task. Call gantt.select(payload.taskId) yourself if you want that.

• Read-only charts still emit both events. The event means "the user asked to open this task", not "the task is editable" (a read-only detail card on double-click is a normal use). Check your own readOnly before offering editing.

• Keyboard row navigation comes from withInteraction. The hooks' keys (Enter, F2, ContextMenu, Shift+F10) act on whichever row has focus. Without withInteraction only the first row is in the tab order and there are no arrow keys, so rows 2..n are reachable by pointer only. Apply withInteraction to keep every hook reachable from the keyboard.

• Enter on a summary row still collapses/expands it (with withInteraction). Use F2 or a double-click to open a summary. Without withInteraction there is no collapse behaviour, so Enter activates the focused row, summary or not.

• Touch. A long-press (500 ms) emits task:context-requested with source: 'long-press'. It is cancelled by pointer up, a second finger, or movement: 4 px on a bar (the drag threshold, so a drag always wins) and 8 px elsewhere. Once it fires, the gesture belongs to your menu: the chart ends the press for drag and selection, so moving the finger afterwards moves, resizes and links nothing, and releasing does not select. Change the delay with withEditHooks(gantt, { longPressMs }); 0 disables it. There is no double-tap activation, so include an "Edit" entry in the long-press menu for touch users. Compose withResponsive as well so the browser does not claim the gesture for scrolling.

• Platform caveats for touch. On Android 12+ Chrome fires its native contextmenu at about 400 ms, before the 500 ms default; the chart reports the long-press at that moment instead, so preventDefault() still works whatever longPressMs is. iOS Safari fires no contextmenu, so preventDefault() cannot stop its callout or the text-selection loupe. Add this to your CSS (core ships none):

  .fg-timeline__row, .fg-timeline__sticky-column { -webkit-touch-callout: none; user-select: none; }

• macOS Ctrl+click is reported by browsers as a right-click, so it fires task:context-requested and also toggles the selection.

• withEditHooks is not part of the all-capabilities bundle measured in CI; it adds about 1 KiB gzip over withRender. The React and Vue wrappers include it.

Returning focus is your job: when your editor or menu closes, put focus back where it was so keyboard users do not lose their place. Capture document.activeElement before you open the editor and restore it, falling back to the row for the task:

const opener = document.activeElement as HTMLElement | null;
// ... open the editor; on close:
(opener?.isConnected ? opener : document.querySelector<HTMLElement>(`[data-task-id="${CSS.escape(taskId)}"]`))
  ?.focus();

Clicking a bar moves the chart's keyboard position to that row, so arrow keys continue from it.

In React pass onTaskActivated / onTaskContextRequested to <FluxGantt>; in Vue listen to @task-activated / @task-context-requested. The payload's preventDefault() works in both, because the wrappers forward the event synchronously.

Import / Export

Requires the withIo mixin (@fluxgantt/core/io).

(The pure, instance-free importJson / importCsv functions are also exported from @fluxgantt/core/io — see Import & Export.)

Events & lifecycle

GanttEventMap

on() returns an UnsubscribeFn (() => void).

Three conventions hold across the whole map, and they are what make these events usable as a persistence hook:

• Snapshot, not delta. selection:changed, collapse:changed and critical-path:computed each carry the complete set. There is nothing to reconcile.
• No-ops are suppressed. Re-selecting what is already selected, collapsing what is already collapsed, zoomTo() with the current mode, undo() on an empty stack — none of these emit. So a listener firing means something genuinely changed.
• One fire per gesture, never per internal write. history:changed fires once for a whole cascade-grouped drag; an import fires data:imported once instead of task:added × N.
• Event timing: listeners see the final state. A mutation that writes more than once (a moveTask that cascades in schedulingMode: 'auto', removeTask of a subtree, undo()/redo() of a grouped step, duplicateTask, Delete on a multi-selection, an import) commits ALL of its writes first, repaints a mounted chart ONCE, and only then calls your listeners and onTaskChange, in the same order as before. So gantt.getTask() or the DOM inside a task:moved listener already shows every cascaded shift, and critical-path:computed fires at most once, before that mutation's other events, with the final critical set. A listener that starts another mutation runs it immediately, as its own command, nested inside that listener call, so the remaining queued events of the outer mutation can carry snapshots older than the store at delivery time. If an onTaskChange hook throws, the remaining events still fire and the first error is rethrown afterwards (unless the mutation itself threw: that error wins and the hook error is logged). The one exception to "repaints first": a mutation made inside your own signals.batch() emits its events before the repaint, because effects are deferred to the end of your batch.

The five task/dependency events take an optional third argument, meta?: { source: 'undo' | 'redo' }, present only when the change came from a replay — see History.

renderer:selected is the reliable way to know a large chart has become visible: above the 2000-task auto-switch threshold, mount() returns synchronously but the Canvas module loads and paints afterwards, and this event fires once it has (or once the SVG fallback has, with canvasFallbackReason set).

Standalone functions & values

Key types

TaskId, DependencyId, ResourceId, BaselineId, ProjectId (branded strings) · Task, TaskInput, TaskPatch, TaskKind, TaskConstraint · Dependency, DependencyInput, DependencyType · DateInput · WorkingCalendar, WeekdayCode, WorkingHours · CriticalPathResult, TaskSchedule, RollupResult · ViewMode, Density, SchedulingMode · Conflict, ConflictKind · GanttConfig, GanttInstance, GanttEventMap, GanttEventName, UnsubscribeFn · EventMeta, ViewportChangedPayload, RendererSelectedPayload, ImportSummary (event payloads) · GanttMessages (see i18n).