React 3D Tag Sphere

A React component for creating interactive 3D tag clouds with images and text. This component uses a canvas to render a visually appealing tag sphere that can be customized to fit various use cases such as skill showcases, image displays, and more.

Installation

Install the package using npm or yarn:

``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 (

type="checkbox"
checked={enablePulse}
onChange={(e) => setEnablePulse(e.target.checked)}
/>
Enable Pulse (Reset on Mouse Leave)


type="checkbox"
onChange={(e) => setMode(e.target.checked ? 'horizontal' : 'sphere')}
/>
Horizontal Mode

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`! 🎉