How Can I Add and Customize Tooltips in Vega-Lite?

Tooltips are a fantastic way to provide more detail about the data points in your visualization without cluttering the chart. In Vega-Lite, you can add and customize tooltips in several ways. Let's dive in and explore the different methods!

Tooltip Based on Encoding

Want to quickly add tooltips that show all the fields you've specified in your encoding? Simply set the tooltip property of the mark definition to true.

{
  "data": {
    "values": [
      { "a": "A", "b": 28 },
      { "a": "B", "b": 55 },
      { "a": "C", "b": 43 },
      { "a": "D", "b": 91 },
      { "a": "E", "b": 81 },
      { "a": "F", "b": 53 },
      { "a": "G", "b": 19 },
      { "a": "H", "b": 87 },
      { "a": "I", "b": 52 }
    ]
  },
  "mark": {"type": "bar", "tooltip": true},
  "encoding": {
    "x": { "field": "a", "type": "nominal" },
    "y": { "field": "b", "type": "quantitative" }
  }
}

Note: This is equivalent to setting:

{
  "mark": {"type": "bar", "tooltip": {"content": "encoding"}},
}

Tooltip Based on Underlying Data Point

To show all fields from the actual data point, set the mark's tooltip to {"content": "data"}.

{
  "mark": {"type": "point", "tooltip": {"content": "data"}},
}

Tooltip Channel

Want to specify exactly what appears in the tooltip? Use the tooltip channel to map it to a data field.

{
  "mark": "bar",
  "encoding": {
    "x": {"field": "a", "type": "nominal"},
    "y": {"field": "b", "type": "quantitative"},
    "tooltip": {"field": "b", "type": "quantitative"}
  }
}

To show multiple fields, provide an array of field definitions:

{
  "mark": "bar",
  "encoding": {
    "x": {"field": "a", "type": "nominal"},
    "y": {"field": "b", "type": "quantitative"},
    "tooltip": [
      {"field": "a", "type": "nominal"},
      {"field": "b", "type": "quantitative"}
    ]
  }
}

To give the fields in the tooltip a label that is different from the field name, set the title parameter.

{
  "mark": "bar",
  "encoding": {
    "x": {"field": "a", "type": "nominal"},
    "y": {"field": "b", "type": "quantitative"},
    "tooltip": [
      {"field": "a", "type": "nominal", "title": "Field A"},
      {"field": "b", "type": "quantitative", "title": "Field B"}
    ]
  }
}

Tooltip Image

Want to get fancy and show images in your tooltips? Use the Vega Tooltip plugin and map the special field name image.

{
  "view": {"stroke": null},
  "data": {
    "values": [
      {"image": "data/ffox.png"},
      {"image": "data/gimp.png"},
      {"image": "data/7zip.png"}
    ]
  },
  "mark": "text",
  "encoding": {
    "text": {"field": "image"},
    "y": {"field": "image", "axis": null},
    "tooltip": [{"field": "image"}]
  }
}

Disable Tooltips

Not a fan of tooltips? You can disable them for a particular single view by setting tooltip to null.

{
  "mark": {"type": "point", "tooltip": null}
}

Alternatively, disable it in the encoding:

{
  "mark": ...,
  "encoding": {"tooltip": null}
}

To disable tooltips globally:

"config": {"mark": {"tooltip": null}}

Vega Tooltip Plugin

For more advanced and customizable tooltips, you can use the Vega Tooltip plugin (opens in a new tab). This plugin allows you to create rich HTML tooltips. Make sure to include the plugin in your project to get access to these features.

Example with Vega Tooltip Plugin

FAQ

1. How do I customize the fields shown in a tooltip?

See the Tooltip Channel part, you can customize the fields by using the tooltip channel in your encoding. You can specify which fields to include and their order.

2. Can I show images in the tooltips?

See the Tooltip Image part, by using the Vega Tooltip plugin and mapping the special image field, you can display images in the tooltips.

3. How can I disable tooltips for specific marks?

Check this part, set the tooltip property to null in the mark definition or in the encoding to disable tooltips for specific marks.

4. Is it possible to use HTML for tooltip customization?

Yes, the Vega Tooltip plugin allows you to create custom HTML tooltips, providing you with greater flexibility in design.

For more detailed information, check out the Vega Tooltip plugin documentation (opens in a new tab).