Getting started
Install and initialize
With npm
npm install ts-gantt
import { TsGantt } from "ts-gantt";
const chart = new TsGantt("#container-selector");
include stylesheet ('ts-gantt/dist/styles.min.css') in any suitable way
Or using CDN
<link rel="stylesheet" href="https://unpkg.com/ts-gantt/dist/styles.min.css">
<script src="https://unpkg.com/ts-gantt/dist/ts-gantt.umd.min.js"></script>
const chart = new tsGantt.TsGantt("#container-selector");
⚠️for chart to function properly its container element must have relative, absolute or fixed position!
⚠️if you use the shadow DOM mode for the chart, including the stylesheet is not needed, the styles bundled inside the main file will be used.
Set your task list
your tasks must implement following interface
interface TsGanttTaskModel {
id: string;
parentId: string | null | undefined;
name: string;
progress: number;
datePlannedStart: Date | null | undefined;
datePlannedEnd: Date | null | undefined;
dateActualStart: Date | null | undefined;
dateActualEnd: Date | null | undefined;
localizedNames: {[key: string]: string} | null | undefined;
}
to pass your task array to chart use 'tasks' property setter
chart.tasks = yourTaskArray;
task are updated in the same way. you should just pass actual task array when any change happens. change detection will find tasks that have been changed/added/removed and will replace/add/remove them in chart.
Switch modes
Language
you can instantly switch chart language
chart.locale = locale;
Timeline scale
you can instantly switch chart timeline scale
chart.chartScale = scale;
Display mode (chart bars)
you can instantly switch chart bar display mode
chart.chartDisplayMode = mode;
"planned" - show only planned dates bar on timeline
"actual" - show only actual dates bar on timeline
Select tasks
select task rows programmatically
chart.selectedTasks = [{id: "taskIdString"}];
get selected tasks
const selectedTasks = chart.selectedTasks;
Customize chart
you can customize chart in two ways:
- edit or override styles in the styles file (if shadow DOM is not used)
- provide custom options to 'TsGantt' class constructor
Css
preffered way to customize styling is to change css variable values. It'll work for both regular DOM and shadow DOM modes
:root {
--tsg-table-min-width: 100px;
--tsg-chart-min-width: 100px;
--tsg-nesting-indent: 20px;
--tsg-background-color: white;
--tsg-foreground-color: black;
--tsg-separator-color: rgb(80, 80, 80);
--tsg-header-color: rgb(210, 210, 210);
--tsg-border-color: rgb(190, 190, 190);
--tsg-symbol-color: rgb(80, 80, 80);
--tsg-selection-color: rgb(230, 230, 230);
--tsg-scrollbar-track-color: #eeeeee;
--tsg-scrollbar-thumb-color: #b0b0b0;
--tsg-not-started-fg-color: dimgray;
--tsg-in-progress-fg-color: black;
--tsg-overdue-fg-color: darkred;
--tsg-completed-fg-color: darkgreen;
--tsg-completed-late-fg-color: sienna;
--tsg-today-line-color: orangered;
--tsg-chart-bar-color-1: skyblue;
--tsg-chart-bar-color-2: lightcoral;
--tsg-chart-bar-accent-1: darkcyan;
--tsg-chart-bar-accent-2: darkred;
--tsg-font-family: 'Calibri', sans-serif;
--tsg-font-size: 14px;
--tsg-line-height: 16px;
--tsg-max-cell-text-lines: 2;
}
Options
you can apply your custom options by passing options object as second parameter to 'TsGantt' constructor
const options = new TsGanttOptions({
multilineSelection: false,
enableChartEdit = true;
});
options.columnValueGetters[0] = task =>
task.localizedNames && task.localizedNames[options.locale] || task.name;
const chart = new TsGantt("#container-selector", options);
const chart = new tsGantt.TsGantt("#container-selector", options);
this.chart.destroy();
this.chart = new TsGantt("#container-selector", options);
ℹ️ complete list of 'TsGanttOptions' class properties you can use
useShadowDom = false;
multilineSelection = true;
useCtrlKeyForMultilineSelection = false;
drawTodayLine = true;
highlightRowsDependingOnTaskState = true;
separatorWidthPx = 5;
headerHeightPx = 90;
rowHeightPx = 40;
borderWidthPx = 1;
barStrokeWidthPx = 2;
barMarginPx = 2;
barCornerRadiusPx = 6;
rowSymbols: TsGanttRowSymbols = {childless: "◆", collapsed: "⬘", expanded: "⬙"};
chartShowProgress = true;
chartDisplayMode: "planned" | "actual" | "both";
chartScale: "day" | "week" | "month" | "year";
chartDateOffsetDays: {[key: string]: number} = {"day": 14, "week": 60, "month": 240, "year": 730};
chartDateOffsetDaysMin: {[key: string]: number} = {"day": 7, "week": 30, "month": 120, "year": 365};
chartDayWidthPx: {[key: string]: number} = {"day": 60, "week": 20, "month": 3, "year": 1};
locale = "en";
localeDecimalSeparator: {[key: string]: string} = {en: ".", uk: ",", ru: ",", ja: "."};
localeDateFormat: {[key: string]: string} = {en: "MM/DD/YYYY", uk: "DD.MM.YYYY", ru: "DD.MM.YYYY", ja: "YYYY/MM/DD"};
localeFirstWeekDay: {[key: string]: number} = {en: 0, uk: 1, ru: 1, ja: 0};
localeDateMonths: {[key: string]: string[]};
localeDateDays: {[key: string]: string[]};
localeDateDaysShort: {[key: string]: string[]};
localeDateScale: {[key: string]: string[]};
localeDurationFormatters: {[key: string]: (duration: number) => string};
columnsMinWidthPx: number[];
columnsContentAlign: ("start" | "center" | "end")[];
columnValueGetters: ((a: TsGanttTask) => string)[];
localeHeaders: {[key: string]: string[]};
taskComparer: (taskA: TsGanttTask, taskB: TsGanttTask) => number;
enableChartEdit = false;
Event callbacks
you can pass callbacks for chart row events using TsGantt properties shown below
onRowClickCb: (model: TsGanttTaskModel, event: MouseEvent) => void;
onRowDoubleClickCb: (model: TsGanttTaskModel, event: MouseEvent) => void;
onRowContextMenuCb: (model: TsGanttTaskModel, event: MouseEvent) => void;
onSelectionChangeCb: (models: TsGanttTaskModel[]) => void;
context menu implementation is not provided, but you can implement your own using callback
Adding a custom column to the end of the column list example
const options = new tsGantt.TsGanttOptions();
options.columnsMinWidthPx.push(100);
options.columnsContentAlign.push("center");
options.columnValueGetters.push(task => (task["customColumnKey"] ?? ""));
options.localeHeaders.en.push("User column");
const ganttChart = new tsGantt.TsGantt("#gantt-container", options);
TODO list
add optional multiple row selection added in 0.2.0make grid columns resizable added in 0.2.2add callbacks on chart events (on row click/double click, selection change) added in 0.3.0remove the hardcoded column number, allow adding custom columns added in 0.4.0move chart to shadow DOM added as an option in 0.5.0allow drag'n'drop grid column reordering added in 0.6.0add optional possibility to move/resize chart bars added in 0.7.0- implement applying changes to the parent task when changing dates for its child
- add event firing on task change
- add optional tooltips on bar hover
- increase code coverage
- optimize task change detection
- add row virtualization (move grid to custom table implementation)