> ## Documentation Index
> Fetch the complete documentation index at: https://learn.nextedy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure the Time Scale

> This guide shows you how to set the time scale (zoom level) in Nextedy GANTT to match your project planning horizon, from hour-level detail to multi-year roadmaps.

export const LastReviewed = ({date}) => {
  if (!date) return null;
  const formatted = new Date(`${date}T00:00:00Z`).toLocaleDateString("en-US", {
    year: "numeric",
    month: "long",
    day: "numeric",
    timeZone: "UTC"
  });
  return <p className="mt-10 text-sm text-gray-400 dark:text-zinc-500 not-prose">
      Last reviewed on {formatted}
    </p>;
};

## Set the Default Scale via Widget Parameter

Navigate to **Widget Properties > Advanced > Scale** and select one of the available values:

| Scale Code | Label          | Best For                                  |
| :--------: | :------------- | :---------------------------------------- |
|     `H`    | Hours          | Hour-precision scheduling, daily standups |
|    `DD`    | 2-Day          | Short-term detailed planning              |
|     `D`    | Day            | Sprint-level task tracking                |
|     `W`    | Week (default) | Sprint and iteration planning             |
|     `M`    | Month          | Release planning, quarterly views         |
|     `Q`    | Quarter        | Program-level roadmaps                    |
|     `Y`    | Year           | Annual portfolio views                    |
|    `YY`    | 2-Year         | Multi-year executive roadmaps             |

The default scale is `W` (Week). Users see a weekly timeline header showing months over weeks when first loading the Gantt chart.

<Tip title="Scale saved per user">
  When a user changes the zoom level via the toolbar or menu, their preference is saved to browser local storage. On the next visit, the Gantt restores their last-used scale instead of the widget parameter default.
</Tip>

## Change the Scale at Runtime

Users can change the time scale without editing widget parameters using three methods:

1. **Toolbar zoom buttons** -- Click the zoom in/out buttons in the Gantt toolbar to step through available scales
2. **Hamburger menu** -- Click the ☰ icon in the first column header, then select **Set scale** and choose a level
3. **Right-click the timeline header** -- Right-click on the time scale area to open a context menu with scale options and a "Go to today" shortcut

<Tip title="Bypass the custom context menu">
  Press **Shift + right-click** on the timeline header to open the browser default context menu instead of the Gantt scale menu.
</Tip>

## Configure Scale Column Widths

You can adjust the width of timeline columns for each scale level through **Administration > Configuration Properties**:

```
nextedy.gantt.zoom.D.min_column_width=60
nextedy.gantt.zoom.W.min_column_width=30
nextedy.gantt.zoom.M.min_column_width=70
nextedy.gantt.zoom.Q.min_column_width=90
nextedy.gantt.zoom.Y.min_column_width=40
nextedy.gantt.zoom.YY.min_column_width=190
nextedy.gantt.zoom.DD.min_column_width=120
```

Increase the value to give more space to each time unit column; decrease it to fit more time periods on screen.

## Override Scale with Gantt Config Script

For advanced customization, use the **Gantt Config Script** to define custom scale rows with subscales. For example, to show a month header with week and day sub-rows:

```javascript theme={null}
gantt.config.scale_unit = "month";
gantt.config.step = 1;
gantt.config.date_scale = "%F, %Y";
gantt.config.min_column_width = 50;
gantt.config.scale_height = 90;

var weekScaleTemplate = function (date) {
    var dateToStr = gantt.date.date_to_str("%d %M");
    var endDate = gantt.date.add(gantt.date.add(date, 1, "week"), -1, "day");
    return dateToStr(date) + " - " + dateToStr(endDate);
};

var daysStyle = function(date){
    var dateToStr = gantt.date.date_to_str("%D");
    if (dateToStr(date) == "Sun" || dateToStr(date) == "Sat") return "weekend";
    return "";
};

gantt.config.subscales = [
    {unit: "week", step: 1, template: weekScaleTemplate},
    {unit: "day", step: 1, date: "%D", css: daysStyle}
];
```

<Tip title="Display calendar week numbers">
  To show calendar week numbers (CW format) on the time scale, use a custom `zoomConfig` script that formats the week label as `"CW" + weekNumber`. This is a common request for teams using ISO week numbering.
</Tip>

<Warning title="Date rounding follows scale">
  By default, dragging a task rounds its start and end dates to the nearest scale unit. For example, on month scale, dates round to full months. To disable this behavior, see [Disable Date Rounding on Drag](/gantt/guides/scheduling/date-rounding).
</Warning>

## Plans Gantt Scale

The Plans Gantt supports the same scale values as the Work Items Gantt. Plans typically use longer scales (`W`, `M`, `Y`) because plan bars span weeks or months. Set the scale in the Plans Gantt widget parameters the same way, under **Advanced > Scale**.

## Verification

You should now see the Gantt chart timeline header reflecting your configured scale. If you set `W`, the header shows months on the top row and weeks on the bottom row. Changing the zoom via toolbar buttons should cycle through the available levels.

## See also

* [Adjust Gantt Row Height](/gantt/guides/visualization/row-height)
* [Schedule in Hours Instead of Days](/gantt/guides/scheduling/hour-precision)
* [Disable Date Rounding on Drag](/gantt/guides/scheduling/date-rounding)
* [Configure the Toolbar and Menus](/gantt/guides/layout/toolbar-configuration)
* [Scroll to Today on Load](/gantt/guides/layout/scroll-to-today)

<LastReviewed date="2026-07-02" />