JavaScript Charts: Legend

A legend makes it easier to tell at a glance which series or series items correspond to which pieces of data. This section describes the legend options and layout behaviour.

Position

A legend is shown by default but can be hidden using the enabled config:

legend: {
    enabled: false
}

When enabled, it can be positioned to any side of a chart using the position config:

legend: {
    position: 'right' // 'bottom', 'left', 'top'
}

Example: Legend Position

Notice how when you click on one of the buttons in the example to change the position of the legend:

• the layout of the legend items also changes
• the layout of the chart changes as well, with series moving around and growing/shrinking slightly to accommodate the legend

// Loading...

Orientation

The legend can have a vertical or horizontal orientation. The arrangement of legend items can be configured using the legend.orientation property.

Vertical Orientation

In the vertical orientation, the legend items are arranged using the minimum number of columns possible given the current dimension constraints.

By default, when the legend is positioned to the 'right' or 'left' of a chart, it is rendered in a vertical orientation. The number of columns in a vertical legend increases as the height of a chart shrinks, as fewer legend items can be placed in a given column.

Example: Vertical Legend Layout

// Loading...

Horizontal Layout

If the legend is horizontal, the legend items are arranged using the minimum possible number of rows. If the legend is not wide enough, the items are divided into more rows until everything fits.

By default, when the legend is positioned to the 'bottom' or 'top' of a chart, it is rendered in a horizontal orientation. The number of rows in a horizontal legend increases as the width of a chart shrinks, as fewer legend items can be placed in a given row.

Example: Horizontal Legend Layout

// Loading...

Constraints

The legend width and height can be constrained using the legend.maxWidth and legend.maxHeight properties.

By default, the legend width and height will be a percentage of the chart width and height depending on the legend's orientation.

If the legend maxWidth or maxHeight is set to a value which is larger than the chart width or height, the legend may overflow the chart and become clipped. Likewise, if the maxWidth or maxHeight is too small, the legend layout will contain at least one row or column of items depending on the orientation.

In addition to maxWidth and maxHeight, the legend's layout is also affected by the amount of padding between the legend items. For example, legend.item.paddingX controls the amount of padding between adjacent horizontal legend items:

legend: {
    item: {
        paddingX: 16
    }
}

legend.item.paddingY controls the amount of padding between adjacent vertical legend items:

legend: {
    item: {
        paddingY: 8
    }
}

And the legend.item.marker.padding config is responsible for the amount of padding within a legend item, between the marker and the label:

legend: {
    item: {
        marker: {
            padding: 8
        }
    }
}

Please refer to the example below to get a better idea of how the above configs affect the legend layout.

Example: Legend Constraints

// Loading...

Pagination

If the legend items don't fit within the constraints, the items will be paginated and the pagination component will be displayed.

The pagination component can be customised using legend.pagination. For example, the pagination button markers can be made larger with legend.pagination.marker:

legend: {
    pagination: {
        marker: {
            size: 18
        }
    }
}

legend.pagination.activeStyle and legend.pagination.inactiveStyle can be used to style the pagination buttons when in the active and inactive states.

legend: {
    pagination: {
        activeStyle: {
            fill: 'blue',
            strokeWidth: 0,
        },
        inactiveStyle: {
            fillOpcacity: 0,
        }
    }
}

Example: Legend Pagination

• Initially the legend is positioned at the bottom of the chart so by default, the legend is rendered in the horizontal orientation.
• legend.maxHeight is used to restrict the height of the legend, resulting in a single row of legend items spread across different pages.
• The pagination component appears automatically when the legend items combined with their configured padding do not fit in the given width and height constraints.
• legend.pagination is used to customise the styles of the pagination label and buttons.
• You can switch between different legend positions using the buttons above the chart to see how the legend pagination component behaves.

// Loading...

Labels

There are a number of configs that affect the fontSize, fontStyle, fontWeight, fontFamily, and color of the legend item labels.

maxLength can also be configured to constrain the length of legend item labels, if the label text exceeds the maximum length, it will be truncated and an ellipsis will be appended.

