vega / vega-tooltip

Tooltip Plugin for Vega-Lite

Tooltip for Vega & Vega-Lite

A tooltip plugin for Vega and Vega-Lite visualizations. This plugin implements a custom tooltip handler for Vega that uses custom HTML tooltips instead of the HTML title attribute. Vega Tooltip is installed in the Vega Editor.

Features

• Renders nice tooltips for Vega and Vega-Lite charts
• Supports dark and light theme
• Renders object-valued tooltips as a table
• Supports special keys title (becomes the title of the tooltip) and image (used as the url for an embedded image)

Demo

http://vega.github.io/vega-tooltip/

Installing

We recommend using Vega-Embed, which already comes with this tooltip plugin.

NPM or Yarn

Use npm install vega-tooltip or yarn add vega-tooltip.

Using Vega-tooltip with a CDN

You can import vega-tooltip directly from jsDelivr. Replace [VERSION] with the version that you want to use.

<!-- Import Vega 5 & Vega-Lite 4 (does not have to be from CDN) -->
<script src="https://cdn.jsdelivr.net/npm/vega@5"></script>
<script src="https://cdn.jsdelivr.net/npm/vega-lite@4"></script>

<script src="https://cdn.jsdelivr.net/npm/vega-tooltip@[VERSION]"></script>

Usage and APIs

If you use Vega-Embed, you don't need to install Vega Tooltip! Vega Embed already comes with Vega Tooltip. You can however pass tooltip customizations.

vegaEmbed("#vis", spec, {tooltip: {theme: 'dark'}})
  .then(function(result) {
    // result.view contains the Vega view
  })
  .catch(console.error);

If you want to use a different version of the tooltip handler, you can override the default handler with the handler from Vega Tooltip (and you need to install it separately).

var handler = new vegaTooltip.Handler();
vegaEmbed("#vis", spec, {tooltip: handler.call})
  .then(function(result) {
    // result.view contains the Vega view
  })
  .catch(console.error);

See the API documentation for details.

Tutorials

1. Creating Your Tooltip
2. Customizing Your Tooltip

Run Instructions

1. In the project folder vega-tooltip, type command yarn to install dependencies.
2. Then, type yarn start. This will build the library and start a web server.
3. In your browser, navigate to http://localhost:8000/, where you can see various Vega-Lite and Vega visualizations with tooltip interaction.

Publishing

To make a release, run npm run release. The update the website with yarn deploy:gh.

vega-tooltip's Issues

Clean up tooltip content for binned fields

Related issue: https://github.com/vega/vega-lite-ui/issues/167

Write pro-tips about point and tooltip in documentation

Points, especially the enlarged ones, are not very easy to mouseover. You have to put mouse on the edge of a point to see the tooltip.

In this example I think it's better to use solid marks because they are easier to mouseover:

On the other hand, when marks overlap with each other, hover on edge actually works well. In the example below, hover on edge allows more marks to be picked up.

Allow highlighting certain fields in the tooltip

