# Timescale Range and Auto Fit

## Content

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.](https://cdn.mescius.io/document-site-files/images/b2223940-43c2-44cf-8eda-f5ab9acd84f0/image-20260324.9c8f8b.png?width=800)

## 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.](https://cdn.mescius.io/document-site-files/images/b2223940-43c2-44cf-8eda-f5ab9acd84f0/image-20260324.c1bd85.png?width=800)

### autoFitMode: "project"

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

```auto
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.](https://cdn.mescius.io/document-site-files/images/b2223940-43c2-44cf-8eda-f5ab9acd84f0/image-20260324.c2b635.png?width=800)

>type=info
> **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](/spreadjs/docs/features/ganttsheet/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.](https://cdn.mescius.io/document-site-files/images/b2223940-43c2-44cf-8eda-f5ab9acd84f0/image-20260324.3f2fe6.png?width=800)
Use the `margin` property to reserve additional space before and after the project duration:

```javascript
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.](https://cdn.mescius.io/document-site-files/images/b2223940-43c2-44cf-8eda-f5ab9acd84f0/image-20260324.aa24b4.png?width=800)
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.

## See Also

* [Scroll](/spreadjs/docs/features/ganttsheet/scroll)
* [Zoom](/spreadjs/docs/features/ganttsheet/zoom)
* [Progress Line](/spreadjs/docs/features/ganttsheet/progress-line)
* [GC.Spread.Sheets.GanttSheet.Timescale](/spreadjs/api/classes/GC.Spread.Sheets.GanttSheet.Timescale)
* [Configure the timescale range in the Designer](/spreadjs/docs/spreadjs-designer-component/spdesignerwork/ganttsheet-designer/view)