@swa-react-3d/components

React 3D components library built with React Three Fiber and GSAP.

Installation

npm install @swa-react-3d/components

CSS import: You must import the component styles in your application:

import '@swa-react-3d/components/dist/style.css';

Components

Hero3D

A 3D hero section component that displays floating 3D objects using React Three Fiber. Supports both GLTF models and primitive shapes.

Props:

| Prop | Type | Default | Description | |------|------|---------|-------------| | modelPath | string | undefined | Path to a GLTF model file | | primitiveType | 'box' \| 'sphere' \| 'cone' | 'box' | Type of primitive shape (used when no model is provided) | | primitiveColor | string | '#3a8cff' | Color of the primitive shape | | screenUrl | string | undefined | URL to display in an embedded iframe (for laptop-style models) |

Usage with a primitive shape:

import { Hero3D } from '@swa-react-3d/components';
import '@swa-react-3d/components/dist/style.css';

function App() {
  return (
    <Hero3D 
      primitiveType="sphere" 
      primitiveColor="#ff6b6b" 
    />
  );
}

Usage with a GLTF model:

import { Hero3D } from '@swa-react-3d/components';
import '@swa-react-3d/components/dist/style.css';

function App() {
  return (
    <Hero3D 
      modelPath="/models/laptop.glb"
      screenUrl="https://example.com"
    />
  );
}

CSS Custom Properties:

The component container can be styled using CSS Custom Properties:

| Variable | Description | Default | |----------|-------------|---------| | --hero3d-height | Container height | 100% | | --hero3d-width | Container width | 100% | | --hero3d-bg-color | Container background color | transparent |

:root {
  --hero3d-height: 500px;
  --hero3d-bg-color: rgba(0, 0, 0, 0.05);
}

FloatingObject

A lower-level component used by Hero3D that renders the actual 3D object with GSAP-powered floating animations. Can be used directly within a React Three Fiber Canvas for more control.

Props:

| Prop | Type | Default | Description | |------|------|---------|-------------| | modelPath | string | undefined | Path to a GLTF model file | | primitiveType | 'box' \| 'sphere' \| 'cone' | 'box' | Type of primitive shape | | primitiveColor | string | '#3a8cff' | Color of the primitive shape | | screenUrl | string | 'about:blank' | URL to display in an embedded iframe |

Usage (within a Canvas):

import { FloatingObject } from '@swa-react-3d/components';
import { Canvas } from '@react-three/fiber';
import '@swa-react-3d/components/dist/style.css';

function App() {
  return (
    <Canvas camera={{ position: [0, 0, 14], fov: 28 }}>
      <ambientLight intensity={0.6} />
      <directionalLight position={[5, 5, 3]} intensity={1.2} />
      <FloatingObject primitiveType="cone" primitiveColor="#4ecdc4" />
    </Canvas>
  );
}

Peer Dependencies

This library requires the following peer dependencies:

• react >= 18.3.0
• react-dom >= 18.3.0
• @react-three/fiber >= 8.15.0
• @react-three/drei >= 9.88.0
• three >= 0.160.0
• gsap >= 3.13.0

Compatibility Notes

This package has been tested with the following dependency combinations:

Recommended Combinations

| React | Three.js | @react-three/fiber | @react-three/drei | GSAP | Status | |-------|----------|-------------------|-------------------|------|--------| | 19.2.0 | 0.160.0 | 9.4.0 | 10.7.6 | 3.13.0 | ✅ Recommended | | 19.2.0 | 0.160.1 | 9.4.0 | 10.7.6 | 3.13.0 | ✅ Tested | | 19.2.0 | 0.160.0 | 9.0.0 | 10.0.0 | 3.13.0 | ✅ Tested |

React 18 Combinations

| React | Three.js | @react-three/fiber | @react-three/drei | GSAP | Status | |-------|----------|-------------------|-------------------|------|--------| | 18.3.1 | 0.160.0 | 8.15.0 | 9.88.0 | 3.13.0 | ✅ Tested | | 18.3.1 | 0.160.1 | 8.15.0 | 9.88.0 | 3.13.0 | ✅ Tested | | 18.3.1 | 0.160.0 | 8.15.0 | 10.0.0 | 3.13.0 | ✅ Tested | | 18.3.1 | 0.160.0 | 8.15.0 | 10.7.6 | 3.13.0 | ✅ Tested |

Cross-Version Combinations

| React | Three.js | @react-three/fiber | @react-three/drei | GSAP | Status | |-------|----------|-------------------|-------------------|------|--------| | 19.2.0 | 0.160.0 | 9.0.0 | 9.88.0 | 3.13.0 | ✅ Tested | | 19.2.0 | 0.160.0 | 9.4.0 | 9.88.0 | 3.13.0 | ✅ Tested | | 19.2.0 | 0.160.0 | 9.4.0 | 10.0.0 | 3.13.0 | ✅ Tested |

Note: The peer dependency ranges specify minimum tested versions. Using versions outside these ranges may work but is not officially supported. If you encounter compatibility issues, please ensure your dependencies match one of the tested combinations above.

Version Summary:

• React: 18.3.1 or 19.2.0
• @react-three/fiber: 8.15.0 (React 18) or 9.0.0-9.4.0 (React 19)
• @react-three/drei: 9.88.0 - 10.7.6
• Three.js: 0.160.0 - 0.160.1
• GSAP: 3.13.0

Development

This package is part of the swa-react-3d-components monorepo.

Build the library:

npm run build:components
# or
npm run build --workspace=packages/swa-react-3d-components

Watch mode for development:

npm run watch --workspace=packages/swa-react-3d-components

Run the showcase app:

npm run dev

License

ISC