TuiEcharts

💎Advanced

🧊Enhanced

⭐Star

TuiEcharts is the "Intelligent Rendering Shell" within the TechUI chart system.

It is not just a traditional secondary wrapper for ECharts, but an intelligent Functional Shell. While perfectly preserving the native configuration capabilities of ECharts, it takes over the tedious instance initialization and lifecycle management, greatly simplifying the development process.

More importantly, it injects a unique "SVG Depth Engine" into standard ECharts instances. By working in synergy with Tui3DPanel, it can parse SVG nodes output by ECharts in real-time and extract features, thereby achieving pseudo-3D thickness and lighting rendering in a standard DOM environment, giving flat charts unprecedented spatial expressiveness.

TuiEcharts is one of the 7 advanced components in the library and requires authorization to use.

Core Features

• SVG 3D Depth Simulation: Creates a sense of physical thickness for ordinary bar and pie charts through unique node cloning and projection technologies.
• High-Performance Rendering: Supports switching between canvas and svg modes, with DOM node optimization for 3D scenes.
• Smart Resize: Built-in ResizeObserver supporting component-level (self) or global-level (global) adaptation strategies.
• Rolling Number Integration: Supports number scrolling synchronized with chart animations (see Demo).

3D Principle

Echarts 3D transformation is a TechUI original solution: This is the most "magical" feature of TuiEcharts. Standard ECharts is flat in non-GL mode. To achieve 3D effects, the component adopts a "Mark-Extract-Project" rendering pipeline.

Rendering Mechanism

To enable 3D effects, the following two conditions must be met:

1. External Container: The chart must be wrapped in a <Tui3DPanel> component, which provides CSS transform perspective transformations (such as rotateX, rotateY).
2. Rendering Mode: The renderer property of TuiEcharts must be set to 'svg'.

Thickness Simulation Principle (Shadow Layer)

The component traverses the SVG DOM tree generated by ECharts. Since we cannot directly tell ECharts to "add thickness to this bar," we use a Feature Value Matching method.

The component detects the stroke-width (i.e., borderWidth in ECharts config) in SVG paths. If this value, when converted to a string, contains the specific sequence "358", the component determines that the element needs to be "3D-fied".

It performs the following operations:

• Clone: Copies the SVG node to generate an independent "Shadow Layer".
• Offset: Calculates the offset based on the Tui3DPanel angle.
• Blur: Applies a CSS Filter to realize volumetric shadows.

The "358" Cultural Easter Egg

Why 358? This number is not generated randomly but originates from Taoist culture:

• 3: Represents "San Cai" (Heaven, Earth, Man);
• 5: Represents "Wu Xing" (Five Elements: Metal, Wood, Water, Fire, Earth);
• 8: Represents "Ba Gua" (The Eight Trigrams: Qian, Dui, Li, Zhen, Xun, Kan, Gen, Kun).

Setting borderWidth to 0.0000358 does not produce a visible border visually (it is extremely thin), but serves as the "Key" to the 3D world.

Configuration Example

Inject the key in ECharts' itemStyle:

// Configure in series data
itemStyle: {
    borderRadius: 3,
    borderColor: "white",
    opacity: 1,
    // [Key] Inject the 358 key to trigger TuiEcharts' 3D shadow layer generation
    borderWidth: 0.0000358,
}

API Reference

Props

Property Name	Type	Default	Description
chartOption	Object	(Required)	Standard configuration object for ECharts.
width	Number/String	-	Container width.
height	Number/String	-	Container height.
ready v0.0.5+	Boolean	false	Rendering Control Signal. The component initializes/renders only when set to true. Often used for waiting for asynchronous data.
renderer	String	'canvas'	Rendering mode. Note: Must be set to 'svg' to enable 3D shadow effects.
initOptions	Object	{}	Additional parameters for ECharts initialization (e.g., devicePixelRatio, locale).
initT3DShadow	Boolean	false	Whether to enable SVG 3D shadow calculation logic.
t3DShadowUpdate	String	'finished'	Timing of 3D shadow generation. Options: 'rendered' (during rendering) or 'finished' (after animation ends).
dataOpacity	Number	-	Data opacity of the 3D shadow layer.
dataBlur	Number	-	Blur radius (px) of the 3D shadow layer.
resizeObserver	String	'global'	Adaptation strategy. 'self' (component itself), 'global' (window), 'none' (disabled).
loading	Boolean	null	Loading state (supports v-model:loading).