legend: {
    item: {
        label: {
            fontSize: 14,
            fontStyle: 'italic',
            fontWeight: 'bold',
            fontFamily: 'Papyrus',
            color: 'red',
            maxLength: 25
        }
    }
}

Markers

Size and StrokeWidth

All legend items use the same size and strokeWidth, regardless of the size and strokeWidth used by the series they represent. It's possible to adjust the defaults using the following configs:

legend: {
    item: {
        marker: {
            size: 20,
            strokeWidth: 3
        }
    }
}

Shape

Normally, the legend mirrors the marker shapes used by the series, unless the series in question doesn't support markers (for example 'column' series), in which case the legend will use 'square'.

It's also possible to override the default behaviour and make the legend use a specified marker shape for all legend items, regardless of the shapes the series are using:

legend: {
    item: {
        marker: {
            shape: 'circle', // 'square', 'diamond', 'cross', 'plus', 'triangle'
        }
    }
}

Legend Events

The legendItemClick event can be used to listen to legend item clicks. A listener can be configured via legend.listeners.legendItemClick.

The event object passed to the listener includes:

• the seriesId of the series associated with the legend item
• the itemId, usually the yKey value for cartesian series
• enabled, whether the legend item is currently enabled or not

For example, to show an alert message with the legendItemClick event contents when a legend item is clicked, the following listener can be configured:

legend: {
    listeners: {
        legendItemClick: ({
            seriesId,
            itemId,
            enabled,
        }: AgChartLegendClickEvent) => {
            window.alert(
                `seriesId: ${seriesId}, itemId: ${itemId}, enabled: ${enabled}`
            );
        }
    }
}

Series Visibility Toggling

By default, when a legend item is clicked, the visibility of the series associated with that legend item will be toggled. This allows the users to control which series are displayed in the chart by clicking on legend items.

To disable series toggling on legend item click, the legend.item.toggleSeriesVisible property can be set to false:

legend: {
    item: {
        toggleSeriesVisible: false
    }
}

If a callback function is configured via legend.listeners.legendItemClick, it will still be invoked when the legend click event is fired.

Example: Legend Click

// Loading...

API Reference

position: AgChartLegendPosition;

type AgChartLegendPosition = 
      'top' 
    | 'right' 
    | 'bottom' 
    | 'left'

orientation: AgChartOrientation;

type AgChartOrientation = 
      'horizontal' 
    | 'vertical'

maxWidth: PixelSize;

type PixelSize = number

maxHeight: PixelSize;

type PixelSize = number

spacing: PixelSize;

type PixelSize = number

item: AgChartLegendItemOptions;

interface AgChartLegendItemOptions {
  // Configuration for the legend markers. 
  marker?: AgChartLegendMarkerOptions;
  // Configuration for the legend labels. 
  label?: AgChartLegendLabelOptions;
  // Used to constrain the width of legend items. 
  maxWidth?: PixelSize;
  // The horizontal spacing in pixels to use between legend items. 
  paddingX?: PixelSize;
  // The vertical spacing in pixels to use between legend items. 
  paddingY?: PixelSize;
  // Set to `false` to turn off toggling of the series visibility in the chart when the legend item is clicked. 
  toggleSeriesVisible?: boolean;
}

interface AgChartLegendMarkerOptions {
  // The size in pixels of the markers in the legend. 
  size?: PixelSize;
  // If set, overrides the marker shape from the series and the legend will show the specified marker shape instead. If not set, will use a marker shape matching the shape from the series, or fall back to `'square'` if there is none. 
  shape?: MarkerShape;
  // The padding in pixels between a legend marker and the corresponding label. 
  padding?: PixelSize;
  // The width in pixels of the stroke for markers in the legend. 
  strokeWidth?: PixelSize;
}

type PixelSize = number

type MarkerShape = 
      'circle' 
    | 'cross' 
    | 'diamond' 
    | 'heart' 
    | 'plus' 
    | 'triangle' 
    | any


