.tooltips

---

class: Tooltip

class Tooltip(**kwargs)

Options for the tooltip that appears when the user hovers over a series or point.

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 animation: bool | None

Flag which indicates whether animation is enabled on the toltip (True).

Defaults to True.

Return type:

bool or None

property background_color: str | Gradient | Pattern | None

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

Returns:

The backgorund color for the tooltip.

Return type:

str, Gradient, Pattern`, or None

property border_color: str | Gradient | Pattern | None

The color of the tooltip border.

Returns:

The color of the tooltip’s border.

Return type:

str, Gradient, Pattern`, or None

property border_radius: int | float | Decimal | str | None

The border radius (in pixels) applied to the pane. Defaults to 3.

Returns:

The border radius of the tooltip.

Return type:

numeric or None

property border_width: int | float | Decimal | None

The border width (in pixels) applied to the tooltip. Defaults to 1.

Returns:

The border width to apply to the tooltip.

Return type:

numeric or None

property class_name: str | None

A classname to apply styling using CSS. Defaults to None.

Returns:

The classname to apply to enable styling via CSS.

Return type:

str or None

property cluster_format: str | None

The HTML of the cluster point’s in the tooltip.

Warning

Works only with marker-clusters module and analogously to Tooltip.point_format().

Note

The cluster tooltip can be also formatted using the Tooltip.formatter() callback function and the Point.is_cluster() flag.

Return type:

str or None

property date_time_label_formats: DateTimeLabelFormats | None

For series on datetime axes, the date format in the tooltip’s header will by default be guessed based on the closest data points. This property gives the default string representations used for each unit.

Defaults to None

Return type:

DateTimeLabelFormats or None

property distance: int | float | Decimal | None

The distance (in pixels) from the point to the tooltip. Defaults to 16.

Returns:

The distance from the point to the tooltip.

Return type:

numeric or None

property enabled: bool | None

If True, enables the use of tooltips. Defaults to True.

Return type:

bool or None

property follow_pointer: bool | None

If True, the tooltip will follow the mouse pointer as it moves across columns, pie slices, and other point types with an extent. Defaults to False generally, except for pie, polygon, map, sankey, and wordcloud series types where the generic False is over-ridden by default.

Note

If Tooltip.split() is True, then this property is ignored.

Return type:

bool or None

property follow_touch_move: bool | None

If True, the tooltip will follow the single finger touches on a touch base. Defaults to True.

Note

If this is True and Chart.panning() is set, this property will take over one-finger touch moves so the user will need to use two fingers for zooming and panning.

Note

There is a significant difference to behavior when compared to Tooltip.follow_pointer(), which updates the position of the tooltip. For example, if follow_pointer is False for a column series, the tooltip will show above or below the column. However, when follow_touch_move is True, the tooltip displayed will jump from column to column (above or below the column as applicable) as the user swipes across the plot area.

Return type:

bool or None

property footer_format: str | None

A string to append to the tooltip format. Defaults to '' (an empty string).

Return type:

str or None

property format: str | None

A format string for the entire tooltip. Defaults to None.

Tip

When format strings are required, it is usually more convenient to use .header_format, .point_format, and .footer_format.

However, the .format option allows combining them into one setting.

Note

The context of the format string is the same as that of the .formatter callback.

Return type:

str

property formatter: CallbackFunction | None

JavaScript callback function to format the text of the tooltip from scratch. Defaults to None

In case of single or shared tooltips, it should return an array where the first item is the header, and subsequent items are mapped to the points. Return false to disable the tooltip for a specific point on a series.

Note

A subset of HTML is supported. Unless Tooltip.use_html() is True, the HTML of the tooltip is parsed and converted to SVG, therefore this is not a complete HTML renderer. The following HTML tags are supported: b, br, em, i, span, strong.

Spans can be styled with a style attribute, but only text-related CSS that is shared with SVG will be handled.

Note

The available data in the formatter differ a bit depending on whether the tooltip is shared, split, or belongs to a single point. In a shared/split tooltip, all properties except x, which is common for all points, are kept in an array, this.points.

Available data are:

• this.percentage (when not shared) / this.points[i].percentage (when shared): Stacked series and pies only. The point’s percentage of the total.

• this.point (when not shared) / this.points[i].point (when shared): The point object. The point name, if defined, is available through this.point.name.

• this.points: In a shared tooltip, this is an array containing all other properties for each point.

• this.series (when not shared) / this.points[i].series (when shared): The series object. The series name is available through this.series.name.

• this.total (when not shared) / this.points[i].total (when shared): Stacked series only. The total value at this point’s x value.

• this.x: The x value. This property is the same regardless of the tooltip being shared or not.

• this.y (when not shared) / this.points[i].y (when shared): The y value.

Return type:

CallbackFunction or None

property header_format: str | None

The HTML of the tooltip header line. Defaults to None.

Note

Variables are enclosed by curly brackets. Available variables are point.key, series.name, series.color, and other members from the point and series objects.

The point.key variable contains the category name, x value or datetime string depending on the type of axis. For datetime axes, the point.key date format can be set using ToolTip.x_date_format().

Return type:

str or None

property header_shape: str | None

The name of a symbol to use for the border around the tooltip header.

Defaults to 'callout'.

Note

Applies only when Tooltip.split() is enabled.

Return type:

str or None

property hide_delay: int | None

The number of milliseconds to wait until the tooltip is hidden when mouse out from a point or chart.

