Timescale Range and Auto Fit

This topic explains how the scrollable date range of a GanttSheet timescale is determined and how to control it using autoFitMode and margin.

The timescale range defines how far users can scroll horizontally in the Gantt chart.

SpreadJS GanttSheet displays a horizontally scrollable timescale whose date boundaries are determined by the minDate and maxDate properties.

Overview

The scrollable range of the timescale is determined by:

timescale.minDate
timescale.maxDate
timescale.autoFitMode
timescale.margin

These properties control:

The base date boundaries of the timescale
Whether the range automatically follows the project schedule
How much additional space is reserved before and after the project duration

Auto Fit to Project

autoFitMode: "none"

The timescale date range remains unchanged after scheduling.

minDate and maxDate are not automatically modified.
The scrollable range may extend beyond the actual project duration.

This mode provides a stable, manually controlled timescale range.

SpreadJS GanttSheet with autoFitMode set to none preserves the configured timescale range beyond the scheduled project duration.

autoFitMode: "project"

When set to "project", the timescale automatically adjusts to match the project's scheduled duration.

timescale.minDate = project.start;
timescale.maxDate = project.finish;

This keeps the Gantt chart focused on the active task period.

SpreadJS GanttSheet with autoFitMode set to project adjusts the scrollable timescale boundaries to the scheduled task period.

When to Use Auto Fit?
If your project duration is much shorter than the default timescale range, the chart may contain large empty areas, making horizontal scrolling inefficient.
Enabling auto fit ensures that the scrollable range closely matches the actual project timeline.

Progress Line Reference Date

When autoFitMode is set to "project", the timescale range follows the project start and finish dates.

If a valid Progress Line is displayed, its active reference date is also included in the project auto-fit range. This ensures that the Progress Line reference anchor remains within the scrollable timescale range.

As a result:

If the Progress Line reference date is earlier than the project start date, it may become the left boundary of the scrollable range.
If the Progress Line reference date is later than the project finish date, it may become the right boundary of the scrollable range.
If the Progress Line reference date is within the project range, the project boundaries remain unchanged.

For more information about configuring Progress Lines, see Progress Line.

Timescale Margin

When the timescale range tightly matches the project boundaries, task labels rendered outside taskbars (such as leftText or rightText) may appear clipped.

SpreadJS GanttSheet shows a taskbar label clipped at the timescale boundary when no additional margin surrounds the project duration.

Use the margin property to reserve additional space before and after the project duration:

ganttSheet.project.timescale.margin = 5;

The margin is expressed in the smallest timescale tier unit (for example, days).

SpreadJS GanttSheet reserves additional timescale space through the margin property, preventing taskbar labels from being clipped at project boundaries.

This helps:

Prevent visual clipping at the boundaries
Improve overall readability

Switching autoFitMode

From "project" to "none"

minDate and maxDate retain their current values.
Automatic updates stop.
Subsequent schedules will not modify the timescale range.

From "none" to "project"

The next schedule automatically updates minDate and maxDate to match the project's scheduled duration.