3D Bar Chart

⚡WASM Powered

💎Advanced

⭐Star

👑Pioneer

TuiBar3D is a 3D visualization chart component with high-fidelity material texture, built using dynamic SVG technology.

Unlike ordinary pseudo-3D charts, Bar3D simulates the physical effects of a translucent glass shell and internal liquid filling. It utilizes advanced CSS3 features to build visual effects with perspective depth, light refraction, and dynamic liquid levels without introducing a heavy WebGL engine.

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

Core Features

• Dual Shapes: Supports two geometric forms: Cylinder and Cube.
• Liquid Level Simulation: The interior of the column presents a liquid filling effect. The liquid height changes with data, accompanied by floating light and shadow effects.
• Smart Thresholds: Supports configuration of multi-level thresholds. It automatically switches the bar color state (e.g., Danger, Warning, Normal, Success) based on the numerical value.
• Scene Components: Optional configuration for Base and Back Track to enhance the sense of spatial positioning.
• Queue Animation: Cooperates with TuiBar3DGroup to achieve delayed sequence playback for multiple sets of data.

Basic Usage

Bar3D is a highly adaptive component; its height is completely determined by the parent container.

<template>
  <div style="height: 300px; width: 100px;">
    <TuiBar3D 
      label="Visits"
      :value="75"
      :maxValue="100"
      unit="Times"
      shape="cylinder" 
    />
  </div>
</template>

Advanced Features

Thresholds & Status

The component supports automatically changing the color state based on numerical values.

• Manual Status: Forcibly specify via the status prop (normal, success, warning, danger, critical, emphasis).
• Automatic Thresholds: Configured via the thresholds object. When value reaches the set value, the corresponding state color is automatically applied.

const myThresholds = {
  danger: 0,    // 0-59 displays Red (danger)
  warning: 60,  // 60-79 displays Orange (warning)
  success: 80   // >=80 displays Green (success)
}

<TuiBar3D :value="85" :thresholds="myThresholds" />

3D Scene Configuration

Enhance the stereoscopic effect by adjusting the viewing distance and auxiliary components.

• viewDeep: View Depth. The larger the value, the more exaggerated the perspective (stronger top-down view); the smaller the value, the closer it is to a flat plane.
• showBase: Displays the bottom base.
• showTrack: Displays the translucent back track.
• gap: The spacing between the bar and its back track. Increasing this value enhances the sense of suspension.

Queue Display (Group)

Use the helper component TuiBar3DGroup to quickly render a group of bar charts and automatically handle Staggered Entrance Animations (delayed playback).

<template>
  <div style="height: 300px; display: flex;">
    <TuiBar3DGroup 
      :items="[
        { label: 'Area A', value: 45 },
        { label: 'Area B', value: 80 },
        { label: 'Area C', value: 30 }
      ]"
      :progress3DBarConfig="{
         shape: 'cube',
         showBase: true,
         aniDelay: 500 // Unified animation delay configuration
      }" 
    />
  </div>
</template>

API Reference

Props

Data Configuration

Property Name	Type	Default	Description
label	String	Required	The title label displayed at the bottom.
value	Number	0	Current value.
maxValue	Number	null	Maximum value (used to calculate liquid level percentage). Defaults to 100 if not specified.
unit	String	''	Numerical unit.
precision	Number	0	Display precision (number of decimal places).
displayValue	String	'auto'	Value display mode: 'auto' (Automatic), 'none' (Hidden), 'all' (Show Value/Max), 'allReverse' (Show Value/Max with line break).
mainValuePosition	String	'auto'	Main value display position. 'auto' (Follows liquid level), 'top' (Fixed at top).

Appearance & Shape

Property Name	Type	Default	Description
shape	String	'cylinder'	Bar shape. Options: 'cylinder', 'cube'.
status	String	null	Forced status color: 'normal', 'success', 'danger', 'warning', 'emphasis', 'critical'.
thresholds	Object	null	Threshold configuration object. Keys are status names, values are trigger thresholds.
barColor	String	null	Custom bar color (accepts CSS color values).
barColorRatio	Number	15	Bar gradient difference coefficient (controls the intensity of stereoscopic lighting).
barBlur	Number	0.7	Bar blurriness (frosted glass effect).
barOpacity	Number	0.9	Bar opacity.

3D Scene & Auxiliaries

Property Name	Type	Default	Description
viewDeep	Number	15	3D View Depth (0-50).
showTrack	Boolean	true	Whether to show the back track.
trackOpacity	Number	0.5	Track opacity.
gap	Number	30	Spacing between the bar and the track.
showBase	Boolean	false	Whether to show the base.
baseSpacing	Number	20	Base margin size.
baseColorWeakened	Boolean	false	Whether to weaken the base color.

Animation & Control

Property Name	Type	Default	Description
duration	Number	1000	Animation duration (ms).
aniDelay	Number	2000	Entrance animation delay (ms).
resizeObserver	String	'global'	Dimension listening strategy: 'self', 'global', 'none'.
initHold	Boolean	false	Whether to keep still (no animation) on initialization.

Events

Event Name	Description
inited	Triggered when component initialization and entrance animation are complete.

Expose

Property Name	Type	Description
inited	Boolean	Whether the current component has completed initialization.

Visual

The visual effects of Bar3D are controlled by a set of fine-tuned SVG gradient variables. The component splits the bar, base, and track into multiple illuminated surfaces internally and assigns different CSS variables to them to simulate real lighting relationships.

You can override the following variables to adjust the color of each part:

Bar

The bar is the visual subject. Its color is automatically determined by the status or thresholds, but its lighting hierarchy is controlled by the following variables:

• --tui-bar3d-bargrad-A: Highlight Surface Color. Usually used for the side or top surface that receives the strongest light.
• --tui-bar3d-bargrad-B: Mid-tone/Transition Color. Used for the main transition area of the bar or Side A of the cube.
• --tui-bar3d-bargrad-C: Backlight/Shadow Color. Used for the shadow side of the bar or Side B of the cube.
• --tui-bar3d-shinegrad-A / B: Glass Highlight Color. Used to simulate the specular reflection of the shell (usually translucent white).

Base

When showBase is enabled, the color of the base is controlled by the following variables:

• Normal State:

  • --tui-bar3d-basgrad-A: Base illuminated surface.
  • --tui-bar3d-basgrad-B: Base backlight/transition surface.

• Weakened State (is-weakened):

  • When baseColorWeakened is enabled, the base is forced to use the Track's color variables, thereby visually receding to a secondary position to highlight the data bar.

Track

When showTrack is enabled, the color of the translucent back track:

• --tui-bar3d-trkgrad-A: Track illuminated surface.
• --tui-bar3d-trkgrad-B: Track backlight surface.

Gradient Mapping Logic (Example: Cube)

To give the Cube a stereoscopic feel, the component uses a "Dual-Face Shading" strategy:

• Side A (cubeSA): Maps to the gradient bargrad-B -> bargrad-A (Light to Dark transition).
• Side B (cubeSB): Maps to the gradient bargrad-B -> bargrad-C (Neutral to Shadow transition).

This differentiated mapping ensures that even with monochromatic data, it presents a clear, sharp-edged perception.