Vega-Lite Tooltips: From Basics to Stunning HTML Experiences

Tooltips deliver extra context without overwhelming your charts. Vega-Lite makes them easy to configure, and with the Vega Tooltip plugin you can go from auto-generated tooltips to immersive, branded experiences. This guide walks through the essentials—turning on tooltips, choosing exactly what appears, formatting values, and finishing with a gorgeous HTML design.

Quick Start: Turn Tooltips On

The fastest way to enable a tooltip is to set the mark's tooltip property to true. Vega-Lite will include every field referenced in your encoding.

{
  "data": { "values": [
    { "product": "Laptops", "sales": 128000 },
    { "product": "Monitors", "sales": 86000 },
    { "product": "Keyboards", "sales": 54000 },
    { "product": "Headsets", "sales": 38000 }
  ]},
  "mark": { "type": "bar", "tooltip": true },
  "encoding": {
    "x": { "field": "product", "type": "nominal" },
    "y": { "field": "sales", "type": "quantitative" }
  }
}

This approach mirrors the more explicit "tooltip": { "content": "encoding" }, which instructs Vega-Lite to reuse your encoding fields inside the tooltip.

Show the Entire Data Row

Need every attribute from the underlying data point, not just what's encoded? Pass "content": "data" so the tooltip surfaces the entire row.

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

This option is perfect when your mark encodes only a subset of fields but the user needs richer context on hover.

Curate the Fields with the Tooltip Channel

Use the tooltip encoding channel to decide exactly what appears. Map a single field or an array of field definitions.

{
  "encoding": {
    "tooltip": {
      "field": "sales",
      "type": "quantitative",
      "title": "Revenue",
      "format": "$,.0f"
    }
  }
}

To mix categorical, quantitative, and formatted metrics together, supply an array:

{
  "encoding": {
    "tooltip": [
      { "field": "product", "type": "nominal", "title": "Product" },
      { "field": "region", "type": "nominal", "title": "Primary region" },
      { "field": "sales", "type": "quantitative", "title": "Revenue", "format": "$,.0f" },
      { "field": "growth", "type": "quantitative", "title": "YoY growth", "format": "+.1%" }
    ]
  }
}

Formatting Tips

Set format (or formatType) to align with your number or date formatting needs.
Use title to create reader-friendly labels that differ from your field names.
Combine calculations or transforms upstream—calculate, aggregate, or timeUnit transforms can prepare tooltip-friendly values without cluttering your main encoding.

Design Bespoke HTML Tooltips with the Plugin

When you need something beyond tables of field/value pairs, reach for the Vega Tooltip plugin (opens in a new tab). By passing tooltip options to vegaEmbed (via the VegaLiteChart component here), you can return fully custom HTML.

const htmlTooltipOptions = {
  theme: "dark",
  sanitize: value => value,
  formatTooltip: value => {
    const datum = value?.datum ?? value;
    // ...return handcrafted HTML string
  }
};

Key ideas for beautiful tooltips:

Leverage formatTooltip: The function receives the current tooltip value, so you can build a mini layout with headings, accents, and helper text.
Override sanitize carefully: Setting it to the identity function unlocks custom HTML. Do this only when you fully control the values you inject.
Style inline or with classes: Inline styles keep examples self-contained, while a custom stylesheet can ensure brand consistency across charts.

Enrich Tooltips with a Lookup Transform

Pair sparse fact tables with descriptive metadata using lookup. The tooltip gains storytelling power, and you can use the extra fields for color or size encodings too.

Without lookup

With lookup

The lookup-enhanced tooltip now includes human-friendly category descriptions while also recoloring the bars.

Disable Tooltips When Needed

Tooltips can get in the way for touch interfaces or dashboards where hover isn't available. Disable them per mark or globally.

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

Or remove the tooltip channel entirely:

{
  "encoding": { "tooltip": null }
}

To disable tooltips for the whole specification, set "config": { "mark": { "tooltip": null } }.

Frequently Asked Questions

How do I choose which fields appear?

Use the tooltip encoding channel to list the fields, order, titles, and formats you want. Arrays let you mix quantitative, temporal, and categorical information in a single hover card.

Can I display images or media?

Yes. When using the Vega Tooltip plugin, set a field named image in your tooltip data, or craft custom HTML that references image URLs. Remember to host assets over HTTPS for production.

What's the best way to create HTML tooltips?

Pass tooltip options to vegaEmbed with a custom formatTooltip function. From there you can return semantic HTML, inline styles, and icons—anything valid in a <div> element.

How do I keep tooltips accessible?

Provide descriptive titles, avoid color-only encodings, and consider adding visible labels or click interactions for touch devices. For complex dashboards, supplement tooltips with on-chart annotations.

For more detail and advanced patterns, explore the official Vega Tooltip plugin documentation (opens in a new tab).

Spec Types