Setting up the Scale

You can configure the following aspects of the time scale (X-Axis):

  1. Unit
  2. Range
  3. Step
  4. Height
  5. Format
  6. Style
  7. Second scale

You can also add a custom scale.

Time units

To set the unit of the scale, use the scale_unit property:

Setting the "week" unit for the scale

gantt.config.scale_unit = "week"; gantt.config.date_scale = "Week #%W";

Related sample:  Month view


Default range settings

If you don't specify the date range explicitly, Gantt uses the dates of the loaded tasks and adds offsets before the first and after the last task in the scale. The offset is defined by the settings of the time scale. Depending on the scale_offset_minimal value, it will be either the time unit defined in via the scale_unit option or the smallest of the time scale units.

You can get the displayed date range programmatically using the getState method.

var state = gantt.getState();
// -> Mon Jan 01 2018 00:00:00
// -> Tue Jan 01 2019 00:00:00

The scale range is recalculated on gantt rendering. If the user moves a task outside the displayed time range, the task row will be displayed, but the bar element won't be visible until complete repainting is done.

In order to adjust scale automatically, use the fit_tasks config.

gantt.config.fit_tasks = true; 

Related sample:  Auto resize scale

Setting date range explicitly

Alternatively, you can set the date range explicitly by using the start_date and end_date configuration options:

gantt.config.start_date = new Date(2018, 02, 31);
gantt.config.end_date = new Date(2018, 03, 09);

They can also be specified in the gantt initialization call:

gantt.init("gantt_here", new Date(2018, 02, 31), new Date(2018, 03, 09));

Related sample:  Define date range

The tasks that don't fit into the specified interval won't be displayed in the Gantt chart, unless they are marked as unscheduled.

Related sample:  Show Unscheduled Tasks


If both the start_date and end_date options are specified and you create a task that is outside the range, the task will disappear from the chart.

In this case we can extend the range:

