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:

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:

Usage

Import and Setup

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 (
    <TagCloudCanvas
      tags={skills}
      height={300}
      width={300}
    />
  );
};

export default MyComponent;

Props

| 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

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)
}

Example Configuration

Basic Example

const Example = () => {
  const tags = [
    { src: '/images/html.svg', size: 30 },
    { src: '/images/css.svg', size: 40 },
    { src: '/images/javascript.svg', size: 35 },
  ];

  return (
    <TagCloudCanvas
      tags={tags}
      height={500}
      width={500}
    />
  );
};

export default Example;

Advanced Example with All Props

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 (
    <div>
      <div style={{ marginBottom: '20px' }}>
        <label>
          <input
            type="checkbox"
            checked={enablePulse}
            onChange={(e) => setEnablePulse(e.target.checked)}
          />
          Enable Pulse (Reset on Mouse Leave)
        </label>
        <label style={{ marginLeft: '20px' }}>
          <input
            type="checkbox"
            onChange={(e) => setMode(e.target.checked ? 'horizontal' : 'sphere')}
          />
          Horizontal Mode
        </label>
      </div>
      
      <TagCloudCanvas
        tags={tags}
        height={600}
        width={600}
        rotationSpeed={0.5}
        enablePulse={enablePulse}
        mode={mode}
      />
    </div>
  );
};

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

Canvas Styling

The TagCloudCanvas component uses a canvas element for rendering. You can style the canvas via the className attribute or using CSS directly:

canvas {
  background-color: transparent;
  cursor: move;
}

Tag Size and Rotation Speed

Each tag can have a custom size, and the overall rotation speed is controlled via the rotationSpeed prop:

const tags = [
  { src: '/images/html.svg', size: 50 },
  { src: '/images/css.svg', size: 40 },
  { src: '/images/javascript.svg', size: 60 },
];

<TagCloudCanvas
  tags={tags}
  height={500}
  width={500}
  rotationSpeed={0.8} // Faster rotation
/>

Development Notes

Fibonacci Sphere Algorithm

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.

Interactivity

• 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.

Performance Optimization

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