3D Pie Chart

⚡WASM Powered

💎Advanced

⭐Star

👑Pioneer

Pie3D is a 3D donut/pie chart component built based on SVG and CSS3 transforms.

Similar to Bar3D, it does not rely on a massive WebGL engine. Instead, it creatively directly calls the Tui3DPanel component as its underlying spatial container. It places the flat donut chart inside the Tui3DPanel for 3D tilting and uses dynamic "Stacking Shadows" technology to simulate realistic physical thickness and side lighting.

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

Core Features

• True 3D Posture: Encapsulates Tui3DPanel internally, supporting precise control of the spatial top-down view angle via the transform3D property.
• Physical Thickness Simulation: Automatically calculates the side thickness color of sectors using CSS variables and shadow layers to present a stereoscopic effect.
• High Degree of Freedom Styling: Supports adjusting the inner radius (switching between ring/pie shapes), corner radius (cornerRadius), and sector explosion gaps (gapSize).
• Rich Interaction: Supports sector hover floating animation (hoverOffset), click events, and legend interaction.
• Center Dashboard: Automatically aggregates and displays the total count and title in the center of the ring chart, making it suitable for use as a dashboard.

Basic Usage

Pie3D requires an array of objects containing label and value as the data source.

<template>
  <div style="height: 350px;">
    <TuiPie3D 
      :data="pieData"
      chartTitle="Total Sales"
      unit="Million"
    />
  </div>
</template>

<script setup>
const pieData = [
  { label: 'Electronics', value: 45 },
  { label: 'Clothing', value: 30 },
  { label: 'Home', value: 15 },
  { label: 'Others', value: 10 }
]
</script>

Principles

3D Implementation Mechanism (The 3D Trick)

Core Principle: TuiPie3D = SVG + Tui3DPanel

The TuiPie3D component **directly invokes Tui3DPanel** internally. The entire pie chart is essentially a flat SVG graphic wrapped inside the 3D spatial container provided by Tui3DPanel.

This means:

1. Posture Control: The rotation parameters (such as the top-down angle) you pass via the transform3D property actually act directly on the internal Tui3DPanel.
2. Configuration Passthrough: You can pass low-level parameters like shadow coefficients and thickness corrections to the internal Tui3DPanel via the t3DConfig property.

Thickness Principle: The component generates a corresponding shadow layer (t3d-shadow-item) for each sector internally. The color of the side is not a texture map but is achieved by calculating a darkened value of the base color.

• Control Parameter: thicknessColorRatio (default is 2). The larger the value, the darker the side (shadow face) color relative to the top face color, and the stronger the stereoscopic contrast.
• Code Logic:

<path style="--tui-t3d-thickcolor: darken(slice.color, ratio);" ... />

Styling Control

• Inner Radius (innerRadiusPercent): Controls the thickness of the ring. Setting it to 0 turns it into a solid pie chart.
• Sector Corner Radius (cornerRadius): Adds rounded corners to the edges of sectors, making the style softer and more modern.
• Sector Explosion (gapSize): Sets the physical gap between sectors. It not only creates visual separation but also causes sectors to have a slight outward displacement in 3D space, enhancing the sense of independence.

Center Content

When innerRadiusPercent > 0 (i.e., a ring chart) and showCenterText is true, the component displays summary information in the center.

• Auto Aggregation: The component automatically calculates the sum of all values in data and displays it in the center.
• Title and Unit: Defined via chartTitle and unit.
• Offset Correction: If the visual center shifts due to 3D perspective, centerTextOffset can be used for fine-tuning.

3D Posture and Lighting

You can precisely control the spatial angle of the chart via transform3D.

// Recommended configuration: 50-degree top-down view
const config = {
  // Directly controls the rotation of the internal Tui3DPanel
  transform3D: { x: 50, y: 0, z: 0 },
  
  // Advanced configuration passed through to the internal Tui3DPanel
  t3DConfig: {
    shadowCoeff: 0.1, // Shadow distance coefficient
    thicknessCoeff: 0.15 // Thickness stacking coefficient
  }
}

API Reference

Props

Data & Legend

Property Name	Type	Default	Description
data	Array	[]	Data source. Format [{ label, value, color? }, ...].
useDefaultColors	Boolean	true	Whether to use the component's built-in color palette. If a data item has its own color, it takes precedence.
legendShow	Boolean	true	Whether to show the legend.
legendPosition	String	'bottom'	Legend position: 'bottom', 'top', 'left', 'right'.
chartTitle	String	'Total'	Title text displayed in the center.
unit	String	-	Unit displayed in the center.
showCenterText	Boolean	true	Whether to show center summary content.

Styling & Appearance

Property Name	Type	Default	Description
width	Number/String	-	Container width.
height	Number/String	-	Container height.
innerRadiusPercent	Number	50	Inner radius percentage (0-95). 0 represents a solid pie chart.
cornerRadius	Number	0	Sector corner radius.
gapSize	Number	10	Gap size between sectors.
useGradient	Boolean	false	Whether to enable slight gradient effects for sector colors (enhances texture).
gradientRatio	Number	0.3	Gradient intensity coefficient.
thicknessColorRatio	Number	2	Thickness Darkening Coefficient. Controls the darkness of the side shadows.

3D Space & Interaction

Property Name	Type	Default	Description
transform3D	Object	-	3D rotation angles. E.g., { x: 50, y: 0, z: 0 }. Acts on the internal Tui3DPanel.
t3DConfig	Object	-	Configuration object passed through to the underlying Tui3DPanel (e.g., shadow coefficients).
pieOffset	Number	-	Y-axis offset of the entire pie chart within the container.
centerTextOffset	Number	-	Fine-tuning Y-axis offset for center text.
hoverOffset	Number	5	Floating (explosion) distance of a sector on mouse hover.
animate	Boolean	true	Whether to enable entrance animation.
animationDuration	Number	750	Animation duration (ms).
resizeObserver	String	'global'	Dimension listening strategy: 'self', 'global', 'none'.

Events

Event Name	Description
sliceClick	Triggered when a sector is clicked. Callback parameters: (event, sliceData, index).
sliceHover	Triggered when the mouse enters a sector.
sliceLeave	Triggered when the mouse leaves a sector.

Potential Issues

Since Pie3D internally contains the Tui3DPanel component, nesting Tui3DPanel outside of Pie3D may lead to unexpected issues. Detailed testing for this scenario has not been conducted yet, so users are advised to avoid nested usage of Tui3DPanel where possible.