(migrated from https://github.com/vega/vega-lite-ui/issues/56)

Provide better default CSS

Tooltip examples doesn't work with D3 version 4

Use template for all time fields

This will let us correctly show quarters in tooltip.

Allow chaining methods to update config

For example

vl.tooltip(vgView, vlSpec[, options])
  .showAllFields(false)
  .colorTheme('dark');

• update doc

Alias for field name

It would be good if we can allow users to specify custom names for tooltip field names. I can pass in alias in the opt object through the API

Separate fields and their format in options

Currently, the complete structure of options look like this:

var options = {
  showFields: [{ // specify data fields to be shown in the tooltip
    field: ..., // field name in the dataset
    fieldTitle: ..., // (optional) field title the tooltip should display
    type: 'date' | 'number' | 'string',
    format: timeUnit | string specifier
  }],
  offset: { // x and y offset (in pixels) of the tooltip
    x: 10,
    y: 10
  },
  colorTheme: 'light' | 'dark' // specify a color theme the tooltip should use
}

For both Vega-Lite and Vega tooltips, if you want to specify the format of a field you have to put an object like {field:..., format: ...} into options.showFields[], and if you put in an object for one field you have to put in objects for all the other fields that you want to display in the tooltip (because the tooltip plugin right now assumes you only want to display the fields in the showFields array).

It's better to separate fields and their formats. If a user wants to specify a format, she specifies the format -- it doesn't affect the "which fields get displayed" decision.

var options = {
  showFields: ['field1', 'field2', 'field3'],
  fieldsConfig: {
    field1: {
      fieldTitle: ..., // (optional) field title the tooltip should display
      type: 'time' | 'number' | 'string',
      format: timeUnit | string specifier
    }
  },
  offset: { // x and y offset (in pixels) of the tooltip
    x: 10,
    y: 10
  },
  colorTheme: 'light' | 'dark' // specify a color theme the tooltip should use
}

Use vega-lite release version

Currently we are using vega-lite.min.js from the vega-lite github page. The vega-lite library (v1.0.8) we get via npm doesn't seem to have vl.timeUnit.format

Eliminate redundancy in method call

Right now, there are way too many redundant parts in vl.tooltip and vg.tooltip
that's why you have call everything twice.

This is not a good practice for a few reasons:

• Have to write the code twice for everything
• If you do something wrong, then you have to correct twice.
• It's entirely possible that you'll forget something in one of the place
• Hard for code review.

Look ahead: consider how this works with concatenation in Vega-Lite

Before we release 1.0, we should look ahead and understand how would this work with Vega-Lite's composition.

Integrate Vega Tooltip with other systems

Once we're done with everything else in 1.0 milestone.

We should integrate this with

• VLUI (hence Voyager and Polestar)

and maybe:

• Vega-Lite docs
• Vega-Editor

Correctly format time.

• take original vega-lite spec as input
• import datalib
• read timeUnit so we can set timeFormat
• read config.numberFormat so we use the correct numberFormat

Tooltip API should return an object that provides a destroy() method

When user calls the destroy() method, all event listeners on that view should be freed, so we don't have memory leak.

vl.tooltip(vgView, vlSpec).destroy()
vg.tooltip(vgView).destroy()

• Update doc

Package.json

• change license to BSD like other vega projects
• use pre 1.0 version
• add a build script

Mute "Cannot find field" warnings for certain composition

When vega-lite composite is ready, we should add logic to the getValue() function in vl-tooltip.js to mute the "[Tooltip] Cannot find field ... in data." warnings when the field is not in a composition.

vlTooltip default should be fieldDefs

Currently, for Vega-Lite visualizations, if no options is passed in the tooltip will show all top-level fields an item has.

But we should make it so that if no options is passed in, tooltip will only show fields that's used in the visualization, i.e. vl.spec.fieldDefs.

The spirit is that we want the user to specify as little as possible, but make the result look as good as possible.

Simply use css

Our css is simpler, better not use scss.

option to show only some fields in the tooltip

• two ways
  • add tooltip channel
  • For the tooltip API that gets call inside vg.embed or vg.parse.spec, add a third tooltip: FieldDef[] parameters to the API (1st=view, 2nd=spec) .
    • (Of course only field def that matches fields in the spec would be displayed.)
    • this mean you the spec must have all fields you want to show in tooltip already

Idea

• This plugin becomes vg.embedVegaLiteWithTooltip(..embedparams.., tooltips, callback)

Make the 10px offset configurable

Remove data from the repository

Instead of putting data in master, we can just copy required data from vega-datasets only for gh-pages branch.

Use JS?

Since the code is <100 lines and does not leverage any typings, using typescript simply complicates things.

For small codebase like this, using only JS will have the benefit that you have the ready-to-use file in the repo without requiring complicated deploy system.

Test if this plugin works well with mark overlayed on top of line and area.

Now we have overlay config for overlaying line and area.

Test if this plugin works well with mark overlayed on top of line and area.
https://github.com/vega/vega-lite/blob/master/examples/specs/overlay_line_short.json
https://github.com/vega/vega-lite/blob/master/examples/specs/overlay_area_short.json

Move tooltip to vl & vg namespaces?

Right now the APIs are
vlTooltip.linkToView(view, spec, opt)
and
vgTooltip.linkToView(view, opt).

Potentially we want to move the tooltip to vl and vg namespaces (?) Then the APIs will become
vl.tooltip(view, spec, opt)
and
vg.tooltip(view, opt)

Tutorial of using `options` to customize tooltip

Currently our documentation does not contain any code example of using options to customize the tooltip. We can use the ## Options section in customizing_your_tooltip.md to do this.

The tooltip APIs are now documented in this page. So the customizing_your_tooltip.md page should be more like tutorials.

T shown as Q when T doesn't have timeUnit

Example 1:

Example 2:

To fix this, we can read vega-lite default config timeFormat

API Option

Generally we want the user to write a field name without any underscore prefixes in options.fields and options.fieldConfigs. Then the tooltip plugin supplements the field names with underscore prefixes derived from vlSpec. We want to supplement the user-provided field names in order to match the field names returned by item.datum.

For aggregated fields, user should provide field name (e.g. 'yield'). Then tooltip supplements the field name with the aggregate operation (e.g. 'mean_yield'). This should match the field names in item.datum.

One exception is the aggregate operation count, where the field name is '*'. In this case the supplemented field name should be 'count' instead of 'count_*'

For fields with timeUnit, user should provide the field name (e.g. 'date'). Tooltip supplements the field name with the timeUnit (e.g. 'month_date').

For binned fields, user should provide field name (e.g. 'Acceleration'). Tooltip supplements the field name with 'bin_' (e.g. 'bin_Acceleration'). In runtime the tooltip plugin calculates the range of the bin field (issue #29).

If user don't provide options.fields, tooltip supplements options.fields with all fieldDefs in the vlSpec, using the underscore prefixes described above.

Should we name this vega-tooltip as it supports both Vega and Vega-Lite?

I'm voting for vega-tooltip?

@domoritz @arvind @jheer – any opinion?

Customize anchor point

Right now the anchor point on the tooltip is top left, so the tooltip is always at the bottom right of the mouse. It would be nice to allow users to overwrite the anchor point through options. This would make tooltip positioning more flexible.

Related: options.offset.x and options.offset.y describes the x and y distances between the mouse and the tooltip anchor point. Changing the anchor point may create some confusion around offset. For example, if anchorPoint = 'left center', should offset.x be 10px or -10px?

Make `removeOriginalTemporalField` a boolean?

From PR #64

Customize tooltip shape?

Right now tooltip is a rectangle with 3px rounded corners. It would be nice to express more shapes (e.g. bubble?)

Create an API document for people to review & comment

Mouse hover color change

Hover colors would be a nice complement to tooltip, especially when data is dense. With hover color I can actually see which mark is I'm actually looking at.

double-check field order in tooltip

Remove `string` as an option for `formatType`

Currently, in options.fields.formatType we allow three options: number, time, and string.

We want to remove string as an option because

• string don't really have format specifier
• When Vega parses data, the options are number, boolean or date (string is the default and thus not an option) https://github.com/vega/vega/wiki/Data

Separate into multiple files

1. VL / VG

For Vega users, they don't need to code for vega-lite.

For Vega-Lite users, compile a version that provide all the necessary methods within one import.

2. Modularize?

Use Vega-Lite layering to support tooltip on line charts and area charts

Currently tooltip for line chart does not report correct data because data is bound to path, not to points. In the screenshot below, price should be a number around 200 and date should be in human-readable format (that's another issue).

Add delay in options

options.delay can be true or false or a number. If it's false, there will be no delay. If it's true, tooltip will be delayed for 200 ms. If it's a number, tooltip will be delayed for the number of milliseconds provided.

Simpler API

• result/view object from vega embed

Option to pick light or dark theme for tooltip

It would be nice to have options.theme that can be light (default) or dark

It would be nice if tooltip can show the same unit as axis

type: date, time, or utc?

Currently, if a field in options is a temporal field, the type is date. For example:

var stackedBarOpts = {
    showFields: [
      {
        field: "month_date",
        fieldTitle: "Month",
        type: "date", // right now we use "date", but it can be "time" or "utc"
        format: "month"
      },
      {
        field: "weather",
        fieldTitle: "Weather"
      },
      {
        field: "count",
        fieldTitle: "Count"
      }
    ]
  };

Vega axes formatType uses "time" and "utc"

Test supplementOptions(options, vlSpec)

This function does not involve interaction.

The inputs and output of this function can have a lot of variations.

/**
  * (Vega-Lite only) Supplement options with vlSpec
  *
  * @param options - user-provided options
  * @param vlSpec - vega-lite spec
  * @return the vlSpec-supplemented options object
  * 
  * if options.showAllFields is true or undefined, vlSpec will supplement
  * options.fields with all fields in the spec
  * if options.showAllFields is false, vlSpec will only supplement existing fields
  * in options.fields
  */
  function supplementOptions(options, vlSpec)

Vega fields that should be hidden by default in tooltip

Consider if we can design this in a way that's useful for Vega too.

A comment from @arvind – at its simplest form, this plugin is useful for Vega too.

Maybe we can design make this more generic, while optionallly supporting some vega-lite specific features?

Use tabs to simplify code examples in documentation

Our documentations contain code examples for Vega-Lite and Vega. Currently they look like this:

Can we make the doc look simpler/shorter/cleaner by using tabs? Here's an example from MSDN:

Don't refer to github pages data, but set up a data copy script like in Vega-Lite

Allow specifying number/time format for a field in Vega

By default, we use auto format for Vega.

In future version, we can have a option in the API for specifying custom format.

Provide .on() event listeners

For example, vega-lite-ui has a need to log when tooltip appears and disappears.

vl.tooltip(vgView, vlSpec)
  .on('appear', function() { /* callback */})
  .on('disappear', function() { /* callback */})

• update doc