Skip to content
GitHub
API reference

Working time & dates

Working hours, date overrides, duration units, and date-input helpers.

Usage

import type { GanttCalendar } from "@art-tools/react-gantt";

const calendar: GanttCalendar = {
  hours: ["9:00-12:00", "13:00-17:00"],
  days: { 0: false, 6: false },
  dates: { "2026-01-01": false },
};

// <Gantt tasks={tasks} calendar={calendar} durationUnit="hour" />
  • Supplying calendar opts into working-time scheduling. Without it, scheduling uses linear time. Calendar precedence is dates, then days, then hours. Omitted hours means the full day; false marks a day off.
  • Hours use local civil time with minute precision, such as 8:30-12:00. Ranges are half-open; 24:00 is allowed only as an end. Weekdays run from 0 (Sunday) to 6 (Saturday). Date keys use YYYY-MM-DD.
  • snapToWorking defaults to true. Setting it to false disables snapping of library-authored dates, while working-time duration arithmetic and non-working shading remain in effect. Consumer-supplied dates are not rewritten merely by supplying a calendar.
  • With a working calendar, one durationUnit day uses the longest working weekday in the week. Working-time walks use civil dates, including across daylight-saving changes.
  • displayEndDate is for displaying an inclusive last day. endInstantFromDisplayDate converts a chosen whole-day end to the following local midnight. Preserve exact stored instants when an editor leaves a date unchanged.

The chart's working-time calendar. Three scopes resolve in the order `dates` → `days` → `hours`, so a specific date beats a weekday rule, which beats the global default. Passing a calendar at all is the opt-in: with no `calendar` prop the chart schedules in plain linear time exactly as it did before this feature existed. The object may be written inline — it is keyed by content, not identity, so a fresh-but-equal object on every render costs nothing.

GanttCalendar documented properties
PropertyType & description
hoursOptionalDayHours

Working hours for every day with no override below. Omitted means the *full* day (`"0:00-24:00"`), so a calendar that only lists weekend days off stays day-granular rather than silently acquiring business hours.

daysOptionalPartial<Record<Weekday, DayHours>>

Per-weekday override. Beats GanttCalendar.hours.

datesOptionalRecord<string, DayHours>

Per-date override keyed by local civil date, `"YYYY-MM-DD"`. Beats both GanttCalendar.days and GanttCalendar.hours. Use it for holidays (`false`), half days, or a one-off working Saturday.

TypeScript declaration
/**
 * The chart's working-time calendar. Three scopes resolve in the order
 * `dates` → `days` → `hours`, so a specific date beats a weekday rule, which
 * beats the global default.
 *
 * Passing a calendar at all is the opt-in: with no `calendar` prop the chart
 * schedules in plain linear time exactly as it did before this feature existed.
 *
 * The object may be written inline — it is keyed by content, not identity, so a
 * fresh-but-equal object on every render costs nothing.
 */
export declare interface GanttCalendar {
    /**
     * Working hours for every day with no override below. Omitted means the
     * *full* day (`"0:00-24:00"`), so a calendar that only lists weekend days off
     * stays day-granular rather than silently acquiring business hours.
     */
    hours?: DayHours;
    /** Per-weekday override. Beats {@link GanttCalendar.hours}. */
    days?: Partial<Record<Weekday, DayHours>>;
    /**
     * Per-date override keyed by local civil date, `"YYYY-MM-DD"`. Beats both
     * {@link GanttCalendar.days} and {@link GanttCalendar.hours}. Use it for
     * holidays (`false`), half days, or a one-off working Saturday.
     */
    dates?: Record<string, DayHours>;
}

Working hours for a single day, or `false` for a day off. Gaps *between* ranges are non-working — that is how a lunch break is expressed: `["8:00-12:00", "13:00-17:00"]`.

/**
 * Working hours for a single day, or `false` for a day off. Gaps *between*
 * ranges are non-working — that is how a lunch break is expressed:
 * `["8:00-12:00", "13:00-17:00"]`.
 */
export declare type DayHours = WorkTimeRange[] | false;

A span of working hours within one day, `"H:MM-H:MM"` in local civil time with minute precision — e.g. `"8:30-12:00"`. Half-open: the end minute is the first non-working minute. `"24:00"` is legal only as an end.

/**
 * A span of working hours within one day, `"H:MM-H:MM"` in local civil time with
 * minute precision — e.g. `"8:30-12:00"`. Half-open: the end minute is the first
 * non-working minute. `"24:00"` is legal only as an end.
 */
export declare type WorkTimeRange = string;

`0` = Sunday … `6` = Saturday, matching `Date.prototype.getDay`.

/** `0` = Sunday … `6` = Saturday, matching `Date.prototype.getDay`. */
export declare type Weekday = 0 | 1 | 2 | 3 | 4 | 5 | 6;

The unit an input `duration` is expressed in, and the unit it displays in.

/** The unit an input `duration` is expressed in, and the unit it displays in. */
export declare type DurationUnit = "day" | "hour" | "minute";

Why a column is shaded. Weekend vs holiday matters only for styling.

/** Why a column is shaded. Weekend vs holiday matters only for styling. */
export declare type NonWorkingReason = "weekend" | "holiday" | "offHours";

The inclusive last-occupied civil day, for **display only**. Stored dates are exclusive instants, which reads wrong in a column: a task running Monday through Friday stores Saturday. This converts back for humans — the day containing the last worked moment. Never write the result back to a task.

/**
 * The inclusive last-occupied civil day, for **display only**.
 *
 * Stored dates are exclusive instants, which reads wrong in a column: a task
 * running Monday through Friday stores Saturday. This converts back for humans —
 * the day containing the last worked moment. Never write the result back to a task.
 */
export declare function displayEndDate(startDate: Date, endInstant: Date): Date;

Inverse of displayEndDate for a whole-day edit: the exclusive instant starting the day after `displayEnd`. This is what a `<input type="date">` end-date editor needs — the user picks the last day they mean, and the task stores the following midnight.

/**
 * Inverse of {@link displayEndDate} for a whole-day edit: the exclusive instant
 * starting the day after `displayEnd`.
 *
 * This is what a `<input type="date">` end-date editor needs — the user picks the
 * last day they mean, and the task stores the following midnight.
 */
export declare function endInstantFromDisplayDate(displayEnd: Date): Date;

Related examples