Rendering tooltips and dataView with slots #838

kingyue737 · 2025-06-07T09:52:09Z

Summary

This PR proposes a new echarts-tooltip component. The component provides a formatter method that can be used with ECharts' tooltip.formatter option, allowing users to define tooltip content using Vue's template syntax.

The slot props are what users passed to the formatter method. The component teleports its slot content to a detached DOM element so that it does not exist in the html body.

Example

<script setup>
const tooltipRef = useTemplateRef('tooltip')
const option = shallowRef({
  tooltip: {
    trigger: "axis",
    formatter: (params) => {
      const name = params[0].name;
      const value = params[0].value;
      return tooltipRef.value?.formatter({ name, value });
    },
  },
});
</script>

<template>
  <v-chart :option="option" />
  <v-chart-tooltip ref="tooltip" v-slot="{ name, value }">
    <div>
      <span>{{ name }}</span>
      <span>{{ value }}</span>
    </div>
  </v-chart-tooltip>
</template>

For a practical example, see the Line Chart in the demo preview which features a Pie Chart as its tooltip.

Design Rationale

Why a Separate Component?

Users have multiple ways to define tooltip formatters, and a single ECharts instance may contain different types of charts. Adding a slot directly to VChart would make it difficult to handle these various use cases intuitively.

The showTip event doesn't provide sufficient information for implementing the approach suggested in Use Web Components without native class support detection #836 (comment).
We may need to support ECharts' asynchronous tooltip formatting:

const option = shallowRef({
  tooltip: {
    formatter: function (params, ticket, callback) {
      fetch(`url?id=${params.dataIndex}`).then((remoteData) => {
        callback(ticket, tooltipRef.value.formatter(remoteData));
      });
      return "Loading";
    },
  },
});

By making it a separate component, users can:

Decide how to compose it with their chart options
Benefit from tree-shaking when the component is unused
Have more control over params passed to the formatter function

@Justineo , do you have any other ideas for us to try?

vercel · 2025-06-07T09:52:14Z

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
vue-echarts	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Jul 7, 2025 5:42am

The limitation is that the tooltip detached from the current component tree, not provide/inject will try teleport next

Justineo · 2025-06-14T12:45:28Z

How about we go over the external API first?

Justineo · 2025-06-16T08:55:25Z

Users have multiple ways to define tooltip formatters, and a single ECharts instance may contain different types of charts. Adding a slot directly to VChart would make it difficult to handle these various use cases intuitively.

We could consider supporting multiple or dynamic slots—e.g., tooltip, tooltip-series-line, etc.—which could then map to the corresponding tooltip configurations at different levels. The idea would be to let slots fully override the tooltip formatters.

2. The showTip event doesn't provide sufficient information for implementing the approach suggested in Use Web Components without native class support detection #836 (comment).

From what I’ve seen, showTip is triggered whenever the pointer moves within the chart. Could you clarify what specific information is missing for our use case?

3. We may need to support ECharts' asynchronous tooltip formatting:

If we can implement tooltips as slots, we should be able to make the content reactive to async states or even render <Suspense>s.

The most tricky part I can think of is when and how to update the slot props when showTip is fired.

kingyue737 · 2025-06-16T14:44:00Z

We could consider supporting multiple or dynamic slots—e.g., tooltip, tooltip-series-line, etc.

I also considered this, but then I remembered that setOption can accept an array of options. So I decided to propose a separate component instead of designing a slot name convention, which might be a bit complicated 😂.

For multiple series of the same type but with different formatters, should we add a modifier like tooltip-series-line.[id]?

Most series support formatter for each single datum. But I think users can achieve similar functionality by using a series-level tooltip formatter and params.dataIndex. So we might not need to support it directly.

From what I’ve seen, showTip is triggered whenever the pointer moves within the chart. Could you clarify what specific information is missing for our use case?

I think the slotProps should be the params object from the tooltip.formatter callback if the slots belong to <VChart>. The payload of the showTip event is different from the params of the tooltip.formatter callback.

The most tricky part I can think of is when and how to update the slot props when showTip is fired.

We could override users' tooltip.formatter like this:

formatter(params) {
    // slotName.slotProps is a shallowRef
    slotName.slotProps.value = params

    return toHtml(slotContent)
}

The slot props would be updated whenever tooltip.formatter is called. So there’s no need to rely on the showTip event, just like here:

https://github.com/ecomfe/vue-echarts/pull/838/files#diff-bd261dd584a35b75c759fd268819ef41b77999d7e1fc0a703b7552b8449660daR11-R15

kingyue737 · 2025-06-21T07:38:38Z

How about use the property path of the tooltip.formatter as the slot name🤔?

