@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"
    />
  );
}

Responsive HTML Positioning

When using a GLTF model with an embedded screen/iframe, the HTML element position automatically adjusts based on canvas dimensions. This ensures proper alignment with the 3D model across different screen sizes without conflicting with orbital camera controls.

Default Responsive Behavior:

By default, HTML positioning properties are normalized based on a reference resolution of 1920x1080. This means:

• Position values automatically adjust based on live canvas dimensions
• Scale, width, and height remain constant as specified
• The iframe maintains proper alignment with the 3D model at any screen size
• Layout animations and post-load measurements are accounted for

Customizing HTML Position (with responsive positioning):

<Hero3D 
  modelPath="/models/laptop.glb"
  screenUrl="https://example.com"
  htmlProps={{
    position: [0, 0.2, -1.5],      // Adjusted position in 3D space (will scale responsively)
    rotation: [0.01, 0, 0],        // Slight tilt
    scale: [1.8, 1.8, 1],          // Fixed scale (does not change with canvas size)
    width: '1400px',               // Fixed iframe width
    height: '800px'                // Fixed iframe height
  }}
/>

Using a Custom Reference Resolution:

<Hero3D 
  modelPath="/models/laptop.glb"
  screenUrl="https://example.com"
  htmlProps={{
    referenceWidth: 2560,   // Reference width for normalization
    referenceHeight: 1440   // Reference height for normalization
  }}
/>

Disabling Responsive Mode:

If you need fixed positioning that doesn't scale with canvas dimensions:

<Hero3D 
  modelPath="/models/laptop.glb"
  screenUrl="https://example.com"
  htmlProps={{
    responsive: false,       // Disable responsive scaling
    position: [0, 0.149, -1.697],
    scale: [1.6, 1.6, 1]
  }}
/>

HTML Positioning Props:

| Property | Type | Default | Description | |----------|------|---------|-------------| | position | [number, number, number] | [0, 0.149, -1.697] | Position in 3D space [x, y, z] | | rotation | [number, number, number] | [0.004, 0, 0] | Rotation in radians [x, y, z] | | scale | [number, number, number] \| number | [1.6, 1.6, 1] | Scale [x, y, z] or uniform | | distanceFactor | number | 1 | Perspective distance factor | | width | string | '1238px' | Width of HTML container | | height | string | '695px' | Height of HTML container | | responsive | boolean | true | Enable responsive scaling | | referenceWidth | number | 1920 | Reference canvas width | | referenceHeight | number | 1080 | Reference canvas height |

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

```css
: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 | | htmlProps | HtmlPositionProps | {} | Positioning props for the embedded HTML element |

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

useResponsiveHtmlProps Hook

For advanced use cases, you can use the useResponsiveHtmlProps hook directly to calculate responsive HTML positioning in your own custom components.

Usage:

import { useResponsiveHtmlProps } from '@swa-react-3d/components';
import { Html } from '@react-three/drei';

function MyCustomComponent() {
  const responsiveProps = useResponsiveHtmlProps(
    {
      position: [0, 0.2, -1.5],
      scale: [1.8, 1.8, 1],
      width: '1400px',
      height: '800px'
    },
    {
      referenceWidth: 1920,
      referenceHeight: 1080
    }
  );

  return (
    <Html
      position={responsiveProps.position}
      scale={responsiveProps.scale}
      rotation={responsiveProps.rotation}
      style={{
        width: responsiveProps.width,
        height: responsiveProps.height
      }}
    >
      <div>Your custom content</div>
    </Html>
  );
}

Parameters:

• baseProps (object): Base HTML positioning properties

  • position?: [number, number, number] - Base position in 3D space
  • rotation?: [number, number, number] - Base rotation in radians
  • scale?: [number, number, number] | number - Base scale
  • width?: string - Base width in CSS units
  • height?: string - Base height in CSS units

• config (object, optional): Reference resolution configuration

  • referenceWidth?: number - Reference canvas width (default: 1920)
  • referenceHeight?: number - Reference canvas height (default: 1080)

Returns:

• ResponsiveHtmlProps object with normalized values:
  • position: [number, number, number] - Scaled position
  • rotation: [number, number, number] - Original rotation (unchanged)
  • scale: [number, number, number] | number - Scaled scale
  • width: string - Scaled width
  • height: string - Scaled height

## 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:

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