@swa-react-3d/components

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

Installation

bash

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}

      scale={responsiveProps.scale}

      rotation={responsiveProps.rotation}

      style={{

        width: responsiveProps.width,

        height: responsiveProps.height

      }}

    >

      Your custom content

    

  );

}





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

License

ISC

@swa-react-3d/components

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

Installation

bash

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}

      scale={responsiveProps.scale}

      rotation={responsiveProps.rotation}

      style={{

        width: responsiveProps.width,

        height: responsiveProps.height

      }}

    >

      Your custom content

    

  );

}





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

License

ISC