global: option.tooltip.formatter

<template #tooltip />

axis: option.xAxis[1].tooltip.formatter

<template #tooltip:xAxis[1] />

series: option.series[3].tooltip.formatter

<template #tooltip:series[3] />

series.data / geo.regions: option.series[3].data[2].tooltip.formatter

<template #tooltip:series[3].data[2] />

media(baseOption): option.baseOption.tooltip.formatter

<template #tooltip:baseOption />

media: option[1].option.tooltip.formatter

<template #tooltip:[1].option />

kingyue737 · 2025-06-22T10:45:47Z

I feel the base functionality is mostly complete. However, it currently doesn't support dynamically changing slot names or adding/removing slots. With the current approach, implementing this might be tricky. For example:

<script setup>
// Work
const slotNames = ref(['tooltip', 'tooltip:series[0]'])

// Don't work
setTimeout(()=>{
  slotNames.value.push('tooltip:series[1]')
},1000)
</script>

<template>
  <v-chart>
    <template v-for="slotName in slotNames" #[slotName]={ params } >
        <!-- content -->
    </template>
  </v-chart>
</template>

Edit: Supported in the latest commit

Justineo

I think the design and implementation is pretty good now. Left a few small questions.

src/ECharts.ts

src/composables/tooltip.ts

src/utils.ts

README.md

README.zh-Hans.md

README.md

demo/data/line.js

