Task Labels in EJ2 JavaScript Gantt Chart Control

27 May 202612 minutes to read

Task labels in the EJ2 JavaScript Gantt Chart control display key task information directly on or near taskbars, enhancing project visualization without requiring task interaction. Configured via the labelSettings property, labels show details like task names, IDs, or progress, streamlining workflows for resource management and status tracking. Labels support three positions: left labels outside the taskbar for identifiers like TaskName, right labels after the taskbar for metrics like Progress, and task labels overlaid on taskbars for prominent data like task titles. Left and right labels remain visible regardless of taskbar width, while task labels may clip for short tasks. Labels improve readability and provide immediate context, reducing the need for hovers or dialogs in large projects.

Configure task labels

Task labels are configured using the labelSettings property, mapping fields from the data source defined in taskFields (e.g., id to TaskID, name to TaskName). The control supports three label positions with specific use cases:

  • leftLabel: Displays content like task names or resource assignments to the left of taskbars, ideal for identifiers.
  • rightLabel: Shows metrics like progress percentages or durations to the right, suitable for completion data.
  • taskLabel: Overlays content like task titles or progress on taskbars, prominent but limited by taskbar width.

Use template literals for formatted labels, such as ${Progress}% for progress percentages. Ensure valid taskFields mappings to reference fields accurately.

The following example configures labels for task names, IDs, and progress:

  const taskFields = {
    id: 'TaskID',
    name: 'TaskName',
    startDate: 'StartDate',
    duration: 'Duration',
    progress: 'Progress',
    parentID: 'ParentID'
  };
  const labelSettings = {
    leftLabel: 'Task Id: ${TaskID}',
    rightLabel: 'Task Name: ${TaskName}',
    taskLabel: '${Progress}%'
  };

This code displays task names on the left, task IDs on the right, and formatted progress percentages on taskbars, ensuring clear visualization.

Customize labels with templates

For advanced scenarios, you can create custom label templates using functions for advanced customization that provide complete control over label content and formatting.

var ganttChart = new ej.gantt.Gantt({
    dataSource: GanttData,
    height: '450px',
    projectStartDate: new Date('03/31/2019'),
    projectEndDate: new Date('04/18/2019'),
    taskFields: {
        id: 'TaskID',
        name: 'TaskName',
        startDate: 'StartDate',
        duration: 'Duration',
        progress: 'Progress',
        parentID: 'ParentID'
    },
    labelSettings: {
        leftLabel: 'Task ID: ${TaskID}',
        rightLabel: 'Task Name: ${taskData.TaskName}',
        taskLabel: '${Progress}%'
    }
});

ganttChart.appendTo('#Gantt');
<!DOCTYPE html>
<html lang="en">

<head>
    <title>EJ2 Gantt</title>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <meta name="description" content="Typescript Gantt Controls">
    <meta name="author" content="Syncfusion">
    <link href="index.css" rel="stylesheet">
    <link href="https://cdn.syncfusion.com/ej2/34.1.29/tailwind3.css" rel="stylesheet" type="text/css">
    <script src="https://cdn.syncfusion.com/ej2/34.1.29/dist/ej2.min.js" type="text/javascript"></script>
    <script src="es5-datasource.js" type="text/javascript"></script>
</head>

<body>
    <div id="container">
        <div id="Gantt"></div>
    </div>
    <script>
        var ele = document.getElementById('container');
        if (ele) {
            ele.style.visibility = "visible";
        }   
    </script>
    <script src="index.js" type="text/javascript"></script>
</body>

</html>

This code creates a left label with priority-based icons (e.g., red for high priority) and a right label with a progress bar, improving visual feedback. For responsive designs, ensure templates adapt to narrow screens, as task labels may be clipped on short taskbars.

Conditional label display with icons:

Create templates that show different content based on task properties:

function leftLabelTemplate(props) {
    var priorityIcon = '';

    if (props.Priority === 'High') {
        priorityIcon = '<span class="priority-high">🔴</span>';
    } else if (props.Priority === 'Medium') {
        priorityIcon = '<span class="priority-medium">🟡</span>';
    } else if (props.Priority === 'Low') {
        priorityIcon = '<span class="priority-low">🟢</span>';
    }

    return (
        '<div class="custom-left-label">' +
            priorityIcon +
            '<span>' + props.TaskName + '</span>' +
        '</div>'
    );
}

function rightLabelTemplate(props) {
    var progress = props.Progress || 0;
    var duration = props.Duration || 0;

    return (
        '<div class="custom-right-label">' +
            '<div class="progress-container">' +
                '<span class="progress-text">' + progress + '%</span>' +
                '<div class="progress-bar" style="width:' + progress + '%"></div>' +
            '</div>' +
            '<span class="duration-text">' + duration + ' days</span>' +
        '</div>'
    );
}

var ganttChart = new ej.gantt.Gantt({
    dataSource: GanttData,
    height: '450px',
    taskFields: {
        id: 'TaskID',
        name: 'TaskName',
        startDate: 'StartDate',
        duration: 'Duration',
        progress: 'Progress',
        parentID: 'ParentID'
    },
    labelSettings: {
        leftLabel: leftLabelTemplate,
        rightLabel: rightLabelTemplate
    }
});

ganttChart.appendTo('#Gantt');

Rich content labels with multiple data points:

Display complex information with formatted content and calculations:

function getProgressClass(progress) {
    if (progress >= 80) {
        return 'high';
    }
    if (progress >= 40) {
        return 'medium';
    }
    return 'low';
}

function formatDate(date) {
    if (!date) {
        return '';
    }
    return date.toLocaleDateString('en-US', {
        month: 'short',
        day: '2-digit'
    });
}

function taskLabelTemplate(props) {
    var taskName = props.TaskName || (props.ganttProperties && props.ganttProperties.taskName);
    var startDate = props.StartDate || (props.ganttProperties && props.ganttProperties.startDate);
    var endDate = props.EndDate || (props.ganttProperties && props.ganttProperties.endDate);
    var progress = (props.Progress != null)
        ? props.Progress
        : (props.ganttProperties && props.ganttProperties.progress) || 0;
    var resources = props.Resources || (props.ganttProperties && props.ganttProperties.resourceInfo);

    var resourceHtml = '';
    if (resources && resources.length) {
        resourceHtml =
            '<span class="resource-count">👥 ' + resources.length + '</span>';
    }

    return (
        '<div class="rich-task-label">' +
            '<div class="task-info">' +
                '<strong>' + taskName + '</strong>' +
                '<small>' +
                    formatDate(startDate) + ' – ' + formatDate(endDate) +
                '</small>' +
            '</div>' +
            '<div class="task-meta">' +
                resourceHtml +
                '<span class="progress-badge progress-' + getProgressClass(progress) + '">' +
                    progress + '%' +
                '</span>' +
            '</div>' +
        '</div>'
    );
}

var ganttChart = new ej.gantt.Gantt({
    dataSource: GanttData,
    height: '450px',
    taskFields: {
        id: 'TaskID',
        name: 'TaskName',
        startDate: 'StartDate',
        duration: 'Duration',
        progress: 'Progress',
        parentID: 'ParentID'
    },
    labelSettings: {
        taskLabel: taskLabelTemplate
    }
});

ganttChart.appendTo('#Gantt');

See also