Defaults to {constants.DEFAULT_TOOLTIP.get('hide_delay')}.

Return type:

int or None

property null_format: str | None

The HTML of the null point’s line in the tooltip. Defaults to None.

Note

Works analogously to Tooltip.point_format().

Return type:

str or None

property null_formatter: CallbackFunction | None

JavaScript callback function to format the text of the tooltip for visible null points.

Note

Works analogously to Tooltip.formatter().

Return type:

CallbackFunction or None

property outside: bool | None

If True, allows the tooltip to render outside of the chart’s SVG element box. Defaults to False, which causes the tooltip to be rendered inside the SVG element box which results in the tooltip being rendered inside the chart area.

Warning

When setting this property to False (the default) on small charts, the tooltip may either clip or overlap parts of the chart itself.

When True, a separate SVG element is created and overlaid on the page, allowing the tooltip to be aligned inside the page itself.

Note

If Chart.scrollable_plot_area() is True, then this will default to True. Otherwise, it will default to False.

Return type:

bool or None

property padding: int | float | Decimal | None

The padding inside the tooltip, expressed in pixels.

Defaults to 8.

Returns:

The padding to apply to the tooltip.

Return type:

int or None

property point_format: str | None

The HTML of the point’s line in the tooltip. Defaults to None.

Note

Variables are enclosed by curly brackets. Available variables are point.x, point.y, series.name, series.color, and other properties of the same form.

Furthermore, point.y can be extended by the Tooltip.value_prefix() and Tooltip.value_suffix() properties. This can also be overridden for each series, which makes it a good hook for displaying units.

Return type:

str or None

property point_formatter: CallbackFunction | None

JavaScript callback function to format the text of the tooltip’s point line.

Return type:

CallbackFunction or None

property positioner: CallbackFunction | None

A JavaScript callback function to place the tooltip in a custom position.

The callback receives three (JavaScript) parameters: labelWidth, labelHeight, and point, where point contains values for plotX and plotY telling where the reference point is in the plot area. Add chart.plotLeft and chart.plotTop to get the full coordinates.

To find the actual hovered Point instance, use this.chart.hoverPoint. For shared or split tooltips, all the hover points are available in this.chart.hoverPoints.

The return should be an object containing x and y values, for example: { x: 100, y: 100 }.

Return type:

CallbackFunction or None

property shadow: bool | ShadowOptions | None

Configuration for the shadow to apply to the tooltip. Defaults to True.

If False, no shadow is applied.

Returns:

The shadow configuration to apply or a boolean setting which hides the shadow or displays the default shadow.

Return type:

bool or ShadowOptions or None

property shape: str | None

The name of the symbol to use for the border around the tooltip. Defaults to 'callout'.

Accepts:

• 'rect'

• 'circle'

• 'callout'

Note

When Tooltip.split() is enabled, the shape is applied to all boxes except the header (which is controlled by Tooltip.header_shape()).

Returns:

The shape to use for the border around the tooltip.

Return type:

str or None

property shared: bool | None

When True, the entire plot area will capture mouse movement or touch events. Defaults to False.

Hint

If True, tooltip texts for series types with ordered data (not pie, scatter, flags etc) will be shown in a single bubble. This is recommended for single series charts and for tablet/mobile optimized charts.

See also Tooltip.split(), which is better suited for charts with many series, especially line-type series. The Tooltip.split() option takes precedence over Tooltip.shared().

Return type:

bool or None

property snap: int | float | Decimal | None

Proximity snap for graphs or single points. If None, it defaults to 10 pixels for mouse-powered devices and 25 for touch devices.

Defaults to None.

Note

In most cases, the whole plot area captures the mouse movement, and in these cases Tooltip.snap() doesn’t make sense. This applies when Tooltip.sticky_tracking() is True (default) and when the tooltip is shared or split.

Return type:

numeric or None

property split: bool | None

If True, splits the tooltip into one label per series, with the header close to the axis. Defaults to False.

Hint

This is recommended over shared tooltips for charts with multiple line series, generally making them easier to read.

Note

This option takes precedence over Tooltip.shared().

Return type:

bool or None

property stick_on_contact: bool | None

If True, prevents the tooltip from switching or closing when touched or pointed. Defaults to False.

Return type:

bool or None

property style: dict | str | None

CSS styling to apply to the tooltip.

Note

The tooltip can also be styled through the CSS class .highcharts-tooltip.

Warning

The default pointerEvents style makes the tooltip ignore mouse events, so in order to use clickable tooltips, this value must be set to auto.

Return type:

str or None

property use_html: bool | None

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

Defaults to False.

Hint

Using HTML allows advanced formatting like tables and images in the tooltip. It is also recommended for RTL languages as it works around RTL bugs in early Firefox.

Returns:

Flag indicating whether to render tooltips using HTML.

Return type:

bool or None

property value_decimals: int | None

How many decimals to show in each series’ y value. Defaults to None, which perserves all decimals.

Note

This is overridable in each series’ tooltip options object.

Return type:

int or None

property value_prefix: str | None

A string to prepend to each series’ y value. Overridable in each series’ tooltip options object. Defaults to None.

Return type:

str or None

property value_suffix: str | None

A string to append to each series’ y value. Overridable in each series’ tooltip options object. Defaults to None.

Return type:

str or None

property x_date_format: str | None

The format for the date in the tooltip header if the X axis is a datetime axis. Defaults to None, which produces a best-guess based on the smallest distance between points in the chart.

Return type:

str or None