`.chart`

class: `ChartOptions`

class ChartOptions(**kwargs)[source]

Configuration settings that apply to a chart.

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

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') → 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'.

Return type:

str or None

to_json(filename=None, encoding='utf-8')

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'.

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) → 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.

Returns:

Trimmed dict

Return type:

dict

static trim_iterable(untrimmed, to_json=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.

Return type:

iterable

property align_thresholds: bool | None

When using multiple axes, align the thresholds. When True, other ticks will also be aligned. Defaults to False.

Note

For line series and some other series types, the threshold option is set to null by default. This will in turn cause their y-axis to not have a threshold. In order to avoid that, set the series threshold to 0 or another number.

Note

If AxisOptions.start_on_tick() or AxisOptions.end_on_tick() are set to False, or if the axis is logarithmic, the threshold will not be aligned.

Returns:: Flag indicating whether thresholds should be aligned.
Return type:: bool or None

property align_ticks: bool | None

If True and using multiple axes, the ticks of two or more opposite axes will automatically be aligned by adding ticks to the axis or axes with the least ticks, as if tick_amount were specified. This can be prevented by setting align_ticks to False.

Defaults to True.

Hint

If the grid lines look messy, it’s a good idea to hide them for the secondary axis by setting grid_line_width to 0.

Warning

If start_on_tick or end_on_tick in the axis options are set to False, then tick alignment will be disabled for the axis.

Warning

Aways disabled for logarithmic axes.

Returns:: Flag indicating whether ot align ticks along the axes.
Return type:: bool or None

property allow_mutating_data: bool | None

If True, the original data source will be allowed to be mutated. However, if False then Highcharts will create a copy of the original data to prevent inadvertent mutation. Defaults to True.

Note

By default, (for memory and performance reasons) the chart does not copy the data but keeps it as a reference.

In some cases, this might result in mutating the original data source. In order to prevent that, set this property to False. Please note that changing this may decrease performance, especially with bigger sets of data.

Returns:: Flag indicating whether to allow mutation by referencing th eoriginal data (True), or prevent it by copying the original data (False).
Return type:: bool or None

property animation: bool | AnimationOptions | None

Configures the overall animation for all chart updating.

The animation can be configured as either a boolean or a AnimationOptions object. If True, it will apply the 'swing' jQuery easing and a duration of 500 ms by default. If used as a AnimationOptions instance, you have more fine-grianed configuration control.

Animation can be disabled throughout the chart by setting it to False here. It can be overridden for each individual API method as a function parameter. The only animation not affected by this option is the initial series animation, see PlotOptions.series.animation().

When zooming on a series with less than 100 points, the chart redraw will be done with animation, but in case of more data points, it is necessary to set this option to ensure animation on zoom.

Returns:: Settings for the animation of image patterns.
Return type:: AnimationOptions or None

property background_color: str | Gradient | Pattern | None

The background color or gradient for the outer chart area. Defaults to '#ffffff'.

Returns:: The background color for the outer chart area.
Return type:: str, Gradient, Pattern`, or None

property border_color: str | Gradient | Pattern | None

The color of the outer chart border. Defaults to '#335cad'.

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

property border_radius: int | float | Decimal | None

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

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

property border_width: int | float | Decimal | None

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

Returns:: The border width to apply to the outer chart border.
Return type:: numeric 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 color_count: int | None

In styled mode, sets how many colors the class names should rotate between. Defaults to 10

With ten colors, series (or points) are given class names like highcharts-color-0, highcharts-color-0 […] highcharts-color-9. The equivalent in non-styled mode is to set colors using the colors setting.

Returns:: The number of colors to cycle through in styled mode.
Return type:: int or None

property display_errors: bool | None

If True, will display errors on the chart itself. If False, will only report errors to the console. Defaults to True.

Returns:: Flag indicating whether ot display errors on the chart.
Return type:: bool or None

property events: ChartEvents | None

Definition of JavaScript event listeners to apply to the chart.

Return type:: ChartEvents or None

An explicit height for the chart. Defaults to None.

If a number, the height is given in pixels. If given a percentage string (for example '56%'), the height is given as the percentage of the actual chart width. This allows for preserving the aspect ratio across responsive sizes.

By default (when None python:None>) the height is calculated from the offset height of the containing element, or 400 pixels if the containing element’s height is 0.

Return type:: EnforcedNullType or numeric or str or None

property ignore_hidden_series: bool | None

If True, the axes will scale to the remaining visible series once one series is hidden. If False, hiding and showing a series will not affect the axes or the other series.

Defaults to True.

Note

For stacks, once one series within the stack is hidden, the rest of the stack will close in around it even if the axis is not affected.

Returns:: Flag indicating whether to ignore hidden series.
Return type:: bool or None

property inverted: bool | None

If True, inverts the axes so that the x-axis is vertical and y-axis is horizontal. Defaults to False.

Hint

When True, the x-axis is reversed by default.

Warning

If a bar series is present in the chart, it will be inverted automatically.

Hint

Inverting the chart doesn’t have an effect if there are no cartesian series in the chart, or if the chart is a polar chart type.

Returns:: Flag indicating whether to invert the axes.
Return type:: bool or None

property is_async: bool

Read-only property which indicates whether the data visualization should be rendered using asynchronous logic.

Note

This property will only return True if one or more series rely on AsyncMapData

Return type:: bool

Map geometries that provide instructions on how to render the map itself, along with relevant properties used to join each map area to its corresponding values in the MapSeriesBase.data.

Accepts (either in object representation or as coercable objects):

MapData

AsyncMapData

VariableName

GeoJSONBase or descendant

Topology

a str URL, which will be coerced to AsyncMapData

a str number, which will act as an index to the (JavaScript) Highcharts.maps array

Return type:: MapData or AsyncMapData or None

property map_transforms: dict | None

Set of latitude/longitude transformation definitions for the chart. If None, will be extracted automatically from the underlying map geometry. Defaults to None.

Return type:: dict or None

property margin: List[int | float | Decimal] | None

The margin between the outer edge of the chart and the plot area. The numbers in the array designate top, right, bottom and left respectively.

By default there is no margin. The actual space is dynamically calculated from the offset of axis labels, axis title, title, subtitle and legend in addition to the spacing_top, spacing_right, spacing_bottom and spacing_left options.

Note

This property is a convenience property to consolidate simple margin configuration across the margin_top, margin_right, margin_bottom, and margin_left options. Values will be propagated between all options.

Return type:: list of four numeric values or None

property margin_bottom: int | float | Decimal | None

The margin between the bottom outer edge of the chart and the plot area. Use this to set a fixed pixel value for the margin as opposed to the default dynamic margin.

By default, not set.

See also

Chart.spacing_bottom()

Return type:: numeric or None

property margin_left: int | float | Decimal | None

The margin between the left outer edge of the chart and the plot area. Use this to set a fixed pixel value for the margin as opposed to the default dynamic margin.

By default, not set.

See also

Chart.spacing_left()

Return type:: numeric or None

property margin_right: int | float | Decimal | None

The margin between the right outer edge of the chart and the plot area. Use this to set a fixed pixel value for the margin as opposed to the default dynamic margin.

By default, not set.

See also

Chart.spacing_right()

Return type:: numeric or None

property margin_top: int | float | Decimal | None

The margin between the top outer edge of the chart and the plot area. Use this to set a fixed pixel value for the margin as opposed to the default dynamic margin.

By default, not set.

See also

Chart.spacing_top()

Return type:: numeric or None

property number_formatter: CallbackFunction | None

JavaScript Callback function to override the default function that formats all the numbers in the chart. Returns a string with the formatted number.

Return type:: CallbackFunction or None

property options_3d: Options3D | None

Options to render charts in three dimensions.

Note

This feature requires the JavaScript highcharts-3d.js module, found in the download package or online at code.highcharts.com/highcharts-3d.js.

Return type:: Options3D or None

property pan_key: str | None

Allows setting a key to switch between zooming and panning.

Accepts the following values:

'alt'

'ctrl'

'meta' (the command key on Mac and Windows key on Windows)

'shift'.

The keys are mapped directly to the key properties of the click event argument (event.altKey, event.ctrlKey, event.metaKey, and event.shiftKey).

Returns:: The key that switches between zooming and panning.
Return type:: str or None

property panning: PanningOptions | None

Configures panning behavior in a chart.

Hint

Best used with Chart.pan_key() to combine zooming and panning.

Note

On touch devices, when the Tooltip.follow_touch_move() property is True (default), panning requires two fingers. To allow panning with one finger, set follow_touch_move to False.

Returns:: Configuration settings for panning behavior.
Return type:: PanningOptions or None

property parallel_axes: ParallelAxesOptions | None

Common options for all Y-Axes rendered in a parallel coordinates plot.

Note

This feature requires in JavaScript modules/parallel-coordinates.js.

Return type:: ParallelAxesOptions or None

property parallel_coordinates: bool | None

If True, renders charts as a parallel coordinates plot. Defaults to False.

In a parallel coordinates plot (||-coords) by default all required Y-axes are generated and the legend is disabled.

Note

This feature requires the JavaScript module modules/parallel-coordinates.js.

See also

Parallel Coordinates Demo

Returns:: Flag indicating whether the chart is a parallel coordinates plot.
Return type:: bool or None

property plot_background_color: str | Gradient | Pattern | None

The background color or gradient for the plot area. Defaults to None.

Returns:: The background color for the plot area.
Return type:: str, Gradient, Pattern`, or None

property plot_background_image: str | None

The URL for an image to use as the background of the plot area.

Hint

To set an image as the background for the entire chart, set a CSS background image to the container element.

Note

Note that for the image to be applied to exported charts, its URL needs to be accessible by the export server.

Return type:: str or None
Raises:: HighchartsValueError – if a value is supplied that is not a URL or not path-like

property plot_border_color: str | Gradient | Pattern | None

The color of the outer chart border. Defaults to '#cccccc'.

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

property plot_border_width: int | float | Decimal | None

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

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

property plot_shadow: bool | ShadowOptions | None

Configuration of a drop shadow applied to the plot area. 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 Chart.plot_background_color() be set.

Return type:: bool or None

property polar: bool | None

If True, cartesian charts like line, spline, area, and column are transformed into the polar coordinate system. This produces polar charts (also known as radar charts). Defaults to False.

Returns:: Flag indicating whether to render the chart as a polar chart.
Return type:: bool or None

property proj4: CallbackFunction | None

Function which can be used to manually load the proj4 JavaScript library which Highcharts Maps depends on. Defaults to None, which assumes that the proj4 library is loaded via (HTML) <script/> tag.

Return type:: CallbackFunction or None

property reflow: bool | None

If True, reflows the chart to fit the width of the container div when the window is resized. Defaults to True.

Returns:: Flag indicating whether to reflow the chart in response to window resizing.
Return type:: bool or None

property render_to: str | None

The ID of the HTML element where the chart will be rendered.

Note

In JavaScript, the HTML element can also be passed by direct reference, or as the first argument of the chart constructor, in which case the option is not needed.

Return type:: str or None

property scrollable_plot_area: ScrollablePlotArea | None

Configuration settings to make the plot area scrollable.

This feature provides a minimum size for the plot area of the chart. If the size gets smaller than this, typically on mobile devices, a native browser scrollbar is presented. This scrollbar provides smooth scrolling for the contents of the plot area, whereas the title, legend and unaffected axes are fixed.

Hint

Since v7.1.2, a scrollable plot area can be defined for either horizontal or vertical scrolling, depending on whether the minimum_width or minimum_height options are set.

Return type:: ScrollablePlotArea or None

property selection_marker_fill: str | Gradient | Pattern | None

The background color or the marker square when selecting (zooming in on) an area of the chart. Defaults to 'rgba(51,92,173,0.25)'.

Returns:: The backgorund color of the marker square when selecting an area of the chart.
Return type:: str, Gradient, Pattern`, or None

property shadow: bool | ShadowOptions | None

Configuration of a drop shadow applied to the outer chart area. 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 Chart.background_color() be set.

Return type:: bool or None

property show_axes: bool | None

If True, shows axes initially (before series have been added to the chart).

Warning

This property only applies to empty charts where series are added dynamically.

Returns:: Flag indicating whether to show axes on empty dynamic charts before series have been added.
Return type:: bool or None

property spacing: List[int | float | Decimal] | None

The distance between the outer edge of the chart and the content, like title or legend, or axis title and labels if present. The numbers in the array designate top, right, bottom and left respectively.

By default, [10,10,15,10].

Note

This property is a convenience property to consolidate simple spacing configuration across the spacing_top, spacing_right, spacing_bottom, and spacing_left options. Values will be propagated between all options.

Return type:: list of four numeric values or None

property spacing_bottom: int | float | Decimal | None

The spacing between the bottom edge of the chart and the content (plot area, axis title and labels, title, subtitle or legend in top position).

By default, 15.

Return type:: numeric or None

property spacing_left: int | float | Decimal | None

The spacing between the left edge of the chart and the content (plot area, axis title and labels, title, subtitle or legend in top position).

Defaults to 10.

Return type:: numeric or None

property spacing_right: int | float | Decimal | None

The spacing between the right edge of the chart and the content (plot area, axis title and labels, title, subtitle or legend in top position).

Defaults to 10.

Return type:: numeric or None

property spacing_top: int | float | Decimal | None

The spacing between the top edge of the chart and the content (plot area, axis title and labels, title, subtitle or legend in top position).

Defaults to 10.

Return type:: numeric or None

property style: str | None

Additional CSS styles to apply inline to the container div.

Defaults to '{"fontFamily": ""Lucida Grande", "Lucida Sans Unicode", Verdana, Arial, Helvetica, sans-serif","fontSize":"12px"}'.

Note

Since the default font styles are applied in the renderer, it is ignorant of the individual chart options and must be set globally.

Return type:: str or None

property styled_mode: bool | None

If True, sets the chart to operate in styled mode, where no presentational attributes or CSS are applied to the chart SVG. Instead, CSS rules are required to style the chart. Defaults to False.

See also

Available CSS Styles and Variables.
The Default Style Sheet: https://code.highcharts.com/css/highcharts.css.

Return type:: bool or None

property type: str | None

The default series type for the chart. Defaults to 'line'.

Can be any of the chart types listed under PlotOptions and Series, or can be a series provided by an additional module.

Return type:: str or None

An explicit width for the chart.

Defaults to EnforcedNull <EnforcedNullType>` which indicates a JavaScript value of null (as opposed to None which results in undefined when converted JavaScript.)

If a number, the width is given in pixels. If given a percentage string (for example '56%'), the width is given as the percentage of the actual chart width. This allows for preserving the aspect ratio across responsive sizes.

By default (when null) the width is calculated from the offset width of the containing element.

Return type:: EnforcedNullType or numeric or str or None

property zooming: ZoomingOptions | None

Chart zooming configuration.

Return type:: ZoomingOptions or None

class: `PanningOptions`

class PanningOptions(**kwargs)[source]

Configures panning behavior in a chart.

Hint

Best used with Chart.pan_key() to combine zooming and panning.

Note

On touch devices, when the Tooltip.follow_touch_move() property is True (default), panning requires two fingers. To allow panning with one finger, set follow_touch_move to False.

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

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') → 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'.

Return type:

str or None

to_json(filename=None, encoding='utf-8')

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'.

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) → 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.

Returns:

Trimmed dict

Return type:

dict

static trim_iterable(untrimmed, to_json=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.

Return type:

iterable

property enabled: bool | None

If True, enables chart panning. Defaults to False.

Returns:: Flag enabling or disabling chart panning.
Return type:: bool or None

property type: str | None

Determines in what dimensions the user can pan the chart. Defaults to 'x'.

Accepts:

'x'

'y'

'xy'

Return type:: str or None

Sub-components 

Module	Classes / Functions
`.options.chart`	`ChartOptions` `PanningOptions`
`.chart.options_3d`	`Options3D` `Frame` `PanelOptions`
`.chart.reset_zoom_button`	`ResetZoomButtonOptions`
`.chart.scrollable_plot_area`	`ScrollablePlotArea`
`.options.chart.zooming`	`ZoomingOptions`

.chart

class: ChartOptions

class: PanningOptions

Sub-components

`.chart`

class: `ChartOptions`

class: `PanningOptions`

Sub-components 