Tooltip Customization

You can customize the content of tooltips for the layer by using the parameter tooltips of geom functions.

The following functions set lines, define formatting of the tooltip, its location and width:

    .format(field, format)

Tooltip Variable List: layer_tooltips(variables=['var_name_1', ..., 'var_name_N'])

The variables parameter defines a list of variable names, which values will be placed line by line in the general tooltip. If formatting is specified for a variable from this list (with the format() function), it will be applied. Otherwise, the default formatting is used. Additional tooltip lines can be specified using the line() functions.

Formatting Tooltip Fields: layer_tooltips().format(field, format)

Defines the format for displaying the value. The format will be applied to the mapped value in the default tooltip or to the corresponding value specified in the line template.


  • field (string): The name of the variable/aesthetics. The field name begins with ^ for aesthetics. You can specify variable names without a prefix, but the @ prefix can be also used. It’s possible to set a format for all positional aesthetics: ^X (all positional x) and ^Y (all positional y). For example:

    • field = '^Y' - for all positional y;

    • field = '^y' - for y aesthetic;

    • field = 'y' - for variable with the name “y”.

  • format (string): The format to apply to the field. The format contains a number format ('1.f') or a string template ('{.1f}'). The numeric format for non-numeric value will be ignored. The string template contains “replacement fields” surrounded by curly braces {}. Any code that is not in the braces is considered literal text, and it will be copied unchanged to the result string. If you need to include a brace character into the literal text, it can be escaped by doubling: {{ and }}. For example:

    • .format('^color', '.1f') -> "17.0";

    • .format('cty', '{.2f} (mpg)')) -> "17.00 (mpg)";

    • .format('^color', '{{{.2f}}}') -> "{17.00}";

    • .format('model', '{} {{text}}') -> "mustang {text}".

The string template in the format parameter will allow changing lines for the default tooltip without line specifying.

Variable’s and aesthetic’s formats are not interchangeable, for example, var format will not be applied to aes mapped to this variable.

Customizing Tooltip Lines: layer_tooltips().line(template)

Specifies the string template to use in a general tooltip. If you add line(), it overrides the default tooltip.

Variables and aesthetics can be accessed via a special syntax:

  • ^color for aesthetic;

  • @year for variable;

  • @{number of cylinders} for a variable with spaces or non-word characters in the name;

  • @..count.. for statistics variables.

A ‘^’ symbol can be escaped with a backslash; a brace character in the literal text - by doubling:

  • .line('text') -> "text";

  • .line('\^text') -> "^text";

  • .line('{{text}}') -> "{text}";

  • .line('@model') -> "mustang";

  • .line('{{@model}}') -> "{mustang}".

Labels Configuration

The default tooltip has a label before the value usually containing the name of the mapped variable. It has its own behavior similar to a blank label for an axis aesthetics. This default label can be set in the template by using a pair of symbols @|. You can override the label by specifying a string value before | symbol.

Within the tooltip line, you can align a label to left. The string formed by a template can be aligned to right. If you do not specify a label, the string will be centered in the tooltip. For example:

  • line('^color'): no label, value is centered;

  • line('|^color'): label is empty, value is right-aligned;

  • line('@|^color'): default label is used, value is right-aligned;

  • line('my label|^color'): label is specified, value is right-aligned.

Tooltip Anchor: layer_tooltips().anchor(position)

Specifies a fixed position for a general tooltip.

The anchor() function accepts the following values:

  • ‘top_right’

  • ‘top_center’

  • ‘top_left’

  • ‘bottom_right’

  • ‘bottom_center’

  • ‘bottom_left’

  • ‘middle_right’

  • ‘middle_center’

  • ‘middle_left’

Minimum Width of a General Tooltip: layer_tooltips().min_width(value)

Specifies a minimum width of a general tooltip in pixels.

Tooltip Color: layer_tooltips().color(value)

Specifies a color of a general tooltip.


 1import pandas as pd
 3from lets_plot import *
 6df = pd.read_csv('')
 8ggplot(df) + geom_point(aes(x='displ', y='cty', fill='drv', size='hwy'), shape=21, color='black', \
 9                        tooltips=layer_tooltips().format('cty', '.1f')
10                                                 .format('hwy', '.1f')
11                                                 .format('drv', '{}wd')
12                                                 .line('@manufacturer @model')
13                                                 .line('cty/hwy|@cty/@hwy')
14                                                 .line('@|@class')
15                                                 .line('drive train|@drv')
16                                                 .line('@|@year'))