IApi

The IApi interface provides programmatic access to the Gantt component. Use it to execute actions, subscribe to events, intercept and cancel actions, read state, and integrate data providers.

Obtaining the API

Pass an init callback to the <Gantt> component. The callback receives the IApi instance immediately after mount.

<script>
  import { Gantt } from "@svar-ui/svelte-gantt";
  import type { IApi } from "@svar-ui/svelte-gantt";

  let ganttApi: IApi;

  function init(api: IApi) {
    ganttApi = api;
    // attach listeners, interceptors, providers here
    api.on("select-task", ({ id }) => {
      console.log("Task selected:", id);
    });
  }
</script>

<Gantt {tasks} {links} {init} />

Alternatively, bind the component instance directly (the component exposes the same IApi interface):

<script>
  let api = $state();
</script>

<Gantt bind:this={api} {tasks} {links} />

TypeScript definition

export interface IApi {
  exec<A extends keyof TMethodsConfig | (string & {})>(
    action: A,
    params?: A extends keyof TMethodsConfig ? TMethodsConfig[A] : any
  ): Promise<any>;

  on<A extends keyof TMethodsConfig | (string & {})>(
    action: A,
    callback: (config: A extends keyof TMethodsConfig ? TMethodsConfig[A] : any) => any,
    config?: IEventConfig
  ): void;

  intercept<A extends keyof TMethodsConfig | (string & {})>(
    action: A,
    callback: (config: A extends keyof TMethodsConfig ? TMethodsConfig[A] : any) => any,
    config?: IEventConfig
  ): void;

  detach(tag: IEventConfig["tag"]): void;

  getState(): IData;
  getReactiveState(): { [Key in keyof IData]: IPublicWritable<IData[Key]> };

  setNext(ev: IEventBus<TMethodsConfig>): void;

  getStores(): { data: DataStore };
  getTable(waitRender?: boolean): Promise<ITableApi> | ITableApi;
  getTask(id: TID): ITask;
  serialize(): ITask[];
}

Methods

exec()

Executes a Gantt action programmatically. See Actions for all available actions and their parameters.

string

required

The action name, e.g. "add-task", "update-task", "select-task".

object

Parameters for the action. The type is inferred from TMethodsConfig based on the action name.

Returns: Promise<any> — resolves after the action and all handlers have run.

// Add a new task
await api.exec("add-task", {
  task: { text: "New task", start: new Date(), duration: 3 }
});

// Update an existing task
await api.exec("update-task", {
  id: 42,
  task: { text: "Updated name", progress: 75 }
});

// Scroll the chart to a specific date
api.exec("scroll-chart", { date: new Date("2024-06-01") });

on()

Subscribes to an action event. The callback fires after the action has been processed.

string

required

The action name to listen to.

(params) => any

required

Called with the action parameters after the action completes. The params object may be mutated by the store (e.g. id is set on add-task after the task is created).

IEventConfig

Optional configuration object. Set config.tag to a symbol or string to group listeners for later removal via detach().

const tag = Symbol();

api.on("add-task", ({ id, task }) => {
  console.log("Task added with id:", id, task);
}, { tag });

api.on("delete-task", ({ id }) => {
  console.log("Task deleted:", id);
}, { tag });

// Remove all listeners in the tag group later
api.detach(tag);

intercept()

Registers a handler that fires before an action is processed. Return false from the callback to cancel the action entirely.

string

required

The action name to intercept.

(params) => any

required

Called with the action parameters before the action is processed. Return false to prevent the action from executing.

IEventConfig

Optional configuration. Set config.tag for grouped removal.

// Prevent deletion of tasks with subtasks
api.intercept("delete-task", ({ id }) => {
  const task = api.getTask(id);
  if (task.data?.length) {
    alert("Cannot delete a task that has subtasks.");
    return false;
  }
});

// Prevent dragging (reordering) tasks
api.intercept("drag-task", (ev) => {
  if (typeof ev.top !== "undefined") return false; // block reorder
  return true; // allow horizontal drag
});

detach()

Removes all on() and intercept() listeners associated with the given tag.

symbol | string

required

The tag value used when registering listeners.

const tag = Symbol("myListeners");
api.on("add-task", handler, { tag });
api.on("update-task", handler2, { tag });

// Later — removes both listeners at once
api.detach(tag);

getState()

Returns the current internal state snapshot as a plain object. Useful for reading task lists, current selection, scroll position, and scale data. Returns: IData — the full state object.

const state = api.getState();
console.log(state.selected);    // array of selected task IDs
console.log(state.scrollLeft);  // current horizontal scroll
console.log(state._tasks);      // flat array of positioned tasks

getReactiveState()

Returns reactive Svelte writable stores for each state key. Subscribe to these in Svelte components for live updates. Returns: { [Key in keyof IData]: IPublicWritable<IData[Key]> }

<script>
  let selected = $state([]);

  function init(api) {
    const { selected: selectedStore } = api.getReactiveState();
    selectedStore.subscribe(ids => {
      selected = ids;
    });
  }
</script>

setNext()

Connects a data provider (e.g. RestDataProvider) to the API event bus. The provider receives all actions and persists changes to the backend.

IEventBus<TMethodsConfig>

required

A data provider instance that implements IEventBus. Typically a RestDataProvider.

import { RestDataProvider } from "@svar-ui/gantt-data-provider";

function init(api) {
  const provider = new RestDataProvider("/api");
  api.setNext(provider);
}

getStores()

Returns the internal data store instances. Primarily used for advanced integrations. Returns: { data: DataStore }

getTable()

Returns the underlying grid API instance for direct grid manipulation.

boolean

When true, returns a Promise that resolves after the next render cycle completes. Useful if you need to access the grid immediately after a state change.

Returns: ITableApi | Promise<ITableApi>

getTask()

Returns a task object by ID from the current state.

string | number

required

The task ID to look up.

Returns: ITask — the task object, or undefined if not found.

const task = api.getTask(42);
console.log(task.text, task.start);

serialize()

Returns the current task tree as a flat array of plain task objects, suitable for saving or sending to a server. Returns: ITask[]

const tasks = api.serialize();
fetch("/api/tasks", {
  method: "POST",
  body: JSON.stringify(tasks)
});

Components

Data Types

API Object

Data Provider

Obtaining the API

TypeScript definition

Methods

exec()

on()

intercept()

detach()

getState()

getReactiveState()

setNext()

getStores()

getTable()

getTask()

serialize()

​Obtaining the API

​TypeScript definition

​Methods

​exec()

​on()

​intercept()

​detach()

​getState()

​getReactiveState()

​setNext()

​getStores()

​getTable()

​getTask()

​serialize()

Obtaining the API

TypeScript definition

Methods

exec()

on()

intercept()

detach()

getState()

getReactiveState()

setNext()

getStores()

getTable()

getTask()

serialize()