`.legend`

class: `Legend`

class Legend(**kwargs)[source]

The legend is a box containing a symbol and name for each series item or point item in the chart. Each series (or points in case of pie charts) is represented by a symbol and its name in the legend.

See also

It is possible to override the symbol creator function and create custom legend symbols.

Class Inheritance

copy(other=None, overwrite=True, **kwargs)

Copy the configuration settings from this instance to the other instance.

Parameters:

other (HighchartsMeta) – The target instance to which the properties of this instance should be copied. If None, will create a new instance and populate it with properties copied from self. Defaults to None.
overwrite (bool) – if True, properties in other that are already set will be overwritten by their counterparts in self. Defaults to True.
kwargs – Additional keyword arguments. Some special descendents of HighchartsMeta may have special implementations of this method which rely on additional keyword arguments.

Returns:

A mutated version of other with new property values

classmethod from_dict(as_dict: dict, allow_snake_case: bool = True)

Construct an instance of the class from a dict object.

Parameters:

as_dict (dict) – A dict representation of the object.
allow_snake_case (bool) – If True, interprets snake_case keys as equivalent to camelCase keys. Defaults to True.

Returns:

A Python object representation of as_dict.

Return type:

HighchartsMeta

classmethod from_js_literal(as_str_or_file, allow_snake_case: bool = True, _break_loop_on_failure: bool = False)

Return a Python object representation of a Highcharts JavaScript object literal.

Parameters:

as_str_or_file (str) – The JavaScript object literal, represented either as a str or as a filename which contains the JS object literal.
allow_snake_case (bool) – If True, interprets snake_case keys as equivalent to camelCase keys. Defaults to True.
_break_loop_on_failure (bool) – If True, will break any looping operations in the event of a failure. Otherwise, will attempt to repair the failure. Defaults to False.

Returns:

A Python object representation of the Highcharts JavaScript object literal.

Return type:

HighchartsMeta

classmethod from_json(as_json_or_file, allow_snake_case: bool = True)

Construct an instance of the class from a JSON string.

Parameters:

as_json_or_file – The JSON string for the object or the filename of a file that contains the JSON string.
allow_snake_case (bool) – If True, interprets snake_case keys as equivalent to camelCase keys. Defaults to True.

Returns:

A Python objcet representation of as_json.

Return type:

HighchartsMeta

get_required_modules(include_extension=False) → List[str]

Return the list of URLs from which the Highcharts JavaScript modules needed to render the chart can be retrieved.

Parameters:: include_extension (bool) – if True, will return script names with the '.js' extension included. Defaults to False.
Return type:: list of str

to_dict() → dict

Generate a dict representation of the object compatible with the Highcharts JavaScript library.

Note

The dict representation has a property structure and naming convention that is intentionally consistent with the Highcharts JavaScript library. This is not Pythonic, but it makes managing the interplay between the two languages much, much simpler.

Returns:: A dict representation of the object.
Return type:: dict

to_js_literal(filename=None, encoding='utf-8', careful_validation=False) → str | None

Return the object represented as a str containing the JavaScript object literal.

Parameters:

filename (Path-like) – The name of a file to which the JavaScript object literal should be persisted. Defaults to None
encoding (str) – The character encoding to apply to the resulting object. Defaults to 'utf-8'.
careful_validation – if True, will carefully validate JavaScript values

along the way using the esprima-python library. Defaults to False.

Warning

Setting this value to True will significantly degrade serialization performance, though it may prove useful for debugging purposes.

Return type:: str or None

to_json(filename=None, encoding='utf-8', for_export: bool = False)

Generate a JSON string/byte string representation of the object compatible with the Highcharts JavaScript library.

Note

This method will either return a standard str or a bytes object depending on the JSON serialization library you are using. For example, if your environment has orjson, the result will be a bytes representation of the string.

Parameters:

filename (Path-like) – The name of a file to which the JSON string should be persisted. Defaults to None
encoding (str) – The character encoding to apply to the resulting object. Defaults to 'utf-8'.
for_export (bool) – If True, indicates that the method is being run to produce a JSON for consumption by the export server. Defaults to False.

Returns:

A JSON representation of the object compatible with the Highcharts library.

Return type:

str or bytes

static trim_dict(untrimmed: dict, to_json: bool = False, context: str = None, for_export: bool = False) → dict

Remove keys from untrimmed whose values are None and convert values that have .to_dict() methods.

Parameters:

untrimmed (dict) – The dict whose values may still be None or Python objects.
to_json (bool) – If True, will remove all keys from untrimmed that are not serializable to JSON. Defaults to False.
context (str or None) – If provided, will inform the method of the context in which it is being run which may inform special handling cases (e.g. where empty strings may be important / allowable). Defaults to None.
for_export (bool) – If True, indicates that the method is being run to produce a JSON for consumption by the export server. Defaults to False.

Returns:

Trimmed dict

Return type:

dict

static trim_iterable(untrimmed, to_json=False, context: str = None, for_export: bool = False)