gantt.attachEvent("onLightboxSave", function(id, task, is_new){
 var taskStart = task.start_date;
 var taskEnd = task.end_date;
 var scaleStart = gantt.config.start_date;
 var scaleEnd = gantt.config.end_date;
 // if the task is out of the range
 if(scaleStart > taskEnd || scaleEnd < taskStart ){
  // update timescale range
  gantt.config.end_date=new Date(Math.max(taskEnd.valueOf(), scaleEnd.valueOf()));
  gantt.config.start_date=new Date(Math.min(taskStart.valueOf(),scaleStart.valueOf()));
 return true;

Or add validation to the lightbox control:

gantt.attachEvent("onLightboxSave", function(id, task, is_new){
    var taskStart = task.start_date;
    var taskEnd = task.end_date;
    var scaleStart = gantt.config.start_date;
    var scaleEnd = gantt.config.end_date;
    // check if the task is out of the range
    if(scaleStart > taskEnd || scaleEnd < taskStart ){
            text:"Warning! The task is outside the date range!",
          return false;
    return true;

Changing the displayed range dynamically

There are several ways of how you can change the displayed range on the fly:

  • you can control the time range with the help of the start_date / end_date configs, but dynamically adjust them to display loaded tasks.

You can do it by recalculating the scale range via updating the start_date / end_date configs each time gantt is repainted:

gantt.attachEvent("onBeforeGanttRender", function(){
   var range = gantt.getSubtaskDates();
   var scaleUnit = gantt.getState().scale_unit;
   if(range.start_date && range.end_date){
     gantt.config.start_date = gantt.calculateEndDate(range.start_date, -4, scaleUnit);
     gantt.config.end_date = gantt.calculateEndDate(range.end_date, 5, scaleUnit);
  • to 'force' the scale re-render each time a task doesn't fit into the existing scale interval, set the fit_tasks property to true:
gantt.config.fit_tasks = true; 

In case both the start_date and end_date options are specified, you need to make use of one of the options described above for the fit_tasks property to work correctly.

  • it is also possible to automatically change the scale while dragging a task by specifying the necessary logic inside the handler of the onTaskDrag event:
gantt.attachEvent("onTaskDrag", function(id, mode, task, original){
 var state = gantt.getState();
 var minDate = state.min_date,
     maxDate = state.max_date;
 var Date(),state.scale_step,state.scale_unit)-new Date();
 var showDate,
  repaint = false;
  if(mode == "resize" || mode == "move"){
    if(Math.abs(task.start_date - minDate) < scaleStep){
      showDate = task.start_date;
      repaint = true;
    }else if(Math.abs(task.end_date - maxDate) < scaleStep){
      showDate = task.end_date;
      repaint = true;

Related sample:  Re-rendering Scale during Task Dragging

Time step

To set the step of the time scale, use the step property:

Setting the "day" step for the scale

gantt.config.scale_unit= "day";
gantt.config.step = 2;   

Related sample:  Year scale


To set the height of the scale, use the scale_height property:

gantt.config.scale_height = 54;  

Related sample:  Day hours

If you have several scales, they will share the specified height equally. For example, if scale_height is 60 pixels and you have 3 scales, each scale will have the height of 60 / 3 = 20 pixels.

Date format

See the Date Format Specification article to know about available format characters

To set the format of the scale, use:

  • the date_scale property, to set a simple format as a string:

    gantt.config.scale_unit = "day";
    gantt.config.date_scale = "%F, %d";  
    Related sample:  Multiple scales
  • the date_scale template, to set a complex format as a function that takes a date object as a parameter:

    gantt.config.scale_height = 44;
    gantt.attachEvent("onGanttReady", function(){
        var dateFormat ="%F %d");
        var dayNumber = function(date){
            return gantt.columnIndexByDate(date) + 1;
        gantt.templates.date_scale = function(date){              return "<strong>Day "+dayNumber(date)+"</strong><br/>"+dateFormat(date);     } });
    Related sample:  Custom scales


To style the scale, use the scale_cell_class template:

Setting a custom style for the scale

<style type="text/css">
   .weekend{ background: #BD7990!important; color:white !important;}
    gantt.templates.scale_cell_class = function(date){        if(date.getDay()==0||date.getDay()==6){
            return "weekend";        }    };    gantt.init("gantt_here");

Related sample:  Highlighting weekends

Note that while using work time calculations, you can use isWorkTime instead of hardcoded values:

gantt.config.work_time = true;
gantt.templates.scale_cell_class = function(date){
      return "weekend";

Read more on applying a custom style to the timeline area in the Highlighting Time Slots article.

Multiple scales

To add the second scale(s) underneath the default one, use the the subscales property:

Adding the second scale to the Gantt chart

gantt.config.subscales = [    {unit:"week", step:1, date:"Week #%W"}];gantt.config.scale_height = 54;

Related sample:  Multiple scales

Read more on second scales in a separate article - Adding the Second Scale(s).

Custom time units

dhtmlxGantt allows you to define custom time units and set a template for labels in the scale configuration.

To define a custom unit you need to define 2 functions in the Date object:

Date<unit>_start(Date date);
Date<unit>(Date date, Integer increment);
  • The first function shall return the start time unit for any given date (e.g. month_start for 14 Feb -> 1st Feb).
  • The second function increments the date by any given number of duration units (e.g. 'date minus 2 days')

Let's create a "fiscal_year" unit and assume that a fiscal year will end on the 31st of January. This is how the new unit can be specified:

var firstMonth = 1,
    firstDay = 1; = function(date){          var next = new Date(date);
   if(next.getMonth() < firstMonth || 
      (next.getMonth() === firstMonth && next.getDate() < firstDay)){
      next =, -1, "year"); 
  next =;
  return next;
}; = function(date, inc){       return, inc, "year");

And then use it in the code as in:

var dateToStr ="%Y");
function fiscalYearLabel(date){
    return dateToStr(;
gantt.config.subscales = [
  {unit:"year", step:1, date:"Calendar year %Y"},
  {unit:"fiscal_year", step:1, template:fiscalYearLabel}
Back to top