Timeline Views and Zoom
ApexGantt renders tasks on a scrollable horizontal timeline where the zoom level determines how many pixels represent one calendar day. That single number, pixelsPerDay, controls how much time fits in the visible area: a high value zooms in to show a few days in detail, a low value zooms out to show months or years at a glance. The header tiers (year, quarter, month, week, day, halfday, hour, minute) are picked automatically from the current density.
Timeline density with pixelsPerDay
pixelsPerDay is a continuous number: any value between roughly 0.25 and 7680 is accepted (values outside are clamped). Rather than a fixed set of named modes, you set the exact density you want and the header re-tiers itself to match.
These calibrated reference points map the familiar named scales to a pixelsPerDay value, so you can reach for a preset density or pick anything in between:
| Named scale | pixelsPerDay | Approximate time on screen | Typical use |
|---|---|---|---|
| Year | 0.5 | Multi-year | Executive overviews |
| Quarter | 1.6 | 1-2 years | Roadmaps, long-term planning |
| Month | 4.9 | 3-6 months | Most projects |
| Week | 25.7 | 1-3 months | Sprint planning, short projects |
| Day | 80 | 1-2 weeks | Detailed scheduling, hour-level work |
Setting the zoom at construction
Pass pixelsPerDay in the options object. If omitted, the chart auto-fits the data span (see below).
import ApexGantt from 'apexgantt'
ApexGantt.setLicense('YOUR-LICENSE-KEY')
const gantt = new ApexGantt(document.getElementById('gantt'), {
inputDateFormat: 'YYYY-MM-DD', // the dates on this page are ISO
series: [
{ id: '1', name: 'Discovery', startTime: '2024-04-01', endTime: '2024-04-14' },
{ id: '2', name: 'Design', startTime: '2024-04-15', endTime: '2024-04-30' },
{ id: '3', name: 'Development', startTime: '2024-05-01', endTime: '2024-06-15' },
{ id: '4', name: 'Testing', startTime: '2024-06-10', endTime: '2024-06-30' },
],
pixelsPerDay: 25.7, // week-density timeline
})
gantt.render()
Changing the zoom at runtime
Call update() with a new pixelsPerDay. The timeline re-renders immediately without discarding task data.
// Zoom out to a quarterly overview
gantt.update({ pixelsPerDay: 1.6 })
// Zoom back in to week-level detail
gantt.update({ pixelsPerDay: 25.7 })
// Any value in between works too, for a density between week and day
gantt.update({ pixelsPerDay: 40 })
update() accepts a partial options object, so you can change only pixelsPerDay while leaving all other configuration untouched.
Auto-fit zoom
When you omit pixelsPerDay, ApexGantt calculates a value that fits the full span of your task data into the available container width on first render. This is the default behavior. It is useful when you do not know the date range of the data ahead of time and want the chart to always start fully visible without horizontal scrolling.
Auto-fit runs once, on the first render that has a measurable container width. After that the zoom stays where it is: later update() calls keep the current zoom unless they pass pixelsPerDay, and the toolbar buttons, Ctrl+wheel and zoomIn() / zoomOut() change it from there.
Programmatic zoom buttons
zoomIn() and zoomOut() change the zoom by a continuous step, not by jumping between the named scales above. The header tiers adjust automatically.
zoomIn()multipliespixelsPerDayby 1.4, up to the maximum of about7680.zoomOut()divides it by 1.4, down to the minimum of about0.25.
Three to five steps cover the distance between two neighbouring named scales. Ctrl+wheel over the timeline zooms in finer steps around the pointer.
A minimal toolbar using plain buttons:
<div id="gantt" style="height: 400px;"></div>
<div class="zoom-controls">
<button id="zoom-in">Zoom in</button>
<button id="zoom-out">Zoom out</button>
</div>
import ApexGantt from 'apexgantt'
ApexGantt.setLicense('YOUR-LICENSE-KEY')
const gantt = new ApexGantt(document.getElementById('gantt'), {
inputDateFormat: 'YYYY-MM-DD',
series: [
{ id: '1', name: 'Planning', startTime: '2024-01-01', endTime: '2024-03-31' },
{ id: '2', name: 'Execution', startTime: '2024-04-01', endTime: '2024-09-30' },
{ id: '3', name: 'Review', startTime: '2024-10-01', endTime: '2024-12-31' },
],
pixelsPerDay: 4.9, // month-density timeline
})
gantt.render()
document.querySelector('#zoom-in').addEventListener('click', () => gantt.zoomIn())
document.querySelector('#zoom-out').addEventListener('click', () => gantt.zoomOut())
The built-in toolbar always includes zoom in and zoom out buttons, which call the same methods. toolbarItems adds your own controls next to them; it does not replace them.
React
In React, bind pixelsPerDay to component state. The react-apexgantt wrapper compares props on every render and calls update() internally only when one changes, passing only the props that changed (wrapper releases for apexgantt 3.20.0), so you do not need to manage the chart instance manually.
import { useState } from 'react'
import { ApexGanttChart } from 'react-apexgantt'
const tasks = [
{ id: '1', name: 'Planning', startTime: '2024-01-01', endTime: '2024-03-31' },
{ id: '2', name: 'Execution', startTime: '2024-04-01', endTime: '2024-09-30' },
{ id: '3', name: 'Review', startTime: '2024-10-01', endTime: '2024-12-31' },
]
// Preset densities, labelled for a simple selector.
const PRESETS = [
{ label: 'Day', value: 80 },
{ label: 'Week', value: 25.7 },
{ label: 'Month', value: 4.9 },
{ label: 'Quarter', value: 1.6 },
{ label: 'Year', value: 0.5 },
]
export default function GanttWithZoomSelector() {
const [pixelsPerDay, setPixelsPerDay] = useState(4.9)
return (
<div>
<div style={{ marginBottom: 12, display: 'flex', gap: 8 }}>
{PRESETS.map((p) => (
<button
key={p.label}
style={{ fontWeight: pixelsPerDay === p.value ? 'bold' : 'normal' }}
onClick={() => setPixelsPerDay(p.value)}
>
{p.label}
</button>
))}
</div>
<ApexGanttChart
tasks={tasks}
options={{ inputDateFormat: 'YYYY-MM-DD' }}
pixelsPerDay={pixelsPerDay}
height="400px"
/>
</div>
)
}
To call zoomIn() and zoomOut() from buttons in React, use the imperative ref API. See React ApexGantt for the full ApexGanttHandle reference.
import { useRef } from 'react'
import { ApexGanttChart } from 'react-apexgantt'
import type { ApexGanttHandle } from 'react-apexgantt'
export default function GanttWithZoom() {
const ganttRef = useRef<ApexGanttHandle>(null)
return (
<div>
<div style={{ marginBottom: 12, display: 'flex', gap: 8 }}>
<button onClick={() => ganttRef.current?.zoomIn()}>Zoom in</button>
<button onClick={() => ganttRef.current?.zoomOut()}>Zoom out</button>
</div>
<ApexGanttChart ref={ganttRef} tasks={tasks} height="400px" />
</div>
)
}
Vue
In Vue, bind pixels-per-day to a ref. The vue-apexgantt wrapper handles the update() call when the prop changes.
<template>
<div>
<div style="margin-bottom: 12px; display: flex; gap: 8px;">
<button
v-for="p in presets"
:key="p.label"
:style="{ fontWeight: pixelsPerDay === p.value ? 'bold' : 'normal' }"
@click="pixelsPerDay = p.value"
>
{{ p.label }}
</button>
</div>
<ApexGanttChart
:tasks="tasks"
:options="{ inputDateFormat: 'YYYY-MM-DD' }"
:pixels-per-day="pixelsPerDay"
height="400px"
/>
</div>
</template>
<script setup lang="ts">
import { ref } from 'vue'
import { ApexGanttChart } from 'vue-apexgantt'
const presets = [
{ label: 'Day', value: 80 },
{ label: 'Week', value: 25.7 },
{ label: 'Month', value: 4.9 },
{ label: 'Quarter', value: 1.6 },
{ label: 'Year', value: 0.5 },
]
const pixelsPerDay = ref(4.9)
const tasks = [
{ id: '1', name: 'Planning', startTime: '2024-01-01', endTime: '2024-03-31' },
{ id: '2', name: 'Execution', startTime: '2024-04-01', endTime: '2024-09-30' },
{ id: '3', name: 'Review', startTime: '2024-10-01', endTime: '2024-12-31' },
]
</script>
To call zoomIn() and zoomOut() from Vue, use a template ref. See Vue ApexGantt for the full template ref method list.
Crosshair
The crosshair is a vertical line that tracks the cursor across the timeline. It shows a date label at the top of the timeline as the user moves the mouse, making it easy to read off exact dates on dense charts.
Enable it with enableCrosshair: true:
const gantt = new ApexGantt(document.getElementById('gantt'), {
series: tasks,
enableCrosshair: true,
})
gantt.render()
Crosshair color
Change the line color with crosshairColor. Any CSS color value is accepted.
const gantt = new ApexGantt(document.getElementById('gantt'), {
series: tasks,
enableCrosshair: true,
crosshairColor: '#F59E0B',
})
gantt.render()
Custom crosshair label
The crosshairLabelFormat callback lets you control the text shown in the date label. It receives the Date under the cursor and a tier string that describes which calendar resolution is currently active at the cursor position.
const gantt = new ApexGantt(document.getElementById('gantt'), {
series: tasks,
enableCrosshair: true,
crosshairLabelFormat: (date, tier) => {
// tier: 'minute' | 'hour' | 'halfday' | 'day' | 'week' | 'month' | 'quarter' | 'year'
if (tier === 'day' || tier === 'halfday') {
return date.toLocaleDateString('en-US', { month: 'short', day: 'numeric', year: 'numeric' })
}
if (tier === 'hour' || tier === 'minute') {
return date.toLocaleTimeString('en-US', { hour: '2-digit', minute: '2-digit' })
}
return date.toLocaleDateString('en-US', { month: 'short', year: 'numeric' })
},
})
gantt.render()
The tier value matches the current header resolution, so the label can stay contextually relevant as the user zooms in and out.
Since 3.22.0 locale.crosshairFormat sets the default label's patterns as strings, which works from JSON and Blazor: date on day-and-coarser tiers (default 'ddd MM/DD/YYYY') and time on halfday, hour and minute tiers (default 'MM/DD HH:mm'). The default label names the weekday in the date locale. crosshairLabelFormat wins over both.
locale: { crosshairFormat: { date: 'ddd D MMM YYYY', time: 'D MMM HH:mm' } }
Timeline header formats
Since 3.22.0 locale.timelineHeaderFormat replaces the labels of the timeline header, one tier and row at a time. The header has two rows, a coarse top row and a fine sub row, each drawn from one of eight tiers (minute, hour, halfday, day, week, month, quarter, year). Rows you leave unset keep the built-in labels, and the cells themselves never move; only the text changes.
const gantt = new ApexGantt(el, {
series: tasks,
calendar: { weekStart: 1, fiscalYearStartMonth: 4 },
locale: {
timelineHeaderFormat: {
year: { top: '[FY]{fy}', sub: '[FY]{fy}' },
quarter: { sub: [{ minWidth: 120, format: '[FY]{fy} [Q]{fq}' }, { format: '[Q]{fq}' }] },
month: { top: 'MMMM YYYY', sub: 'MMM' },
week: { sub: 'D MMM-{end:D MMM}' },
},
},
})
What a row can be set to
| Value | Example | Behaviour |
|---|---|---|
| pattern string | 'MMM D' | Used at every cell width. A label wider than its cell is cut with an ellipsis. An empty string blanks the row. |
| candidate array | [{ minWidth: 90, format: 'MMMM YYYY' }, { format: 'MMM' }] | Replaces the built-in list of labels for that row. The first candidate whose minWidth (default 0) fits the cell is used, else the narrowest; the order you write them in does not matter. Each format is a pattern string or a function. |
| function | (date, ctx) => `W${ctx.week}` | Called for every cell with the cell start as a Date and a context. |
The function's ctx carries tier, position ('top' or 'sub'), cellWidth, end, week, quarter, fiscalYear, fiscalQuarter, fiscal, locale and format(pattern, date?), which formats a date exactly as a pattern string is applied. ctx.fiscal (since 3.23.0) is true while a fiscal year is in use (see the rule), so one function can write both kinds of label:
year: { top: (date, ctx) => (ctx.fiscal ? `${ctx.fiscalYear}年度` : `${date.getFullYear()}年`) }
- Output is plain text: it is HTML-escaped before it renders.
- A function that throws, or returns anything but a string or a number, leaves that cell with the built-in label, and the chart logs one warning for that row.
- A function runs for every cell on every render and zoom step, so keep it pure and cheap. In React, define it outside the component or memoize the options, or each render sends an update.
update({ locale: { timelineHeaderFormat } })replaces the whole format object and keeps thedateLocalealready set.
Rows for fiscal years only
Since 3.23.0 a format can hold a fiscal block: rows in the same shape as the rest of the format, used only while a fiscal year is in use. With no fiscal year in use the block is ignored. It is plain data like the rest of the format, so a JSON locale pack can carry it, and one format then reads calendar years or fiscal years depending on calendar.fiscalYearStartMonth alone:
locale: {
timelineHeaderFormat: {
year: { top: 'YYYY年', sub: 'YYYY年' }, // calendar years
quarter: { sub: [{ minWidth: 96, format: '第{fq}四半期' }, { format: '{fq}[Q]' }] },
fiscal: { year: { top: '{fy}年度', sub: '{fy}年度' } }, // only while a fiscal year is in use
},
},
calendar: { fiscalYearStartMonth: 4 }, // remove it and the year row reads 2026年 again
The quarter row needs no fiscal entry here: {fq} is already the fiscal quarter while a fiscal year is in use and the calendar quarter otherwise. This is how the Japanese pack switches between 2026年 and 2026年度 (see Japanese fiscal years).
While a fiscal year is in use, each tier and row takes the first of these that sets it:
locale.timelineHeaderFormat.fiscallocale.timelineHeaderFormat- the pack's
timelineHeaderFormat.fiscal - the pack's
timelineHeaderFormat - the built-in fiscal labels (
FY2026,#1 Apr-Jun)
So a row you set yourself wins over every row of the pack, fiscal or not. With no fiscal year in use, the order is the one without the fiscal blocks: your row, then the pack's, then the built-in label.
Code that walks a format object (Object.keys, Object.values) meets the fiscal key beside the eight tiers; skip it, and in TypeScript type the tier rows as TimelineHeaderTierRows.
Pattern tokens
Patterns are dayjs format strings run with the date locale applied. Since 3.22.0 every date ApexGantt formats (header patterns, inputDateFormat, displayDateFormat, crosshairFormat) takes these tokens on top of the core ones (YYYY, M, MMM, D, ddd, H, h, mm, A and the rest). Examples are for Sunday 4 January 2026, 15:00, in English:
| Token | Meaning | Example |
|---|---|---|
Q | Calendar quarter | 1 |
Do | Day of month, ordinal | 4th |
k, kk | Hour, 1 to 24 | 15 |
w, ww, wo | Week of year, following the week start | 2, 02, 2nd |
W, WW | ISO week (Monday weeks) | 1, 01 |
gggg, GGGG | Week year, ISO week year | 2026 |
L, LL, LLL, LLLL (and l, ll, lll, llll) | The date locale's own formats | 01/04/2026, January 4, 2026 |
X, x | Unix seconds, milliseconds |
Wrap literal Latin text in square brackets ('[Wk] w' gives Wk 2); CJK text such as 年, 月 and 週 needs no brackets. YYYY and Q stay calendar-based. Three placeholders are filled in before formatting:
| Placeholder | Gives |
|---|---|
{end:PATTERN} | The cell's last instant (the last day of the week, month or quarter), formatted with PATTERN |
{fy} | Fiscal year, named by the calendar year it starts in (see calendar.fiscalYearStartMonth) |
{fq} | Fiscal quarter, 1 to 4 |
With no fiscal year in use, {fy} is the calendar year and {fq} the calendar quarter. Any other {...} text prints as written. A Latin letter right after a placeholder still needs brackets: '{fq}[Q]' reads 1Q, while '{fq}Q' reads 11, because the bare Q is the quarter token.
Upgrading inputDateFormat: because the parser reads the new tokens too, a format that held Q, Do, k, w, W, X, x or L as literal text now prints a value there. Wrap such text in [ ]; the chart logs one warning when it finds one outside brackets. The default 'MM-DD-YYYY' is unaffected.
Which rows show at which zoom
Zoom (pixelsPerDay) | Top row | Sub row |
|---|---|---|
| under about 0.9 | none | year.sub |
| about 0.9 to 2.6 | year.top | quarter.sub |
| about 2.6 to 11.4 | year.top | month.sub |
| about 11.4 to 42 (week zoom is 25.7) | month.top | week.sub |
| 42 to 400 (day zoom is 80) | week.top | day.sub |
| 400 to 1920 | day.top | halfday.sub |
| 1920 to 7680 | day.top | hour.sub |
| 7680 and over | hour.top | minute.sub |
So at week zoom the weeks are the sub row, under months, and week.top is not on screen. Set every row your users can zoom to. minute.top, halfday.top and quarter.top never render.
Week start and fiscal year
Since 3.22.0 two calendar settings shape the timeline header:
calendar.weekStart(0Sunday to6Saturday): week cells start on that day, and week numbers (wand the built-inWklabels) follow it. Unset, a locale pack'sweekStartapplies, then thelocale.dateLocale's own week start, else Sunday.calendar.fiscalYearStartMonth(1January to12December, unset by default): quarter and year cells start on fiscal boundaries, and the built-in labels read as fiscal periods. With4, the year from April 2026 to March 2027 readsFY2026and its first quarter#1 Apr-Jun. Month, week and day cells are unaffected.
const gantt = new ApexGantt(el, {
series: tasks,
calendar: { weekStart: 1, fiscalYearStartMonth: 4 }, // Monday weeks, April fiscal year
})
When a fiscal year is in use. Since 3.23.0 one rule decides it: calendar.fiscalYearStartMonth, or a locale pack's fiscalYearStartMonth, is set to a valid month, 1 included. The same rule switches the built-in fiscal labels, the fiscal rows of a header format and ctx.fiscal, and changing the setting through update() switches all three. Left unset, the header shows calendar years and quarters (2026, #1 Jan-Mar 2026).
fiscalYearStartMonth | Built-in year | Built-in quarter | Japanese pack year | Japanese pack quarter |
|---|---|---|---|---|
| not set | 2026 (January to December) | #1 Jan-Mar | 2026年 | 第1四半期 (January to March) |
4 | FY2026 (April 2026 to March 2027) | #1 Apr-Jun | 2026年度 | 第1四半期 (April to June) |
1 | FY2026 (January to December) | #1 Jan-Mar | 2026年度 | 第1四半期 (January to March) |
1 reads as a fiscal year since 3.23.0. In 3.22.0 the built-in labels switched to fiscal periods only when the start month was not January, so an explicit fiscalYearStartMonth: 1 showed 2026. It now shows FY2026 and #1 Jan-Mar on the same calendar-aligned cells. Leave the setting out for calendar labels. Because 1 now turns fiscal-year mode on, no calendar value turns off a fiscal year that a locale pack sets: use a pack without fiscalYearStartMonth.
A calendar that holds only these two settings shapes the header and leaves every day a working day; add any other calendar setting (such as workingWeekdays or holidays) to turn the working calendar on. A value out of range logs a warning and is ignored: an invalid weekStart leaves the week start to the pack or date locale, and an invalid fiscalYearStartMonth leaves calendar years (or the pack's fiscal year, if it sets one).
Week cells now follow the date locale. Since 3.22.0 a dateLocale whose week starts on Monday (de, fr, ru, en-gb and most European locales) or Saturday (ar) moves the week cells to that day, and the week number on each cell matches it. Before, cells always ran Sunday to Saturday while the numbers followed the locale. Set calendar.weekStart: 0 to keep Sunday weeks. Dependency arrows and the crosshair line up with the cells under any week start or fiscal year.
Snap behavior
When a user drags or resizes a task bar, ApexGantt snaps the task boundaries to the nearest unit. This prevents tasks from landing on arbitrary timestamps and keeps the schedule clean.
snapUnit sets the unit of the grid: 'day', 'hour', or 'minute'.
snapValue sets how many of those units form one snap interval. The default is 1, meaning every day (or hour, or minute). Set it higher to enforce coarser alignment.
const gantt = new ApexGantt(document.getElementById('gantt'), {
series: tasks,
// Snap to the nearest half-day boundary
snapUnit: 'hour',
snapValue: 12,
})
gantt.render()
Common patterns:
// Daily snap (default)
{ snapUnit: 'day', snapValue: 1 }
// Weekly snap: tasks align to week boundaries
{ snapUnit: 'day', snapValue: 7 }
// Two-hour snap for sub-day scheduling
{ snapUnit: 'hour', snapValue: 2 }
// 15-minute snap for fine scheduling
{ snapUnit: 'minute', snapValue: 15 }
Snapping applies to dragging and resizing bars, drawing new tasks and inline date edits. snapUnit and snapValue also set the units of the Duration column. With dragging, resizing and editing all off, they only affect that column. Since 3.20.0 a 'day' snap moves bars by calendar days (mouse and keyboard alike), so a one-day step across a daylight-saving change lands on the next date; hour and minute snaps move by elapsed time.
Scrolling to a task
On a long timeline a task's bar can sit well outside the visible window. Three mechanisms bring it back into view.
enableScrollButtons (default false since 3.15.0) shows a chevron at the edge of any row whose bar is scrolled out of the visible window; clicking it jumps that bar into view. Set it to true to opt in.
scrollToTaskOnRowClick (default false) reveals a task's bar when you click its row in the task list, using the same nearest-edge alignment. It composes with enableSelection, so a single click both selects the row and scrolls its bar into view. Clicks on the selection checkbox, the toggle chevron, and active inline-edit inputs are ignored, so those controls keep working.
new ApexGantt(el, { series: tasks, scrollToTaskOnRowClick: true })
scrollToTask(id) does the same programmatically, using nearest-edge alignment (the minimum scroll that reveals the bar) both horizontally and vertically. It works even when the target row is virtualized out of the DOM and is unaffected by the enableScrollButtons default.
Since 3.20.0 it first opens any collapsed parents (and a collapsed group) of the task; pass { expand: false } to leave them closed. It returns false for an unknown id, a task hidden by the active filter, or expand: false with a collapsed parent. Before 3.20.0 it took no options, returned true only when it scrolled, and returned false for a task under a collapsed parent.
const found = gantt.scrollToTask('task-42')
gantt.scrollToTask('task-42', { expand: false }) // 3.20.0+
Call it to locate a task from search results, an external list, or your own toolbar button.
Related
- Options reference for all timeline and toolbar options
- Methods reference for
zoomIn,zoomOut, andupdate - Localization and RTL for locale packs,
dateLocaleand translated header labels - React ApexGantt for the
pixelsPerDayprop andApexGanttHandle - Vue ApexGantt for the
pixels-per-dayprop and template ref methods