React 3D components library with React Three Fiber and GSAP
npm install @swa-react-3d/componentsbash
npm install @swa-react-3d/components
`
CSS import: You must import the component styles in your application:
`js
import '@swa-react-3d/components/dist/style.css';
`
Components
$3
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:
`jsx
import { Hero3D } from '@swa-react-3d/components';
import '@swa-react-3d/components/dist/style.css';
function App() {
return (
primitiveType="sphere"
primitiveColor="#ff6b6b"
/>
);
}
`
Usage with a GLTF model:
`jsx
import { Hero3D } from '@swa-react-3d/components';
import '@swa-react-3d/components/dist/style.css';
function App() {
return (
modelPath="/models/laptop.glb"
screenUrl="https://example.com"
/>
);
}
`
$3
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):
`jsx
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:
`jsx
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:
`jsx
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);
}
`
$3
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):
`jsx
import { FloatingObject } from '@swa-react-3d/components';
import { Canvas } from '@react-three/fiber';
import '@swa-react-3d/components/dist/style.css';
function App() {
return (
);
}
`
$3
For advanced use cases, you can use the useResponsiveHtmlProps hook directly to calculate responsive HTML positioning in your own custom components.
Usage:
`jsx
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 (
position={responsiveProps.position}
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:
$3
| 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 |
$3
| 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 |
$3
| 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:
`bash
npm run watch --workspace=packages/swa-react-3d-components
`
Run the showcase app:
`bash
npm run dev
``