The react-3d-tag-sphere component allows you to create an interactive and visually appealing 3D rotating tag cloud using images. This React component provides a spherical layout of tags that rotate dynamically based on user interactions or automatic anima
npm install react-3d-tag-sphere
bash
npm install react-3d-tag-sphere
or
yarn add react-3d-tag-sphere
`
Features
- 3D Sphere Rendering: Distributes tags evenly using a Fibonacci sphere algorithm.
- Horizontal Mode: Optional cylindrical distribution for a horizontal tag cloud layout.
- Interactive Rotations: Supports mouse movements for dynamic rotation with inverse tracking (sphere moves opposite to cursor).
- Pulse Animation: Optional pulse effect that resets rotation when the mouse leaves the canvas.
- Customizable Rotation Speed: Control the speed of automatic rotation.
- Image-Based Tags: Each tag can display an image with optional customization.
- Smooth Animations: Offers fluid animations and scaling for tags.
Demo Video
Here is a demo of the project in action:
!Tag Cloud Canvas Video
Usage
$3
`tsx
import React from "react";
import { TagCloudCanvas } from 'react-3d-tag-sphere';
const MyComponent = () => {
const skills = [
{ src: 'path/to/image1.svg', size: 30 },
{ src: 'path/to/image2.png', size: 40 },
// Add more tags as needed
];
return (
tags={skills}
height={300}
width={300}
/>
);
};
export default MyComponent;
`
$3
| Prop | Type | Required | Default | Description |
|--------|----------|----------|---------|------------------------------------------------------|
| tags | Tag[] | Yes | - | Array of tags to render. See the Tag interface below.|
| height | number | Yes | - | Height of the canvas in pixels. |
| width | number | Yes | - | Width of the canvas in pixels. |
| rotationSpeed | number | No | 0.5 | Speed multiplier for rotation (higher = faster). |
| enablePulse | boolean | No | false | Enables pulse animation and resets rotation on mouse leave. |
| mode | 'sphere' \| 'horizontal' | No | 'sphere' | Layout mode: 'sphere' for 3D sphere or 'horizontal' for cylindrical layout. |
#### Tag Interface
`ts
interface Tag {
src: string; // Image source URL (required)
size?: number; // Size of the tag in pixels (auto-calculated based on canvas size if not provided)
// The following properties are auto-calculated and shouldn't be set manually:
phi?: number; // Vertical angle (auto-calculated)
theta?: number; // Horizontal angle (auto-calculated)
x?: number; // X position on unit sphere (auto-calculated)
y?: number; // Y position on unit sphere (auto-calculated)
z?: number; // Z position on unit sphere (auto-calculated)
img?: HTMLImageElement; // Loaded image element (auto-populated)
}
`
$3
#### Basic Example
`tsx
const Example = () => {
const tags = [
{ src: '/images/html.svg', size: 30 },
{ src: '/images/css.svg', size: 40 },
{ src: '/images/javascript.svg', size: 35 },
];
return (
tags={tags}
height={500}
width={500}
/>
);
};
export default Example;
`
#### Advanced Example with All Props
`tsx
import { useState } from 'react';
import { TagCloudCanvas } from 'react-3d-tag-sphere';
const AdvancedExample = () => {
const [mode, setMode] = useState<'sphere' | 'horizontal'>('sphere');
const [enablePulse, setEnablePulse] = useState(false);
const tags = [
{ src: '/images/react.png', size: 60 },
{ src: '/images/typescript.png', size: 60 },
{ src: '/images/javascript.png', size: 60 },
{ src: '/images/html.png', size: 60 },
{ src: '/images/css.png', size: 60 },
];
return (
tags={tags}
height={600}
width={600}
rotationSpeed={0.5}
enablePulse={enablePulse}
mode={mode}
/>
);
};
export default AdvancedExample;
`
How It Works
The component:
1. Distribution: Distributes tags evenly across a spherical surface using the Fibonacci sphere algorithm (for 'sphere' mode) or cylindrically around the Y-axis (for 'horizontal' mode).
2. Image Loading: Loads image resources asynchronously for smooth rendering.
3. Interactive Rotation:
- The sphere/cylinder rotates continuously based on the rotationSpeed prop.
- Mouse movement controls the rotation axis - the cloud moves in the opposite direction of the cursor for an intuitive feel.
- In horizontal mode, mouse rotation is disabled and the cloud rotates around the Y-axis automatically.
4. Pulse Animation (optional): When enablePulse is enabled, the rotation resets to a default diagonal axis when the mouse leaves the canvas.
5. Depth Perception: Tags are scaled and their opacity adjusted dynamically based on their Z-depth to create a realistic 3D effect.
6. Occlusion: Tags are rendered in order from back to front for proper visual layering.
Styling and Customization
$3
The TagCloudCanvas component uses a canvas element for rendering. You can style the canvas via the className attribute or using CSS directly:
`css
canvas {
background-color: transparent;
cursor: move;
}
`
$3
Each tag can have a custom size, and the overall rotation speed is controlled via the rotationSpeed prop:
`tsx
const tags = [
{ src: '/images/html.svg', size: 50 },
{ src: '/images/css.svg', size: 40 },
{ src: '/images/javascript.svg', size: 60 },
];
tags={tags}
height={500}
width={500}
rotationSpeed={0.8} // Faster rotation
/>
`
Development Notes
$3
The component uses the Fibonacci sphere algorithm to ensure even tag distribution on a spherical surface. Each tag's position is calculated based on its index in the array.
$3
- Sphere Mode: The sphere rotates in the opposite direction of the mouse cursor for intuitive control. The rotation axis is determined by your cursor position relative to the canvas center.
- Horizontal Mode: Automatically rotates around the vertical (Y) axis, with mouse interaction disabled for consistent behavior.
- Auto-Rotation: Both modes feature continuous auto-rotation at the speed defined by rotationSpeed.
- Pulse Mode: Enable enablePulse to reset the rotation axis to a diagonal when the mouse leaves the canvas area.
$3
To optimize rendering performance:
- Minimize the number of tags.
- Use appropriately sized images to reduce load time.
License
This project is licensed under the MIT License. See the LICENSE file for more details.
---
Happy coding with react-3d-tag-sphere`! 🎉