Skip to main content

​
Legend Configuration

The legend provides a key to identify different series in your chart. Highcharts offers extensive options to customize legend appearance, position, and behavior.

​
Basic Legend Setup

By default, legends are enabled and positioned at the bottom of the chart: 
Highcharts.chart('container', {
  legend: {
    enabled: true,
    align: 'center',
    verticalAlign: 'bottom',
    layout: 'horizontal'
  },
  series: [
    { name: 'Series 1', data: [1, 2, 3] },
    { name: 'Series 2', data: [2, 3, 4] }
  ]
});

​
Legend Positioning

​
Alignment and Layout

{
  legend: {
    align: 'center',
    verticalAlign: 'bottom',
    layout: 'horizontal'
  }
}

​
Fine-tuning Position

Use x and y offsets for precise positioning: 
{
  legend: {
    align: 'right',
    verticalAlign: 'middle',
    layout: 'vertical',
    x: -10,  // 10px from right edge
    y: 0     // Centered vertically
  }
}

​
Legend Styling

​
Basic Appearance

From the Legend options (ts/Core/Legend/LegendOptions.ts:64-111): 
{
  legend: {
    backgroundColor: '#FFFFFF',
    borderColor: '#999999',
    borderWidth: 1,
    borderRadius: 5,
    shadow: true,
    padding: 8
  }
}

​
Item Styling

Customize how legend items appear: 
{
  legend: {
    itemStyle: {
      color: '#333333',
      fontSize: '12px',
      fontWeight: 'normal',
      fontFamily: 'Arial, sans-serif'
    },
    itemHoverStyle: {
      color: '#000000',
      fontWeight: 'bold'
    },
    itemHiddenStyle: {
      color: '#CCCCCC'
    },
    itemDistance: 20  // Space between items
  }
}

​
Symbol Customization

{
  legend: {
    symbolHeight: 12,
    symbolWidth: 12,
    symbolRadius: 6,
    symbolPadding: 5,
    squareSymbol: true  // Use square symbols instead of circles
  }
}

​
Legend Behavior

​
Interactive Features

1

Clickable Items

By default, clicking legend items toggles series visibility:
{
  legend: {
    enabled: true
    // Items are clickable by default
  },
  plotOptions: {
    series: {
      events: {
        legendItemClick: function (e) {
          // Custom behavior when legend item is clicked
          console.log('Clicked:', this.name);
          // Return false to prevent default toggle
          // return false;
        }
      }
    }
  }
}
2

Checkboxes

Add checkboxes to legend items:
{
  series: [{
    name: 'Series 1',
    showCheckbox: true,
    selected: true,
    data: [1, 2, 3]
  }]
}
3

Navigation for Long Legends

Enable pagination for legends with many items:
{
  legend: {
    maxHeight: 100,
    navigation: {
      enabled: true,
      animation: true,
      arrowSize: 12,
      activeColor: '#003399',
      inactiveColor: '#CCC',
      style: {
        fontSize: '12px'
      }
    }
  }
}

​
Series-Specific Legend Options

Control which series appear in the legend: 
{
  series: [
    {
      name: 'Visible in legend',
      showInLegend: true,
      data: [1, 2, 3]
    },
    {
      name: 'Hidden from legend',
      showInLegend: false,
      data: [2, 3, 4]
    },
    {
      name: 'Custom order',
      legendIndex: 0,  // Display first regardless of series order
      data: [3, 4, 5]
    }
  ]
}

​
Advanced Legend Features

​
Custom Legend Labels

{
  legend: {
    labelFormat: '{name} - Total: {options.total}'
  },
  series: [{
    name: 'Sales',
    total: 12500,
    data: [1, 2, 3]
  }]
}

​
Legend Title

Add a title to your legend: 
{
  legend: {
    title: {
      text: 'Data Series',
      style: {
        fontSize: '14px',
        fontWeight: 'bold',
        color: '#333'
      }
    }
  }
}

​
Reversed Legend

Reverse the order of legend items: 
{
  legend: {
    reversed: true
    // Items appear in reverse order
  }
}

​
Layout Options

​
Responsive Width

Control legend width based on container: 
{
  legend: {
    width: '60%',      // Percentage of chart width
    maxWidth: 400,     // Maximum width in pixels
    itemWidth: 150     // Fixed width per item
  }
}

​
Column Alignment

For vertical legends with multiple columns: 
{
  legend: {
    layout: 'vertical',
    alignColumns: true,  // Align items in columns
    itemWidth: 100
  }
}

​
Legend Events

Handle legend interactions: 
{
  legend: {
    events: {
      itemClick: function (event) {
        console.log('Legend item clicked:', event.target.name);
        // Prevent default behavior
        // return false;
      }
    }
  }
}

​
Theme Example

From the DarkUnica theme (ts/Extensions/Themes/DarkUnica.ts:137-153): 
{
  legend: {
    backgroundColor: 'rgba(0, 0, 0, 0.5)',
    itemStyle: {
      color: '#E0E0E3'
    },
    itemHoverStyle: {
      color: '#FFF'
    },
    itemHiddenStyle: {
      color: '#606063'
    },
    title: {
      style: {
        color: '#C0C0C0'
      }
    }
  }
}

​
HTML Legends

Create completely custom legends using HTML: 
{
  legend: {
    enabled: false  // Disable default legend
  },
  // Create custom HTML legend
  chart: {
    events: {
      load: function () {
        const chart = this;
        const legendDiv = document.getElementById('custom-legend');
        
        chart.series.forEach((series, i) => {
          const item = document.createElement('div');
          item.innerHTML = `
            <span style="color: ${series.color};">■</span>
            ${series.name}
          `;
          item.onclick = function () {
            series.setVisible(!series.visible);
          };
          legendDiv.appendChild(item);
        });
      }
    }
  }
}

​
Accessibility

Ensure legends are accessible: 
{
  legend: {
    accessibility: {
      enabled: true,
      keyboardNavigation: {
        enabled: true
      }
    }
  }
}

​
Best Practices

Legend Design Tips
  • Keep legend labels concise and descriptive
  • Use consistent symbol sizes for visual harmony
  • Position legends where they don’t obscure important data
  • Enable navigation for legends with many items
  • Consider using colors with sufficient contrast
Common Pitfalls
  • Too many legend items can overwhelm users
  • Floating legends may obscure data on smaller screens
  • Custom formatters can impact performance with many series
  • Ensure legend width doesn’t cause unwanted wrapping