3D Panel

⚡WASM Powered

💎Advanced

⭐Star

👑Pioneer

T3DPanel is a container component with high visual impact. It utilizes CSS3 perspective and transform properties to endow internal content with realistic 3D depth, thickness, and dynamic perspective effects.

It has built-in interaction models that automatically calculate 3D transformations based on cursor position, device tilt, or preset animations. It is ideal for building Sci-Fi style large-screen cards, cool navigation entries, or data dashboards.

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

Basic Usage

The simplest usage is to wrap business content as a container. By default (mode="auto"), it enables Matrix mode on PC and Gyroscope mode on mobile devices.

<template>
  <Tui3DPanel>
    <div class="card-content">
      I am a 3D card with thickness and lighting.
    </div>
  </Tui3DPanel>
</template>

Global Switch

You can quickly enable or disable the deformation effects of all 3D panels via the global configuration item t3D. When set to false, the component degrades to a regular flat container and no longer consumes computing resources, which is very useful on devices with limited performance.

// Global configuration (usually in main.js or setup)
const globalConfig = {
  // ...other configurations
  t3D: true // Enable/Disable global 3D deformation
}

Modes Explained

The mode property is the core of the component, determining the behavioral logic of 3D interactions.

Matrix Mode (matrix)

Default mode for PC. All panels act as a unified matrix, deforming uniformly based on the cursor's position relative to the screen center.

• Features: The tilt angle of all T3DPanel instances on the screen is completely consistent. When the cursor is in the top-left corner of the screen, all panels tilt towards the top-left uniformly.
• Applicability: Regularly arranged card walls, data lists.

Hive Mode (hive)

Independent Gaze Interaction. Each panel calculates the relative position of the cursor and itself independently, presenting a "gaze effect" similar to a sunflower.

• Features: The further the panel is from the cursor, the more obvious the perspective deformation; the panel always faces the cursor.
• Applicability: Scattered layouts, scenarios emphasizing individual interaction.

Unity Mode (unity)

Whole Container Deformation. Treats <Tui3DPanel> as a huge 3D container. All internal child elements (passed via Slots) share the same perspective plane, but the shadows of child elements are calculated independently in real-time based on their respective positions to ensure realism.

• Features: Suitable for wrapping entire dashboard sections or complex composite components.

Hover Mode (hover)

Triggered by Mouse Interaction. Triggers 3D deformation only on mouse hover. Supports smooth transition from initialRotate (initial angle) to hoverRotate (target angle).

• Applicability: Navigation buttons, key data cards.

Animation Mode (animation)

Automatic Loop Playback. Automatically loops 3D swaying animations based on the passed animationRotate keyframe array.

• Configuration: Needs to be used with duration (cycle) and aniDelay (delay).

Gyroscope Mode (gyro)

Mobile Exclusive. Calls the mobile device's gyroscope (gravity sensor) data to control the 3D posture of the panel in real-time based on the phone's physical tilt angle.

• Requirement: Device sensor APIs can only be called in an HTTPS environment.

Static Mode (static)

Fixed Display. Does not respond to any interaction and always maintains the fixed angle set by initialRotate.

Auto Mode (auto)

Smart Switching (Default).

• PC: Automatically switches to matrix mode.
• Mobile: Automatically switches to gyro mode.

Visual & Physical Configuration

Shadow System

The component automatically calculates shadows simulating a real light source.

• showShadow: Whether to show shadows.
• shadowCoeff: Shadow displacement coefficient. The larger the value, the further the shadow deviates from the main body, and the stronger the floating sensation.
• shadowBlur: Shadow blur radius.

Thickness System

The component simulates the physical thickness of objects through a stacking algorithm.

• showThickness: Whether to show thickness.
• thicknessLength: The physical pixel length of the thickness.
• thicknessColor: Color of the thickness layer. Defaults to automatically fetching the theme color.
• thicknessFixGap: Whether to enable thickness gap correction (used to solve tiny cracks during rendering in some browsers).