Convert any EnforcedNullType values in untrimmed to 'null'.

Parameters:

untrimmed (iterable) – The iterable whose members may still be None or Python objects.
to_json (bool) – If True, will remove all members from untrimmed that are not serializable to JSON. Defaults to False.
context (str or None) – If provided, will inform the method of the context in which it is being run which may inform special handling cases (e.g. where empty strings may be important / allowable). Defaults to None.
for_export (bool) – If True, indicates that the method is being run to produce a JSON for consumption by the export server. Defaults to False.

Return type:

iterable

property accessibility: LegendAccessibilityOptions | None

Accessibility options for the legend.

Note

Requires the Accessibility module.

Return type:: LegendAccessibilityOptions or None

property align: str | None

The horizontal alignment of the legend box within the chart area. Defaults to 'center'.

Valid values are:

'left'

'center'

'right'

In the case that the legend is aligned in a corner position, the Legend.layout() setting will determine whether to place it above/below or on the side of the plot area.

Return type:: str or None

property align_columns: bool | None

If the layout is horizontal and the legend items span over two lines or more, if the value is True will align the items into vertical columns.

Setting this to False makes room for more items, but will look more messy.

Defaults to True.

Return type:: bool or None

property background_color: str | Gradient | Pattern | None

The background color or gradient for the legend. Defaults to None.

Returns:: The backgorund color for the legend..
Return type:: str, Gradient, Pattern`, or None

property border_color: str | Gradient | Pattern | None

The border color drawn around the legend. Defaults to '#999999'.

Returns:: The color of the legend border.
Return type:: str, Gradient, Pattern`, or None

property border_radius: int | float | Decimal | None

The border radius (in pixels) applied to the legend border. Defaults to 0.

Returns:: The border radius to apply to the legend border.
Return type:: numeric or None

property border_width: int | float | Decimal | None

The border width (in pixels) applied to the legend border. Defaults to 0.

Returns:: The border width to apply to the legend border.
Return type:: numeric or None

property bubble_legend: BubbleLegend | None

The bubble legend is an additional element in legend which presents the scale of the bubble series.

Individual bubble ranges can be defined by user or calculated from series. In the case of automatically calculated ranges, a 1px margin of error is permitted.

Return type:: BubbleLegend or None

property class_name: str | None

A classname to apply styling using CSS.

Returns:: The classname to apply to enable styling via CSS.
Return type:: str or None

property enabled: bool | None

If True, displays the legend. If False, hides the legend. Defaults to False.

Note

There is also a series-specific option, PlotOptions.series.show_in_legend(), that can hide the series from the legend. In some series types this is False by default, so it must set to True in order to show the legend for the series.

Return type:: bool or None

property floating: bool | None

If True, the plot area ignores the legend and can be rendered below the legend. If False, the legend is rendered visually distinct (not overlapping) the plot area. Defaults to False.

Return type:: bool or None

property item_checkbox_style: str | dict | None

Default styling for the checkbox next to a legend item when Legend.show_checkbox() is True. Defaults to: '{"width": "13px", "height": "13px", "position":"absolute"}'.

Return type:: str or dict or None

property item_distance: int | float | Decimal | None

In a legend with horizontal layout, the itemDistance defines the pixel distance between each item. Defaults to 20.

Return type:: numeric or None

property item_hidden_style: str | dict | None

Default styling for the legend item when the corresponding series or data point is hidden. Defaults to: '{"color": "#cccccc"}'.

Warning

Only a subset of CSS is supported, notably those options related to text.

Note

Properties are inherited from Legend.style() unless overridden here.

Return type:: str or None

property item_hover_style: str | dict | None

Default styling for the legend item when the corresponding series or data point is in a hover state. Defaults to: '{"color": "#000000"}'.

Warning

Only a subset of CSS is supported, notably those options related to text.

Note

Properties are inherited from Legend.style() unless overridden here.

Return type:: str or dict or None

property item_margin_bottom: int | float | Decimal | None

The bottom margin expressed in pixels for each legend item. Defaults to 0.

Return type:: numeric or None

property item_margin_top: int | float | Decimal | None

The top margin expressed in pixels for each legend item. Defaults to 0.

Return type:: numeric or None

property item_style: str | dict | None

Default styling for each legend item. Defaults to: {"color": "#333333", "cursor": "pointer", "fontSize": "12px", "fontWeight": "bold", "textOverflow": "ellipsis"}.

Warning

Only a subset of CSS is supported, notably those options related to text. However, a "width" property can be added to control the text width.

Note

The default "textOverflow" property makes long texts truncate. Set it to undefined to wrap text instead.

Return type:: str or None

property item_width: int | float | Decimal | None

The width for each legend item, expressed in pixels. Defaults to None.

By default, the items are laid out successively. In a horizontal layout, if the items are laid out across two rows or more, they will be vertically aligned depending on the Legend.align_columns() setting.

Return type:: numeric or None

property label_format: str | None

A format string for each legend label. Defaults to: '{name}'.

Note

