@lidvizion/react-3d-overlay

A React 3D overlay component featuring a morphing loading animation that cycles through different geometric shapes (orb, prism, pyramid, cube) with customizable text. The component includes its own Canvas and lighting setup, so you don't need to configure them separately.

Features

• Smooth morphing animation between geometric shapes
• Customizable 3D text overlay
• Obsidian-style glossy material with optional image reflection
• Continuous rotation animation
• Small shadow effect
• Built-in Canvas and lighting (no setup required)
• Fully typed with TypeScript

Installation

npm install @lidvizion/react-3d-overlay

Peer Dependencies

This library requires the following peer dependencies:

• react (^18 || ^19)
• react-dom (^18 || ^19)
• @react-three/fiber (^8.17.10)
• @react-three/drei (^9.114.0)
• three (^0.169.0)

Usage

import { LoadingOverlay } from '@lidvizion/react-3d-overlay';

function App() {
  return (
    <div style={{ width: '100%', height: '400px' }}>
      <LoadingOverlay
        position={[0, 0, 0]}
        radius={1}
        text="enhancing..."
        hoverHeight={1.5}
        color="#0a0a0f"
      />
    </div>
  );
}

With Image Reflection

You can pass an image that will be reflected on the surface of the morphing object:

import { LoadingOverlay } from '@lidvizion/react-3d-overlay';
import myImage from './path/to/image.jpg';

function App() {
  return (
    <div style={{ width: '100%', height: '400px' }}>
      <LoadingOverlay
        position={[0, 0, 0]}
        radius={1}
        text="enhancing..."
        envMapImage={myImage}
      />
    </div>
  );
}

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | position | [number, number, number] | [0, 0, 0] | Position of the overlay in 3D space | | radius | number | 1 | Radius/size of the morphing object | | color | string | '#0a0a0f' | Color of the object (obsidian by default) | | rotationSpeed | number | 0.15 | Speed of rotation animation | | hoverHeight | number | 0.1 | Height offset above the base position | | text | string | 'enhancing...' | Text to display in front of the object | | envMapImage | string | undefined | Optional image URL/path to reflect on the object surface | | className | string | undefined | CSS class name for the wrapper div | | style | React.CSSProperties | undefined | Inline styles for the wrapper div |

Animation

The component automatically cycles through the following sequence:

1. Orb → Prism → Orb
2. Orb → Pyramid → Orb
3. Orb → Cube → Orb
4. (Repeats)

Each transformation takes 1 second, with the object always returning to the orb shape before morphing to the next shape.

License

MIT