Tooltips

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

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

tooltips(variables, formats, title, anchor, minWidth, hide) {
  LayerTooltipsContext -> line(template)
}

Tooltip `variables` parameter (optional)

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.

This is useful for configuring the tooltip content, instead of using the line() method to configure each line of the tooltip.

Set the list of variables to place them in a multiline tooltip with the default formatting:

val mpgDf =
    DataFrame.readCSV("https://raw.githubusercontent.com/JetBrains/lets-plot-kotlin/master/docs/examples/data/mpg.csv")
mpgDf.head()

untitled	manufacturer	model	displ	year	cyl	trans	drv	cty	hwy	fl	class
1	audi	a4	18	1999	4	auto$l5$	f	18	29	p	compact
2	audi	a4	18	1999	4	manual$m5$	f	21	29	p	compact
3	audi	a4	2	2008	4	manual$m6$	f	20	31	p	compact
4	audi	a4	2	2008	4	auto$av$	f	21	30	p	compact
5	audi	a4	28	1999	6	auto$l5$	f	16	26	p	compact

mpgDf.plot {
    points {
        x(displ)
        y(cty)
        fillColor(drv)
        size(hwy)

        symbol = Symbol.CIRCLE_FILLED
        color = Color.GREY

        tooltips(manufacturer, model, `class`, drv)
    }
}

Tooltip `formats` parameter

Parameter formats 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. 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 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 in the literal text, it can be escaped by doubling: {}. For example:

cty to ".1f")-> "17.0"
cty to "{.2f} (mpg)"))-> "17.00 (mpg)"
cty to "{{{.2f}}}")-> "{17.00}"
model to "{} {{text}}")-> "mustang {text}"

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

line("text")-> "text"
line("{{text}}")-> "{text}"
line("${value(model)}")-> "mustang"
line("${model.tooltipValue()}")-> "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 the 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.

Adds a title template to the tooltip.

The specification rules are the same as for the line() function.

A long title can be split into multiple lines using \n as a text separator.

Tooltip anchor

Specifies a fixed position for a general tooltip.

The Anchor object accepts the following values:

TOP_RIGHT
TOP_CENTER
TOP_LEFT
BOTTOM_RIGHT
BOTTOM_CENTER
BOTTOM_LEFT
MIDDLE_RIGHT
MIDDLE_CENTER
MIDDLE_LEFT

Specifies minimum width of a general tooltip in pixels.

mpgDf.plot {
    points {
        x(displ)
        y(cty)
        fillColor(drv)
        size(hwy)

        symbol = Symbol.CIRCLE_FILLED
        color = Color.GREY

        tooltips {
            line("${manufacturer.tooltipValue()} ${model.tooltipValue()}")
            line("cty/hwy|${cty.tooltipValue(".1f")}/${hwy.tooltipValue(".1f")}")
            line(`class`)
            line("drive train", drv.tooltipValue("{}wd"))
            line(year, format = "d")
        }
    }

    layout {
        style {
            legend.position = LegendPosition.None
        }
    }
}

Change format for the default tooltip:

mpgDf.plot {
    points {
        x(displ)
        y(cty)
        fillColor(drv)
        size(hwy)

        symbol = Symbol.CIRCLE_FILLED
        color = Color.GREY

        tooltips {
            varLine("hwy", "{.2f} (mpg)")
        }
    }
}

Place a general tooltip at the top center and define its minimum width:

mpgDf.plot {
    points {
        x(displ)
        y(cty)
        fillColor(drv)
        size(hwy)

        symbol = Symbol.CIRCLE_FILLED
        color = Color.GREY

        tooltips(anchor = Anchor.TOP_CENTER, minWidth = 200.0) {
            line("${manufacturer.tooltipValue()} ${model.tooltipValue()}")
            line("cty/hwy|${cty.tooltipValue(".1f")}/${hwy.tooltipValue(".1f")}")
            line(`class`)
            line("drive train", drv.tooltipValue("{}wd"))
            line(year, format = "d")
        }
    }
}

Move the tooltips to the top right corner:

val irisDf = DataFrame.readCSV(
    "https://raw.githubusercontent.com/JetBrains/lets-plot-kotlin/master/docs/examples/data/iris.csv",
    parserOptions = ParserOptions(Locale.ENGLISH)
)
irisDf.head()

sepal_length	sepal_width	petal_length	petal_width	species
5.1	3.5	1.4	0.2	setosa
4.9	3	1.4	0.2	setosa
4.7	3.2	1.3	0.2	setosa
4.6	3.1	1.5	0.2	setosa
5	3.6	1.4	0.2	setosa

irisDf.groupBy { species }.plot {
    densityPlot(sepal_length) {
        tooltips(anchor = Anchor.TOP_RIGHT) {
            line(species.tooltipValue())
            line("length", Stat.x.tooltipValue())
            line("density", Stat.density.tooltipValue())
        }
    }
    layout {
        style { legend.position = LegendPosition.None }
    }
}

Side tooltips configuration

In Kandy, certain aesthetics by default are represented by a so-called "side tooltip" — a small tipped box containing just a single numeric value.