Removed Props

• Obsolete Props removed in v0.0.5: initDelay, initHold;

Events

Event Name	Description
chartClick / chartDblClick	Triggered when a chart element is clicked / double-clicked.
chartMouseDown / chartMouseUp	Triggered when the mouse is pressed / released.
chartMouseOver	Triggered when the mouse hovers.
chartGlobalOut	Triggered when the mouse leaves the chart area.
chartInit	Triggered when instance initialization is complete.
chartReady	Triggered when the chart completes its first render (including animation).
chartRendered	Triggered every time a render action occurs.
chartFinished	Triggered when rendering actions completely stop (animations end).
update:loading	Loading state update event.

Methods

Callable via ref:

• resize(): Force repaint.
• setOption(option, ...): Update configuration.
• getChart(): Get the ECharts instance.
• clear(): Clear the canvas.
• dispose(): Destroy the instance.
• initChart(): Manually initialize the chart.

Configuration & Examples

TuiEcharts is a deep wrapper component for Vue 3 based on Apache ECharts. To maintain API standardization and minimize learning costs, we expose the core configuration capabilities of ECharts.

• Configuration Reference The component's chartOption property is fully compatible with ECharts' standard data structure. For specific chart item configurations such as series, xAxis, legend, etc., please refer directly to the Apache ECharts Official Configuration Manual.
• Test Cases & Practical Code For complete source code of test cases for various charts mentioned in this document (such as 3D Pie Charts, Radar Charts, Line Charts) and more integration examples of the TechUI component library, please visit the official resource center: Preface - Ecosystem & Resources

Best Practice: 3D Pie Chart

The following code demonstrates how to combine Tui3DPanel and TuiEcharts to create a 3D pie chart with a sense of thickness.

<script setup>
  import { reactive } from "vue";

  const state = reactive({
    // Basic ECharts Configuration
    chartOption: {
      series: [
        {
          type: "pie",
          radius: ["50%", "75%"],
          data: [
            {
              value: 325,
              name: "Data A",
              itemStyle: {
                color: "#409EFF",
                // [Core] Inject 358 key, telling the component this sector needs 3D thickness
                borderWidth: 0.0000358,
              },
            },
            {
              value: 252,
              name: "Data B",
              itemStyle: { borderWidth: 0.0000358 },
            }, // Color config omitted
          ],
        },
      ],
    },
    // 3D Panel Configuration
    t3dConfig: {
      view3d: true,
      initialRotate: { x: 40, y: 0 }, // Tilt the panel backward to show thickness
    },
  });
</script>

<template>
  <Tui3DPanel v-bind="state.t3dConfig" style="height: 400px; width: 400px;">
    <TuiEcharts
      :chartOption="state.chartOption"
      renderer="svg"
      :initT3DShadow="true"
      :dataOpacity="0.8"
      :dataBlur="2"
    />
  </Tui3DPanel>
</template>

Notes

1. Performance Overhead: initT3DShadow increases the number of DOM nodes. It is recommended to disable it for scatter plots or heat maps with massive amounts of data, or only enable it on mouse hover.
2. Animation Synchronization: If the chart has an initial animation, it is recommended to set t3DShadowUpdate to 'rendered' for a smoother shadow following effect, but this will increase CPU load.

Credits

Baidu EFE team

Github

Apache Software Foundation (ASF)

Github

Special thanks and sincere respect to Baidu EFE, the founding team of the Echarts project, for creating such an outstanding open-source standard for data visualization.

We also thank the Apache Software Foundation (ASF) for the continuous maintenance and management of this project.