Charts - Legend

#Usage

import { ChartColorLegend, ChartGroup, ChartLegend, ChartSvg } from '@primeui/vue-chart';

<ChartSvg>
    <!-- series and axes -->
    <ChartLegend />
</ChartSvg>

Legends are opt-in: add ChartLegend to display a series key; remove it and no space is reserved. Clicking an entry toggles that series. Use position, alignment, and layout to control placement; use render to replace individual entries with custom content.

#Basic

Add ChartLegend to display a legend below the chart. Each series appears as a separate entry. Click any item to toggle that series on or off.

#Position

Set position to place the legend on any side of the chart. Each position reduces the chart area to make room for the legend.

#Alignment

Set align to start, center, or end to control how legend items are aligned within the legend area. start left-aligns items, center centers them, and end right-aligns them.

#Layout

Set layout="vertical" to stack legend items vertically instead of the default horizontal row. Vertical layout pairs well with position="left" or position="right".

#Overflow

The legend area is pre-calculated by the layout engine as a fixed rectangle. maxWidth and maxHeight cap the legend container within that space and enable scrolling when content exceeds the limit. For top/bottom legends use maxHeight, for left/right legends use maxWidth. Use width and height to lock the container to a fixed size regardless of item count.

#Icon Shape

Set iconShape to control the marker shape shown next to each legend label. circle renders a dot, line a thin bar, and square a filled box. The default auto picks a shape that matches the mark: line and area series show a line, scatter, bubble, pie, and donut show a dot, and everything else shows a square.

#Styling

Set fontSize, fontFamily, fontWeight, and color to customize legend label text. Set iconSize to control the marker size. Use width and height to fix the legend container dimensions.

#Interactive

Set interactive to false to disable click-to-toggle behavior. Use it for static charts and reports where legend items are labels. To intercept clicks and run custom logic, use onClick.

#Shared Mode

When ChartLegend is placed inside ChartGroup outside individual charts, it acts as a shared legend controlling all synced charts. Set mode to control what each entry represents: dataset for one entry per series (default), category for one entry per shared category label, or both for dataset entries followed by category entries.

For full configuration see Synced Charts.

#Custom Legend

Set render to replace each legend item with custom content. The callback receives a LegendItemRenderContext for each item, including label, color, visible, isHovered, and event handlers for click and hover. Return a VNode per item.

#Color Legend

Add ChartColorLegend to display a continuous gradient bar mapping values to colors. It renders only when a scale is available: from a heatmap, a value-colored treemap, or an explicit colorScale/colorRange on the legend. Without a scale it renders nothing. Set ticks to control the number of labels and formatLabel to customize their text. Set steps to render discrete color blocks instead of a smooth gradient. Use width and height to control the gradient bar dimensions.

#API

#ChartLegend

#LegendClickContext

Passed to the onClick callback when a legend item is clicked.

#LegendItemRenderContext

Passed to the render callback for each legend item.

#ChartColorLegend

Renders a value-to-color scale from a heatmap, a value-colored treemap, or an explicit colorScale/colorRange. With no resolvable scale it renders nothing.

#Related Docs

• Heatmap
• Treemap
• Synced Charts
• Hover