Slot Scopes

T3DPanel exposes a set of special dynamic shadow class names to the interior by default via scoped slots.

These class names are not static styles but calculate offsets and blurriness in real-time based on the current 3D deformation angle and light source direction. Binding them to internal business elements can achieve real-time linkage between shadows and 3D posture, thereby greatly enhancing the stereoscopic and realistic feel.

Property Name	Default	Description
boxShadowName	'box-shadow-item'	Box Shadow Linkage. Used for the container's box-shadow, changing shadow projection direction as the panel tilts.
textShadowName	'text-shadow-item'	Text Shadow Linkage. Used for internal text text-shadow to enhance the floating feel of text.
t3dShadowName	't3d-shadow-item'	3D Specialized Shadow. Used in conjunction with the thickness system or for more complex 3D scene simulations.
dropShadowName	'drop-shadow-item'	Filter Projection Linkage. Used for filter: drop-shadow on transparent PNG images or SVG icons to ensure accurate projection shapes.

Usage Example

<Tui3DPanel>
  <template #default="{ boxShadowName, textShadowName, dropShadowName }">
    
    <div class="my-card" :class="boxShadowName">
      
      <h3 :class="textShadowName">3D Data Visualization</h3>
      
      <img src="icon.png" :class="dropShadowName" />
      
    </div>
    
  </template>
</Tui3DPanel>

API Reference

Props

Core Configuration

Property Name	Type	Default	Description
mode	String	'auto'	Core. Options: 'auto', 'matrix', 'hive', 'unity', 'hover', 'animation', 'gyro', 'static'.
coeff	Number	null	Global deformation coefficient. Controls the sensitivity of 3D rotation; larger values mean greater rotation amplitude.
perspective	Number	-	CSS Perspective. Determines the strength of the 3D perspective.
transformOrigin	String	null	Deformation origin. E.g., 'left top', 'center'. Supports standard CSS syntax.
view3d	Boolean	true	Whether the current component participates in 3D rendering.

Interaction & Animation

Property Name	Type	Default	Description
initialRotate	Object	{x:0,y:0,z:0}	Initial rotation angle (Start state for Static/Hover modes).
hoverRotate	Object	{x:0,y:0,z:0}	Hover target rotation angle (Hover mode).
rotateMax	Number	50	Maximum rotation angle limit (Matrix/Hive modes).
rotateMin	Number	-50	Minimum rotation angle limit (Matrix/Hive modes).
animationRotate	Array	[]	Animation keyframe array [{x,y}, {x,y}...] (Animation mode).
duration	Number	null	Animation single cycle duration (ms).
aniDelay	Number	1000	Animation start delay (ms).
hoverDelay	Number	0	Hover trigger delay (ms).
hoverMask	Boolean	false	Whether to show a highlight mask on hover.

Mobile Gyroscope

Property Name	Type	Default	Description
uesAlpha	Boolean	false	Whether to use Alpha (compass direction) data for rotation.
fixAlpha	Number	0	Alpha angle correction value.

Visual Effects (Shadow/Thickness)

Property Name	Type	Default	Description
showShadow	Boolean	true	Whether to show dynamic shadows.
shadowCoeff	Number	-	Shadow displacement coefficient.
shadowBlur	Number	-	Shadow blurriness.
shadowTransparent	Number	-	Shadow transparency.
showThickness	Boolean	true	Whether to show 3D thickness.
thicknessLength	Number	-	Thickness depth (px).
thicknessCoeff	Number	-	Thickness stacking coefficient.
thicknessColor	String	null	Thickness side color.
thicknessFixGap	Boolean	false	Enable thickness rendering gap correction.

Others

Property Name	Type	Default	Description
eventBus	Boolean	false	Whether to enable the event bus. Used for multi-component state synchronization in Unity/Gyro modes.
index	Number	0	Index during list rendering (used for calculating staggered animations).
group	String	't3dcom'	Component group name.