Task Labels in EJ2 TypeScript Gantt Chart Control

27 May 202612 minutes to read

Task labels in the EJ2 TypeScript 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.

import { Gantt } from '@syncfusion/ej2-gantt';
import { GanttData } from './datasource.ts';

let gantt: Gantt = new 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}%'
    }
});

gantt.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://cdnjs.cloudflare.com/ajax/libs/systemjs/0.19.38/system.js"></script>
    <script src="systemjs.config.js"></script>
</head>

<body>
  
    <div id='loader'>Loading....</div>
    <div id='container'>
        <div id='Gantt'></div>        
    </div>
</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:

import { Gantt } from '@syncfusion/ej2-gantt';
import { GanttData } from './datasource.ts';

function leftLabelTemplate(props: any): string {
    let priorityIcon: string = '';

    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: any): string {
    const progress: number = props.Progress || 0;
    const duration: number = 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>
    `;
}

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

gantt.appendTo('#Gantt');

Rich content labels with multiple data points:

Display complex information with formatted content and calculations:

import { Gantt } from '@syncfusion/ej2-gantt';
import { GanttData } from './datasource.ts';

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

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

function taskLabelTemplate(props: any): string {
    const taskName: string =
        props.TaskName || props.ganttProperties?.taskName;

    const startDate: Date =
        props.StartDate || props.ganttProperties?.startDate;

    const endDate: Date =
        props.EndDate || props.ganttProperties?.endDate;

    const progress: number =
        props.Progress ?? props.ganttProperties?.progress ?? 0;

    const resources: any[] =
        props.Resources || props.ganttProperties?.resourceInfo;

    const resourceHtml: string = (resources && resources.length)
        ? `<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>
    `;
}

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

gantt.appendTo('#Gantt');

See also