* chore: fix warnings and errors in demo (#839) * chore: suppress warning in demo * chore: prevent multiple intializations of esbuild-wasm in demo HMR * feat: dynamically update the theme (#841) Co-authored-by: GU Yiling <justice360@gmail.com> * feat: add dataView slot * vibe docs --------- Co-authored-by: GU Yiling <justice360@gmail.com>

README.md

README.zh-Hans.md

Justineo · 2025-07-11T17:51:02Z

src/composables/slot.ts

+      if (isValidSlotName(key)) {
+        return true;
+      }
+      console.warn(`[vue-echarts] Invalid slot name: ${key}`);


We can import the warn util from vue as it will show component stack trace.

Justineo · 2025-07-11T17:59:27Z

src/composables/slot.ts

+      console.warn(`[vue-echarts] Invalid slot name: ${key}`);
+      return false;
+    });
+    if (newSlotNames.join() !== slotNames.join()) {


We'd better implement a isSameSet for this.

src/composables/slot.ts

Justineo

I have another option: how do we support [contentToOption](https://echarts.apache.org/zh/option.html#toolbox.feature.dataView.contentToOption)?

src/composables/slot.ts

Justineo · 2025-07-14T02:06:15Z

src/composables/slot.ts

+const SLOT_PATH_MAP = {
+  tooltip: ["tooltip", "formatter"],
+  dataView: ["toolbox", "feature", "dataView", "optionToContent"],
+};


as const

or we should make this config as SLOT_CONFIG which includes slot paths and propNames, etc.

Justineo · 2025-07-14T02:06:53Z

src/composables/slot.ts

+  tooltip: ["tooltip", "formatter"],
+  dataView: ["toolbox", "feature", "dataView", "optionToContent"],
+};
+type SlotPrefix = keyof typeof SLOT_PATH_MAP;


Suggested change

type SlotPrefix = keyof typeof SLOT_PATH_MAP;

type SlotPrefix = keyof typeof SLOT_PATH_MAP;

type SlotName = `${SlotPrefx}-${string}`;

Justineo · 2025-07-14T02:07:13Z

src/composables/slot.ts

+};
+type SlotPrefix = keyof typeof SLOT_PATH_MAP;
+
+function isValidSlotName(key: string) {


Suggested change

function isValidSlotName(key: string) {

function isValidSlotName(key: string): key is SlotName {

Justineo · 2025-07-14T02:12:32Z

src/composables/slot.ts

+          Object.entries(slots)
+            .filter(([key]) => isValidSlotName(key))
+            .map(([key, slot]) => {
+              const propName = key.startsWith("tooltip") ? "params" : "option";


This can be defined in slot configs instead of being hard-coded here.

Justineo · 2025-07-14T09:55:05Z

src/composables/slot.ts

+            .map(([key, slot]) => {
+              const propName = key.startsWith("tooltip") ? "params" : "option";
+              const slotContent = initialized[key]
+                ? slot?.({ [propName]: params[key] })


On a second thought, is the additional object wrapper necessary here? Can we just use slot?.(params[key]) here?

kingyue737 added 3 commits June 2, 2025 21:33

feat: experimental component rendered tooltip

34e04a7

revert slot in VChart

79a1d7d

feat: use tooltip composable

42c3569

feat: try createApp

978317e

vercel bot deployed to Preview June 7, 2025 13:18 View deployment

feat: use pie chart as tooltip

89743cf

vercel bot deployed to Preview June 8, 2025 14:31 View deployment

feat: switch to createVNode

585279e

The limitation is that the tooltip detached from the current component tree, not provide/inject will try teleport next

vercel bot deployed to Preview June 9, 2025 08:07 View deployment

feat: try component with teleport

c6bab0d

vercel bot deployed to Preview June 14, 2025 12:28 View deployment

wip

2072c3b

vercel bot deployed to Preview June 21, 2025 15:26 View deployment

add xAxis example

177e875

vercel bot deployed to Preview June 22, 2025 07:58 View deployment

refactor with shallowReactive

117df61

vercel bot deployed to Preview June 22, 2025 11:47 View deployment

Support dynamic slot

2dccfdb

vercel bot deployed to Preview June 23, 2025 15:28 View deployment

kingyue737 marked this pull request as ready for review June 23, 2025 15:39

fix: fill empty elements with object in array

322fda4

vercel bot deployed to Preview June 24, 2025 03:18 View deployment

Justineo reviewed Jun 25, 2025

View reviewed changes

src/ECharts.ts Outdated Show resolved Hide resolved

src/composables/tooltip.ts Outdated Show resolved Hide resolved

src/composables/tooltip.ts Outdated Show resolved Hide resolved

shallow copy option along the path

49ad09b

kingyue737 added 2 commits July 1, 2025 15:15

ssr friendly

9c2f431

vibe docs

0acb7b2

vercel bot deployed to Preview July 1, 2025 08:28 View deployment

graphite-app bot reviewed Jul 1, 2025

View reviewed changes

src/composables/tooltip.ts Outdated Show resolved Hide resolved

typo

3556afe

vercel bot deployed to Preview July 1, 2025 08:44 View deployment

Justineo requested changes Jul 3, 2025

View reviewed changes

Justineo changed the title ~~[Experiment] Component rendered tooltip~~ Rendering tooltips with slots Jul 3, 2025

update according to the review

6aa8d6d

vercel bot deployed to Preview July 4, 2025 08:39 View deployment

kingyue737 mentioned this pull request Jul 4, 2025

Rendering Data View with slots #844

Merged

vercel bot deployed to Preview July 4, 2025 09:02 View deployment

kingyue737 changed the title ~~Rendering tooltips with slots~~ Rendering tooltips and dataView with slots Jul 4, 2025

Merge branch '8.0' into tooltip-slot

c1b76d5

vercel bot deployed to Preview July 4, 2025 09:16 View deployment

Justineo requested changes Jul 7, 2025

View reviewed changes

README.md Outdated Show resolved Hide resolved

README.zh-Hans.md Outdated Show resolved Hide resolved

fix docs typo

429943a

vercel bot deployed to Preview July 7, 2025 05:42 View deployment

Justineo requested changes Jul 11, 2025

View reviewed changes

Justineo requested changes Jul 14, 2025

View reviewed changes

	type SlotPrefix = keyof typeof SLOT_PATH_MAP;
	type SlotPrefix = keyof typeof SLOT_PATH_MAP;
	type SlotName = `${SlotPrefx}-${string}`;

	function isValidSlotName(key: string) {
	function isValidSlotName(key: string): key is SlotName {

Rendering tooltips and dataView with slots #838

Are you sure you want to change the base?

Rendering tooltips and dataView with slots #838

Uh oh!

Conversation

kingyue737 commented Jun 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Example

Design Rationale

Why a Separate Component?

Uh oh!

vercel bot commented Jun 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Justineo commented Jun 14, 2025

Uh oh!

Justineo commented Jun 16, 2025

Uh oh!

kingyue737 commented Jun 16, 2025

Uh oh!

kingyue737 commented Jun 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

kingyue737 commented Jun 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Justineo left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Justineo Jul 11, 2025

Choose a reason for hiding this comment

Uh oh!

Justineo Jul 11, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Justineo left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Justineo Jul 14, 2025

Choose a reason for hiding this comment

Uh oh!

Justineo Jul 14, 2025

Choose a reason for hiding this comment

Uh oh!

Justineo Jul 14, 2025

Choose a reason for hiding this comment

Uh oh!

Justineo Jul 14, 2025

Choose a reason for hiding this comment

Uh oh!

Justineo Jul 14, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

kingyue737 commented Jun 7, 2025 •

edited

Loading

vercel bot commented Jun 7, 2025 •

edited

Loading

kingyue737 commented Jun 21, 2025 •

edited

Loading

kingyue737 commented Jun 22, 2025 •

edited

Loading