Gantt API
Complete API reference for @oge-ui/gantt. The kernel — the task-tree index, calendar-true time scales, forward auto-scheduling, the critical-path backward pass, orthogonal dependency routing and the gesture math — is pure TypeScript in the framework-free @oge-ui/gantt-engine package, which the React Gantt runs too; live demos are on the overview page.
Properties Methods Events Types
OgeGantt
oge-ganttProperties 26
Data
| Name | Type | Default | Description |
|---|---|---|---|
tasks | readonly T[] | [] | Task items — a plain array, copied into an internal working set; the input is never mutated. Edits surface through the past-tense events. |
dependencies | readonly D[] | [] | Dependency links between tasks; same working-set semantics as tasks. |
keyExpr / parentKeyExpr / titleExpr / startExpr / endExpr / progressExpr / colorExpr | string | ((item: T) => unknown) | 'id' / 'parentId' / 'title' / 'start' / 'end' / 'progress' / 'color' | Task field mapping: names (dotted paths reach nested objects) or getter functions. String dates parse as local wall time and write back in the same storage shape. |
baselineStartExpr / baselineEndExpr | string | ((item: T) => unknown) | 'baselineStart' / 'baselineEnd' | Baseline plan fields — tasks with both render the original plan as a slim bar under the live bar. |
dependencyKeyExpr / predecessorKeyExpr / successorKeyExpr / dependencyTypeExpr | string | ((item: D) => unknown) | 'id' / 'predecessorId' / 'successorId' / 'type' | Dependency field mapping. Types are 'FS' | 'SS' | 'FF' | 'SF' (dx numeric codes 0–3 also parse); missing type means FS. |
resources | readonly OgeGanttResource[] | [] | Resource choices: labels next to the bars, the multi-assignment tag editor in the task dialog, the workload band rows — and a resource's own calendar overrides workCalendar for its tasks (first assigned resource with a calendar wins). |
resourceIdExpr | string | ((item: T) => unknown) | 'resourceId' | The task's assigned resource field — a single id or an array of ids (multi-assignment). Write-back preserves the storage shape: array stores stay arrays, scalar stores stay scalar while at most one id is assigned. |
Appearance & behavior
| Name | Type | Default | Description |
|---|---|---|---|
scaleType | 'hours' | 'days' | 'weeks' | 'months' | 'days' | Timeline scale — calendar-true ticks (real month lengths, DST-safe). Two-way ([(scaleType)]); the toolbar zoom and Ctrl+wheel write it. |
firstDayOfWeek | number | undefined | — | First day of week (0 = Sunday) for the weeks scale; undefined resolves from the locale. |
columns | readonly OgeGanttColumn[] | title / start / end / duration | Task-list columns: built-in fields (title, start, end, duration, progress) or any data field, with optional header, widthPx and format. |
taskListWidth | number | 360 | Initial width (px) of the task pane; the splitter between the panes drags. |
taskTitlePosition | 'inside' | 'outside' | 'none' | 'inside' | Where the task title renders relative to its bar. |
showDependencies / showRowLines | boolean | true | Dependency arrows / horizontal row guides. |
showCriticalPath | boolean | false | Outlines the zero-slack chain (backward-pass latest-finish relaxation over all four link types). |
weekendsHighlighted / holidays | boolean / readonly Date[] | true / [] | Off-day shading on the days scale. |
weekendDays | readonly number[] | undefined | — | Weekend days (0 = Sunday … 6 = Saturday) weekendsHighlighted shades. undefined resolves from the locale via Intl.Locale#getWeekInfo() (Friday + Saturday in he-IL), falling back to Saturday + Sunday. A workCalendar takes precedence. |
workCalendar | OgeGanttWorkCalendar | null | null | Work-time calendar ({ workingDays?, holidays? }, 0 = Sunday): shades every off day and makes auto-scheduling roll pushed starts onto working days, preserving durations in working days. The holidays input merges in; per-resource calendars override it per task. |
showResourceWorkload | boolean | false | Renders the per-resource workload band under the chart: merged assignment segments per resource, overallocated stretches (concurrent assignments) in the danger color. |
stripLines | readonly OgeGanttStripLine[] | [] | Vertical markers: { start, end?, label?, color? } — a line without end, a shaded range with it (dx parity). |
autoScheduling | boolean | false | Forward-pass scheduling: moving a predecessor pushes its successors to satisfy FS/SS/FF/SF constraints (never pulls them earlier). |
locale | string | undefined | — | BCP 47 locale for every Intl format; defaults to the config locale, then the browser locale. |
messages | Partial<OgeGanttMessages> | {} | Per-instance message overrides, merged over the DI config per top-level block. |
selectedTaskKey | RowKey | null | null | The selected task. Two-way ([(selectedTaskKey)]). |
Editing gates
| Name | Type | Default | Description |
|---|---|---|---|
editingEnabled | boolean | true | Master editing switch (dx editing.enabled). |
allowTaskAdding / allowTaskUpdating / allowTaskDeleting / allowDependencyAdding / allowDependencyDeleting | boolean | true | Per-capability editing gates. |
readOnly | boolean | false | Display-only shorthand: equivalent to editingEnabled=false, hides every editing affordance. |
Methods 13
| Name | Type | Description |
|---|---|---|
insertTask(taskData) / updateTask(taskData, patch) / deleteTask(taskData) | void | Programmatic CRUD through the same cancelable pipelines as interactive editing — one undo step each. |
insertDependency(predecessorData, successorData, type?) / deleteDependency(dependencyData) | void | Guarded link CRUD; inserting runs the same cycle check as interactive drawing. |
undo() / redo() | void | Snapshot history — every applied edit, drags included, is exactly one step (depth: config undoLimit). |
zoomIn() / zoomOut() / zoomToFit() | void | Steps the scale (hours ⇄ days ⇄ weeks ⇄ months) / picks the scale that fits the whole plan and scrolls to it. |
scrollToDate(date) | void | Scrolls the chart so date is in view. |
expandAll() / collapseAll() / expandAllToLevel(level) / expandToTask(key) | void | Tree expansion control; expandToTask also selects and reveals the row. |
showTaskDetailsDialog(taskData?) | void | Opens the task dialog — edit form for the given task, prefilled create form without one. |
indentTask(task) / outdentTask(task) | void | Reparents through the guarded update pipeline: indent makes the task a child of its previous sibling (MS Project parity), outdent lifts it to the grandparent. Also on the built-in context menu and Alt+Shift+Left/Right on the focused row. |
focus() | void | Focuses the task tree (roving row). |
getExportData() | OgeGanttExportData<T> | Snapshot for the exporters: every task in tree order (collapse ignored), the resolved columns with pane-identical formatting, the chart range and the critical-path keys. |
Export entry points (lazy, optional peers)
| Name | Type | Description |
|---|---|---|
exportGanttToExcel(gantt, options?) / buildGanttExcelWorkbook(data, options?) | @oge-ui/gantt/export-excel | Lazy Excel export (exceljs peer): the task tree as a typed worksheet — indented titles, bold summary rows, real Date cells, an appended resource column. Import the entry point dynamically so exceljs stays out of the initial bundle. |
exportGanttToPdf(gantt, options?) / buildGanttPdfDocument(data, options?) | @oge-ui/gantt/export-pdf | Lazy PDF export (jspdf peer): the chart drawn as vector graphics — scale header, bars with progress fill, summary brackets, milestone diamonds, optional critical-path outlining, multi-page pagination. Text outside WinAnsi (Turkish ğ ş ı İ, Central European, Greek, Cyrillic) needs a Unicode TrueType font — per export, or once for every PDF via setOgePdfDefaultFont({ family, normal, bold }) from @oge-ui/behavior; without one the built-in Helvetica cannot draw it (a dev-mode warning says so). |
exportGanttToPng(gantt, options?) / buildGanttCanvas(data, options?) | @oge-ui/gantt/export-image | Lazy PNG export with no dependencies — plain canvas drawing of the same chart (configurable width, pixel ratio, background and critical-path outlining). |
Events 8
Editing (cancelable pipeline)
| Name | Type | Description |
|---|---|---|
taskInserting / taskUpdating / taskDeleting | OgeGanttTask*ingEvent<T> | Cancelable pre-events — set cancel = true to veto before the store changes. |
taskInserted / taskUpdated / taskDeleted | OgeGanttTask*edEvent<T> | Fired only for applied changes — persist from these. |
dependencyInserting / dependencyDeleting | OgeGanttDependency*ingEvent | Cancelable link pre-events; inserting carries predecessorKey, successorKey and type. |
dependencyInserted / dependencyDeleted | OgeGanttDependency*edEvent<D> | Applied link changes. |
taskEditDialogShowing | OgeGanttDialogShowingEvent<T> | Cancelable, before the task dialog opens; replace formItems to customize the form (dx onTaskEditDialogShowing parity). |
Interaction
| Name | Type | Description |
|---|---|---|
taskClick / taskDblClick / taskContextMenu | OgeGanttTaskClickEvent<T> | Bar/row pointer events with the normalized task and the raw MouseEvent. Right-click also opens the built-in context menu (edit, new task/subtask, indent/outdent, delete — labels in messages.menu); listen to taskContextMenu to add your own entries alongside it. |
selectionChanged | OgeGanttSelectionChangedEvent<T> | Single-row selection changed (task or null). |
scaleTypeChange / selectedTaskKeyChange | OgeGanttScaleType / RowKey | null | The two-way model outputs. |
Types 12
| Name | Type | Description |
|---|---|---|
OgeGanttTask<T> | interface | The normalized task — the payload of events and templates: key, parentKey, source (the original item), title, start/end, progress, color, baseline dates, isSummary/isMilestone and level. |
OgeGanttDependency<D> | interface | The normalized link: key, source, predecessorKey, successorKey, type. |
OgeGanttDependencyType | 'FS' | 'SS' | 'FF' | 'SF' | Finish-to-start, start-to-start, finish-to-finish, start-to-finish. |
OgeGanttScaleType | 'hours' | 'days' | 'weeks' | 'months' | The timeline scale units. |
OgeGanttColumn | interface | A task-list column: { field, header?, widthPx?, format? }. |
OgeGanttStripLine | interface | { start, end?, label?, color? } — a chart marker line or range. |
OgeGanttWorkCalendar | interface | { workingDays?, holidays? } — the work-time calendar (0 = Sunday; default working week Monday-Friday). |
OgeGanttResource | interface | { id, text, color?, calendar? } — one assignable resource (the resources item type). |
OgeGanttExportData<T> / OgeGanttExportColumn<T> | interface | The exporter snapshot: tasks, columns (header + pane-identical text()), rangeStart/rangeEnd, critical keys and resourceText(). |
OgeGanttTaskTitlePosition | 'inside' | 'outside' | 'none' | Task title placement relative to the bar. |
[ogeGanttTaskTemplate] | structural directive (OgeGanttTaskTemplate) | Replaces the bar's title content; context OgeGanttTaskTemplateContext: { $implicit: OgeGanttTask<T> }. |
[ogeGanttTooltipTemplate] | structural directive (OgeGanttTooltipTemplate) | Replaces the hover tooltip's content (default: title, dates + duration, progress, resources); context OgeGanttTooltipTemplateContext: { $implicit: OgeGanttTask<T> }. |
Configuration
Properties 5
| Name | Type | Default | Description |
|---|---|---|---|
provideOgeGanttConfig(config) | Provider | — | Configures every Gantt below the provider (OgeGanttConfigInput); shallow merge over OGE_DEFAULT_GANTT_CONFIG per top-level key — a partial messages replaces whole nested blocks. The token is OGE_GANTT_CONFIG (OgeGanttConfig). |
messages | OgeGanttMessages | — | Every user-facing string, aria labels included: toolbar (OgeGanttToolbarMessages), columns (OgeGanttColumnMessages), dialog (OgeGanttDialogMessages), grid (OgeGanttGridMessages, aria templates with {token} placeholders) and announcements (OgeGanttAnnouncementMessages, live-region templates). Defaults: OGE_DEFAULT_GANTT_MESSAGES. |
locale | string | undefined | — | BCP 47 locale for every Intl format in scope; a per-instance [locale] input wins. |
rowHeight | number | 36 | Fixed row height in px — the invariant behind the row virtualization of both panes. |
undoLimit | number | 50 | Undo history depth. |
Notes
- Dates are plain local
Dates throughout (Intl-only house rule — no date library, no adapter, no timezone database). The time scales are calendar-true: month ticks span real month lengths and DST transitions never shift a bar. - No WAI-ARIA APG gantt pattern exists. The widget composes the treegrid pattern: the task pane is a
role="treegrid"with roving-tabindex rows (arrows, Left/Right collapse/expand, Enter opens the dialog, Delete deletes), and the focused row drives its bar: Ctrl+Left/Right moves, Ctrl+Shift+Left/Right resizes as the keyboard equivalent of drag, announced through a polite live region. The chart itself is a focusable scroll region. - Binding plain arrays never mutates them — edits land in an internal working set and the past-tense events carry the data to persist. Every applied edit, interactive or programmatic, is exactly one snapshot undo/redo step.