interface AgChartLegendLabelOptions {
  // If the label text exceeds the maximum length, it will be truncated and an ellipsis will be appended to indicate this. 
  maxLength?: number;
  // The colour of the text. 
  color?: CssColor;
  // The font style to use for the legend. 
  fontStyle?: FontStyle;
  // The font weight to use for the legend. 
  fontWeight?: FontWeight;
  // The font size in pixels to use for the legend. 
  fontSize?: FontSize;
  // The font family to use for the legend. 
  fontFamily?: FontFamily;
  // Function used to render legend labels. Where `id` is a series ID, `itemId` is component ID within a series, such as a field name or an item index. 
  formatter?: (params: AgChartLegendLabelFormatterParams) => string;
}

type CssColor = string

type FontStyle = 
      'normal' 
    | 'italic' 
    | 'oblique'


type FontWeight = 
      'normal' 
    | 'bold' 
    | 'bolder' 
    | 'lighter' 
    | '100' 
    | '200' 
    | '300' 
    | '400' 
    | '500' 
    | '600' 
    | '700' 
    | '800' 
    | '900'


type FontSize = number

type FontFamily = string

interface AgChartLegendLabelFormatterParams {
  seriesId: string;
  itemId: any;
  value: string;
}

listeners: AgChartLegendListeners;

interface AgChartLegendListeners {
  // The listener to call when a legend item is clicked. 
  legendItemClick?: (event: AgChartLegendClickEvent) => void;
}

interface AgChartLegendClickEvent {
  // Series id 
  seriesId: string;
  // Legend item id - usually yKey value for cartesian series. 
  itemId: string;
  // Whether the legend item is currently enabled or not. 
  enabled: boolean;
}

pagination: AgChartLegendPaginationOptions;

interface AgChartLegendPaginationOptions {
  // Configuration for the pagination markers. 
  marker?: AgPaginationMarkerOptions;
  // Configuration for pagination buttons when a button is active. 
  activeStyle?: AgPaginationMarkerStyle;
  // Configuration for pagination buttons when a button is inactive. 
  inactiveStyle?: AgPaginationMarkerStyle;
  // Configuration for pagination buttons when a button is hovered over. 
  highlightStyle?: AgPaginationMarkerStyle;
  // Configuration for the pagination label. 
  label?: AgPaginationLabelOptions;
}

interface AgPaginationMarkerOptions {
  // The size in pixels of the pagination buttons. 
  size?: PixelSize;
  // If set, overrides the marker shape for the pagination buttons. If not set, the pagination buttons will default to the `'triangle'` marker shape. 
  shape?: MarkerShape;
  // The inner padding in pixels between a pagination button and the pagination label. 
  padding?: PixelSize;
}

type PixelSize = number

type MarkerShape = 
      'circle' 
    | 'cross' 
    | 'diamond' 
    | 'heart' 
    | 'plus' 
    | 'triangle' 
    | any


interface AgPaginationMarkerStyle {
  // The fill colour to use for the pagination button markers. 
  fill?: CssColor;
  // Opacity of the pagination buttons. 
  fillOpacity?: Opacity;
  // The colour to use for the button strokes. 
  stroke?: CssColor;
  // The width in pixels of the button strokes. 
  strokeWidth?: PixelSize;
  // Opacity of the button strokes. 
  strokeOpacity?: Opacity;
}

type CssColor = string

type Opacity = number

interface AgPaginationLabelOptions {
  // The colour of the text. 
  color?: CssColor;
  // The font style to use for the pagination label. 
  fontStyle?: FontStyle;
  // The font weight to use for the pagination label. 
  fontWeight?: FontWeight;
  // The font size in pixels to use for the pagination label. 
  fontSize?: FontSize;
  // The font family to use for the pagination label. 
  fontFamily?: FontFamily;
}

type FontStyle = 
      'normal' 
    | 'italic' 
    | 'oblique'


type FontWeight = 
      'normal' 
    | 'bold' 
    | 'bolder' 
    | 'lighter' 
    | '100' 
    | '200' 
    | '300' 
    | '400' 
    | '500' 
    | '600' 
    | '700' 
    | '800' 
    | '900'


type FontSize = number

type FontFamily = string

Next Up

Continue to the next section to learn about the series.