Available variables relate to properties on the {{series}}, or the {{point}} in the case of pie charts.

Return type:: str or None

property label_formatter: CallbackFunction | None

A JavaScript callback function that formats each of the series’ labels.

Note

The (JavaScript) this keyword refers to the series object for most chart types, and refers to the point object for pie charts.

Return type:: CallbackFunction or None

property layout: str | None

The layout of the legend items. Defaults to 'horizontal'.

Accepts:

'horizontal'

'vertical'

'proximate'

When proximate, the legend items will be placed as close as possible to the graphs they’re representing, except in inverted charts or when the legend position does not allow it.

Return type:: str or None

property margin: int | float | Decimal | None

If the plot area sized is calculated automatically and the legend is not floating, the legend margin is the space between the legend and the axis labels or plot area. Defaults to 12.

Return type:: numeric or None

property max_height: int | float | Decimal | None

The maximum height for the legend, expressed in pixels. Defaults to None.

When the maximum height is extended, navigation will show.

Return type:: numeric or None

property navigation: LegendNavigation | None

Options for paging or navigation within the legend when the legend overflows the available space.

Hint

Navigation works well on screen, but not in static exported images. One way of working around that is to increase the chart height in export.

Return type:: LegendNavigation or None

property padding: int | float | Decimal | None

The inner padding of the legend box. Defaults to 8.

Return type:: numeric or None

property reversed: bool | None

If True, reverses the order of the legend items compared to the order of series/points as defined in the configuration object. Defaults to False.

Return type:: bool or None

property rtl: bool | None

If True, displays the symbol on the right side of the text rather than the left (this is common in RTL languages like Arabic or Hebrew). Defaults to False.

Return type:: bool or None

property shadow: bool | ShadowOptions | None

Configuration of a drop shadow applied to the legend box. Accepts either a boolean value of False which disables any shadow, or a ShadowOptions instance with the applicable configuration.

Defaults to False.

Warning

Requires that Legend.background_color() be set.

Return type:: bool or ShadowOptions or None

property square_symbol: bool | None

If True, the legend symbol width will be the same as the symbol height, which in turn defaults to the font size of the legend items. Defaults to True.

Return type:: bool or None

property symbol_height: int | float | Decimal | None

The height of the symbol (in pixels) for series types that use a rectangle in the legend. Defaults to the font size of legend items.

Return type:: numeric or None

property symbol_padding: int | float | Decimal | None

The pixel padding between the legend item symbol and the item text. Defaults to 5.

Return type:: numeric or None

property symbol_radius: int | float | Decimal | None

The border radius of symbol for series types that use a rectangle in the legend. Defaults to one half of the Legend.symbol_height.

Return type:: numeric or None

property symbol_width: int | float | Decimal | None

The width of the legend item symbol (in pixels). When Legend.square_symbol() is True, this defaults to the Legend.symbol_height(), otherwise 16.

Return type:: numeric or None

property title: LegendTitle | None

A title to be added on top of the legend.

Return type:: LegendTitle or None

property use_html: bool | None

If True, will use HTML to render the legend item texts. If False, will use SVG or WebGL as applicable.

Defaults to False.

Returns:: Flag indicating whether to render annotation labels using HTML.
Return type:: bool or None

property vertical_align: str | None

The vertical alignment of the legend box. Defaults to 'bottom'.

Accepts:

'bottom'

'middle'

'top'

Hint

Vertical position can be further determined by the Legend.y() option.

Note

If the legend is aligned in a corner position, the Legend.layout() setting will determine whether to place it above/below or on the side of the plot area.

When the layout option is 'proximate', the vertical_align option does not apply.

Return type:: str or None

property width: int | float | Decimal | str | None

The width of the legend box. If expressed as a numeric value, the value is in pixels. If as a str, then accepts a value expressed as a percentage of the chart area (e.g. '40%').

If None, then defaults to the full chart width if above or below the chart and half the chart width aligned to the left or right of the chart.

Defaults to None.

Return type:: numeric or None

property x: int | None

The x position offset of the legend relative to its horizontal alignment (Legend.align()) within Chart.spacing_left() and Chart.spacing_right(). Defaults to 0.

Note

Negative values move it to the left, positive values move it to the right.

Return type:: numeric or None

property y: int | None

The y position offset of the legend relative to its vertical alignment (Legend.vertical_align()) within Chart.spacing_top() and Chart.spacing_bottom(). Defaults to 0.

Note

Negative values move it up, positive values move it down.

Return type:: numeric or None

Sub-components 

Module	Classes / Functions
`.options.legend`	`Legend`
`.options.legend.accessibility`	`LegendAccessibilityOptions` `LegendKeyboardNavigation`
`.options.legend.bubble_legend`	`BubbleLegend` `BubbleLegendRange` `BubbleLegendLabelOptions`
`.options.legend.navigation`	`LegendNavigation`
`.options.legend.title`	`LegendTitle`

.legend

class: Legend

Sub-components

`.legend`

class: `Legend`

Sub-components 