Skip to main content

Calendars

The functionality is available in PRO Edition only

PRO

This guide shows you how to configure working-time calendars in Gantt, from a single global schedule to per-task and per-resource assignments.

When to use calendar and calendars​

Use calendar alone when every task follows the same working-time rules. Pass true for the default 8-hour Mon–Fri week, or a config object to customize it.

Use calendars when different tasks or resources need different working-time rules. Define each entry with an id, then reference it as task.calendar or resource.calendar. Set calendar alongside calendars to define the fallback for tasks and resources that have no calendar assigned. Point it at an existing entry by id (calendar: "standard"), or pass a config object or true directly if you don't need the fallback to be reusable.

Where each calendar applies:

  • Use task.calendar when you need task bar length, duration math, drag, resize, auto-scheduling, critical path, and standard timeline row shading to follow that task's working-time rules. Falls back to the global calendar if not set.
  • Use resource.calendar when you need row shading in grouped view and the resource-load grid to reflect that resource's non-working days. Task bar length still follows the task or global calendar.
  • Resource load cell values use the intersection: min(task-calendar hours, resource-calendar hours) for each day.

Apply the default calendar​

Pass calendar={true} to apply the built-in 8-hour Mon–Fri working week without any configuration:

<Gantt calendar={true} tasks={tasks} links={links} />

Gantt uses this calendar for all duration calculations, drag-and-resize operations, auto-scheduling, and non-working day column highlights.

note

The calendar operates at the day level. You can set the number of working hours per day, but not specific hour ranges within the day (for example, 09:00–13:00).

Configure a custom global calendar​

Pass CalendarConfig object to the calendar prop to define your own working-week pattern. The example sets an 8-hour Mon–Fri schedule:

import { Gantt } from "@svar-ui/react-gantt";
import { getData } from "../data";

const { tasks, links } = getData();

export default function App() {
  return (
    <Gantt
      calendar={{ weekHours: { monday: 8, tuesday: 8, wednesday: 8, thursday: 8, friday: 8 } }}
      tasks={tasks}
      links={links}
    />
  );
}

Each day you omit from weekHours defaults to 0 hours (non-working). Set friday: 4 for a half-day Friday, or omit saturday and sunday entirely for a Mon–Fri-only week.

info

Always provide valid date values when updating tasks. If you update a task through the update-task action, include all date fields: start, end, and duration. Calendars support durationUnit: "day" only.

Define multiple calendars​

Use the calendars prop when different tasks or resources need different working-time rules. Each entry requires a unique id that tasks and resources use to select their working-time schedule.

import { Gantt } from "@svar-ui/react-gantt";

const calendars = [
  {
    id: "standard",
    name: "Standard",
    weekHours: { monday: 8, tuesday: 8, wednesday: 8, thursday: 8, friday: 8 },
  },
  {
    id: "part-time",
    name: "Part-time",
    weekHours: { monday: 4, tuesday: 4, wednesday: 4, thursday: 4, friday: 4 },
  },
  {
    id: "weekends",
    name: "Weekends",
    weekHours: { saturday: 8, sunday: 8 },
    css: "weekend-shift",
  },
];

export default function App() {
  return (
    <Gantt
      calendars={calendars}
      calendar="standard"
      tasks={tasks}
      resources={resources}
    />
  );
}

Set calendar to a calendar id to nominate that entry as the global default. It applies to any task or resource that has no calendar set.

Assign a calendar to a task​

Add calendar property to a task and set it to the id of calendars entry. Gantt then uses that calendar for duration math, drag-and-resize, end-date computation, auto-scheduling, and critical-path analysis for that task.

const tasks = [
  { id: 1, text: "Regular work",       start: "2024-01-15", duration: 40 },
  { id: 2, text: "Server maintenance", start: "2024-01-20", duration: 16, calendar: "weekends" },
];

Task bar length always follows the task's calendar, regardless of which resource the task is assigned to. This keeps bar geometry consistent across the standard timeline, grouped view, and resource-load grid.

Assign a calendar to a resource​

Refer to Resource calendar for the instructions about assigning a calendar to a resource.

Add rules and exceptions​

Pass rules array inside any calendar config to override specific dates, ranges, or weekday patterns. Rules apply on top of weekHours and always take priority.

The example adds a fixed holiday, a company shutdown range, and a recurring New Year's Day:

const calendars = [
  {
    id: "standard",
    name: "Standard",
    weekHours: { monday: 8, tuesday: 8, wednesday: 8, thursday: 8, friday: 8 },
    rules: [
      { type: "date",      date: "2024-07-04",  hours: 0, name: "Independence Day"  },
      { type: "range",     start: "2024-12-24", end: "2024-12-26", hours: 0, name: "Holiday shutdown" },
      { type: "recurring", month: 1, day: 1,    hours: 0, name: "New Year's Day"    },
      { type: "weekday",   month: 11, weekday: "thursday", nth: 4, hours: 0, name: "Thanksgiving" },
    ],
  },
];

See Calendar properties for the full shape of each rule type.

Modify a calendar at runtime​

The object returned by api.getCalendar() is a live calendar instance from the underlying scheduler library. If you modify it directly, Gantt does not detect the change automatically. Reassign tasks to trigger recalculation:

const cal = api.getCalendar("standard");
// modify the calendar instance here
tasks = api.serialize();

To capture the current state of a calendar after modifications, serialize the instance directly:

const config = api.getCalendar("standard").serialize();

The inline global calendar doesn't appear in api.serialize({ data: "calendars" }) because it lives outside the registry. Use api.getCalendar().serialize() to capture it separately.

Non-working time highlighting​

When a global calendar is set, Gantt derives column highlighting from it and ignores the highlightTime prop.

Row-level highlighting follows a different source depending on the active view:

ViewRow highlight source
Standard timelinetask.calendar
Grouped by resourceresource.calendar
Resource load gridresource.calendar

When a task's calendar differs from its resource's calendar in grouped view, the row shading reflects the resource's non-working days while bar length follows the task's calendar. Use the resource-load grid to inspect the actual working hours per day.

Related samples:

Related articles: