Calendar and Working Days
ApexGantt's working calendar affects how duration math, summary aggregation, dependency lag, the critical path and timeline stripes handle non-working time. Without a calendar option, every day is treated as a working day.
Since 3.20.0 any calendar object you pass, even calendar: {}, turns the working calendar on with a Monday to Friday week. Before 3.20.0 the calendar took effect only when workingWeekdays or holidays was set, so calendar: { showNonWorkingStripes: true } on its own did nothing.
The exception, since 3.22.0, is a calendar that holds only weekStart and fiscalYearStartMonth: those shape the timeline header and leave every day a working day.
Basic setup
Set which weekdays count as working days and which dates are holidays:
const gantt = new ApexGantt(document.getElementById('chart'), {
inputDateFormat: 'YYYY-MM-DD', // since 3.20.0 holiday strings are read with the same format as task dates
series: tasks,
calendar: {
workingWeekdays: [1, 2, 3, 4, 5], // Mon-Fri (0 = Sunday)
holidays: [
'2024-01-01', // New Year's Day
'2024-12-25', // Christmas
],
},
})
CalendarOptions reference
| Option | Type | Default | Description |
|---|---|---|---|
workingWeekdays | number[] | [1,2,3,4,5] | Weekdays that count as working (0 = Sunday, 6 = Saturday). Since 3.20.0 numeric strings ('1') are read as numbers, and a list that names no weekday from 0 to 6 logs a warning and uses Monday to Friday |
holidays | HolidayEntry[] | [] | Specific non-working dates, regardless of weekday. Since 3.20.0 strings are read with inputDateFormat (ISO YYYY-MM-DD always works) |
showNonWorkingStripes | boolean | true | Render tinted bands over non-working timeline columns |
holidayTooltip | (ctx) => string | None | HTML string rendered when hovering a holiday stripe |
dragSnapMode | 'next' | 'previous' | 'allow' | 'next' | What happens when drag/resize lands on a non-working day |
weekStart | number | A locale pack's weekStart, else the date locale's, else 0 | Since 3.22.0. First day of the week (0 = Sunday) for week cells and week numbers in the timeline header. Does not change working days |
fiscalYearStartMonth | number | Unset (calendar years) | Since 3.22.0. First month of the fiscal year (1 = January); quarter and year cells and their labels follow it. Since 3.23.0 any valid month, 1 included, gives fiscal labels. Does not change working days |
weekStart and fiscalYearStartMonth are covered in Week start and fiscal year. Note that workingWeekdays decides which days are worked, while weekStart only decides where a week cell begins.
HolidayEntry formats
Each holiday can be a plain string, a Date object, or an object with a date and a label for the hover tooltip.
Since 3.20.0 holiday strings are read with inputDateFormat, like task dates, falling back to ISO YYYY-MM-DD. In a DD-MM-YYYY chart '03-04-2026' is now 3 April (before, the browser read it as 4 March), and '25-12-2026' is no longer dropped. On 3.19 and earlier, pass holidays as ISO strings or Date objects whatever your inputDateFormat is.
const gantt = new ApexGantt(el, {
series: tasks,
calendar: {
workingWeekdays: [1, 2, 3, 4, 5],
holidays: [
'2024-01-01', // plain string
new Date('2024-07-04'), // Date object
{ date: '2024-12-25', label: 'Christmas' }, // labeled, appears in tooltip
],
},
})
Non-working stripes
When showNonWorkingStripes: true (the default), weekends and holidays are shaded with a tinted band in the timeline. Since 3.20.0 the bands are drawn above the row backgrounds and below the bars; before 3.20.0 an opaque row background could hide them. Disable them when you want the calendar to drive duration math only without the visual overlay:
calendar: {
workingWeekdays: [1, 2, 3, 4, 5],
showNonWorkingStripes: false, // no visual bands, calendar still drives duration
},
Holiday hover tooltip
Supply a holidayTooltip function to control the HTML rendered when a user hovers a holiday stripe. The function receives { date: Date, label?: string }. The tooltip shows on hover since 3.20.0; on earlier versions the stripes sat under the rows and the tooltip did not appear.
calendar: {
workingWeekdays: [1, 2, 3, 4, 5],
holidays: [
{ date: '2024-12-25', label: 'Christmas Day' },
{ date: '2024-01-01', label: "New Year's Day" },
],
holidayTooltip: ({ date, label }) => `
<div style="padding: 6px 10px; font-size: 13px;">
<strong>${label ?? 'Non-working day'}</strong><br/>
${date.toLocaleDateString('en-US', { month: 'long', day: 'numeric' })}
</div>
`,
},
Drag snap mode
When a task bar is dragged or resized to land on a non-working day, dragSnapMode determines where it snaps:
'next'(default): snaps forward to the next working day. Drag preserves the task's working-day duration.'previous': snaps backward to the previous working day.'allow': permits non-working start/end dates, which is useful for tasks that can span weekends.
calendar: {
workingWeekdays: [1, 2, 3, 4, 5],
dragSnapMode: 'next', // default: drag always lands on a working day
},
What the calendar changes
- The Duration column counts working days, with the suffix
wd. - Since 3.20.0, the BaselineVariance column counts working days too (
wd). - The critical path measures durations and dependency
lagin working days. - A summary row's progress is weighted by its children's working-day durations.
- Dragging or resizing a bar onto a non-working day snaps it, as set by
dragSnapModeabove. - The inline Duration editor works in the same working days as the column (since 3.20.0).
- With day snapping, a keyboard move or resize skips non-working days in the direction of travel, unless
dragSnapModeis'allow'. - Sorting, filtering and grouping on Duration use the working-day count the column shows (since 3.20.0).
Six-day working week
If your team works Saturday but not Sunday:
calendar: {
workingWeekdays: [1, 2, 3, 4, 5, 6], // Mon-Sat
},
A workingWeekdays list that names no weekday from 0 to 6 ([], [7]) logs a warning and falls back to Monday to Friday since 3.20.0. Before, it made every day non-working.
Updating the calendar at runtime
Since 3.20.0, call update() to change the calendar after mount, for example to switch between fiscal calendars. update() rebuilds the working calendar whenever you pass calendar or inputDateFormat, and a theme change keeps the calendar. Before 3.20.0 update() kept the calendar the chart was created with (and a theme change dropped it), so recreate the chart to change it on those versions.
gantt.update({
calendar: {
workingWeekdays: [0, 1, 2, 3, 4], // switch to Sun-Thu (Middle East pattern)
holidays: newHolidayList,
},
})
React example
import { ApexGanttChart } from 'react-apexgantt'
import type { GanttUserOptions } from 'react-apexgantt'
const options: Omit<GanttUserOptions, 'series'> = {
calendar: {
workingWeekdays: [1, 2, 3, 4, 5],
holidays: [
'2024-01-01',
'2024-07-04',
{ date: '2024-12-25', label: 'Christmas Day' },
],
showNonWorkingStripes: true,
dragSnapMode: 'next',
holidayTooltip: ({ label, date }) =>
`<div style="padding:6px 10px"><strong>${label ?? date.toDateString()}</strong></div>`,
},
}
export default function CalendarGantt() {
return <ApexGanttChart tasks={tasks} options={options} height="500px" />
}
Vue example
<template>
<ApexGanttChart :tasks="tasks" :options="ganttOptions" height="500px" />
</template>
<script setup lang="ts">
import { ApexGanttChart } from 'vue-apexgantt'
import type { GanttUserOptions } from 'vue-apexgantt'
import { tasks } from './tasks'
const ganttOptions: Partial<GanttUserOptions> = {
calendar: {
workingWeekdays: [1, 2, 3, 4, 5],
holidays: [
'2024-01-01',
{ date: '2024-12-25', label: 'Christmas Day' },
],
showNonWorkingStripes: true,
dragSnapMode: 'next',
},
}
</script>