You can override these defaults using the line() function. Configuring a "line" in a general multi-line tooltip disables side tooltip for the correspondent aesthetic.

mpgDf.plot {
    boxplot(`class`, hwy) {
        boxes {
            tooltips {
                line("y min/max", "${Stat.min.tooltipValue()}, ${Stat.max.tooltipValue()}")
                line("lower/upper", "${Stat.lower.tooltipValue()}, ${Stat.upper.tooltipValue()}")
                line("middle", Stat.middle.tooltipValue())
            }
        }
    }
}

Place the tooltip at the top center:

mpgDf.plot {
    boxplot(`class`, hwy) {
        boxes {
            tooltips(anchor = Anchor.TOP_CENTER) {
                line("middle", Stat.middle.tooltipValue(".2f"))
                line("lower/upper", "${Stat.lower.tooltipValue("d")}, ${Stat.upper.tooltipValue("d")}")
                line("y min/max", "${Stat.min.tooltipValue("d")}, ${Stat.max.tooltipValue("d")}")
            }
        }
    }
}

Hiding tooltips

Set tooltips(true) to hide tooltips from the layer.

To hide axis tooltips, you can set "blank" parameters of the style() function.

mpgDf.plot {
    points {
        x(displ)
        y(cty)
        fillColor(drv)
        size(hwy)

        symbol = Symbol.CIRCLE_FILLED
        color = Color.GREY

        tooltips(enable = false)
    }
}

Splitting text using `\n`

mpgDf.plot {
    points {
        x(displ)
        y(cty)
        fillColor(drv)
        size(hwy)

        symbol = Symbol.CIRCLE_FILLED
        color = Color.GREY

        tooltips {
            line("${value(manufacturer)} \n${value(model)}")
            line(`class`)
            line(year)
        }
    }
}

Adding a title

mpgDf.plot {
    points {
        x(displ)
        y(cty)
        fillColor(drv)
        size(hwy)

        symbol = Symbol.CIRCLE_FILLED
        color = Color.GREY

        tooltips(title = "${value(manufacturer)} ${value(model)}") {}
    }
    layout {
        style { legend.position = LegendPosition.None }
    }
}

mpgDf.plot {
    points {
        x(displ)
        y(cty)
        fillColor(drv)
        size(hwy)

        symbol = Symbol.CIRCLE_FILLED
        color = Color.GREY

        tooltips(`class`, year, title = "${value(manufacturer)} ${value(model)}") {}
    }
    layout {
        style { legend.position = LegendPosition.None }
    }
}

mpgDf.plot {
    points {
        x(displ)
        y(cty)
        fillColor(drv)
        size(hwy)

        symbol = Symbol.CIRCLE_FILLED
        color = Color.GREY

        tooltips(title = "Car info: \n${value(manufacturer)} ${value(model)}") {
            line(`class`)
            line("drive train", value(drv))
            line(year)
        }
    }
    layout {
        style { legend.position = LegendPosition.None }
    }
}

val dataset = dataFrameOf("x" to listOf(0.0, 1.0), "y" to listOf(0.0, 1.0))

plot(dataset) {
    tiles {
        x("x")
        y("y")
        fillColor = Color.GREY

        tooltips(title = "Tooltip title") {
            line("label|value")
        }
    }
}

plot(dataset) {
    tiles {
        x("x")
        y("y")
        fillColor = Color.GREY

        tooltips(title = "Tooltip title") {
            line("label|value")
        }
    }

    layout.style {
        layerTooltips {
            background {
                borderLineColor = Color.hex("#225e32")
                fillColor = Color.hex("#238b45")
                borderLineWidth = 2.0
            }
            text {
                color = Color.hex("#bae4b3")
            }
            title {
                color = Color.hex("#edf8e9")
            }
        }
        xAxis.tooltip.text {
            color = Color.GREEN
        }
    }
}

Last modified: 14 February 2024

kandy 0.8.0-RC1 Help

Tooltips

Tooltip `variables` parameter (optional)

Tooltip `formats` parameter

Customizing tooltip lines

Labels configuration

Tooltip Title Parameter

Tooltip anchor

Minimum width of general tooltip

Side tooltips configuration

Hiding tooltips

Tooltip Title

Splitting text using `\n`

Adding a title

Tooltip Style

untitled	manufacturer	model	displ	year	cyl	trans	drv	cty	hwy	fl	class
1	audi	a4	18	1999	4	auto\(l5\)	f	18	29	p	compact
2	audi	a4	18	1999	4	manual\(m5\)	f	21	29	p	compact
3	audi	a4	2	2008	4	manual\(m6\)	f	20	31	p	compact
4	audi	a4	2	2008	4	auto\(av\)	f	21	30	p	compact
5	audi	a4	28	1999	6	auto\(l5\)	f	16	26	p	compact

Tooltips

Tooltip variables parameter (optional)

Tooltip formats parameter

Customizing tooltip lines

Labels configuration

Tooltip Title Parameter

Tooltip anchor

Minimum width of general tooltip

Side tooltips configuration

Hiding tooltips

Tooltip Title

Splitting text using \n

Adding a title

Tooltip Style

Tooltip `variables` parameter (optional)

Tooltip `formats` parameter

Splitting text using `\n`