Progressive Time Header Rendering

Progressive time header rendering helps the JavaScript Gantt chart load long timelines faster. Time headers appear as the user scrolls, so an application can show a large date range without displaying every header at once.

The feature is enabled by default in DayPilot Pro for JavaScript since version 2026.4.7080. No configuration change is required.

Adjust Scrolling Performance

Start with the defaults. If custom headers are slow to appear during scrolling, increase progressiveTimeHeaderRenderingMargin. The default margin is 200 pixels on each side of the visible area; this example uses 400:

const dp = new DayPilot.Gantt("dp", {
  startDate: "2027-01-01",
  days: 365,
  scale: "Day",
  timeHeaders: [
    {groupBy: "Month"},
    {groupBy: "Day", format: "d"}
  ],
  progressiveTimeHeaderRenderingMargin: 400
});
dp.init();

A larger margin can make scrolling smoother, but uses more memory and can increase loading time.

Two other settings let you tune the behavior:

• progressiveTimeHeaderRenderingCacheSize (default 200) controls how many additional headers are cached for scrolling back. Increase it for faster return to recently viewed dates, or lower it to reduce memory use.

• scrollDelayTimeHeaders (default 0 milliseconds) delays additional headers until scrolling pauses. A positive value can help with complex custom content, but newly visible header areas may remain blank during the delay.

Customize Time Headers

Use onBeforeTimeHeaderRender to set each header’s text, colors, or other properties. With progressive rendering enabled, the callback runs as headers are needed for display or export. It does not run for every header during initialization.

Keep the callback focused on the supplied header. If an existing application requires all header callbacks to run during initialization, disable progressiveTimeHeaderRendering:

dp.update({progressiveTimeHeaderRendering: false});

Custom DOM, React and Vue headers are supported. For interactive headers, store values that must survive scrolling or view updates in application state.

Keep Labels Visible

Use floatingTimeHeaders to keep labels readable when only part of a long header is visible. Custom controls keep their state as the label moves. scrollDelayFloats sets the delay before an existing floating label follows the scroll position.

Image Export

Export includes the headers for the requested date range, even if the user has not scrolled through it. Use onBeforeTimeHeaderExport to specify text and styling for the exported image.