3D Renderer

A professional React component for rendering and interacting with 3D GLTF/GLB models using Three.js and React Three Fiber. Features 20+ interactive controls for camera, lights, model transforms, and automatic rotation speeds.

Features

• 🎨 Interactive 3D Model Viewer – Render and manipulate GLTF/GLB models with real-time feedback
• 🎮 20+ Live Controls – Adjust camera, lights, position, rotation, scale, and rotation speeds via Leva UI
• 📱 Mobile Responsive – Auto-detects mobile and disables orbit controls for better UX
• 💡 Advanced Lighting – Ambient, directional (with position control), and hemisphere lights
• 🔄 Per-Axis Rotation – Independent control over X, Y, Z rotation speeds for dynamic presentations
• 🌍 Environment Presets – City environment lighting for realistic renders
• ✨ Smooth Animations – Float animation with configurable intensity
• 💾 State Persistence – Save/restore control states via the model object
• 🚀 Zero-Config Ready – Works out-of-the-box with sensible defaults
• 🛠️ Easy Setup – Simple CLI tool to add component to your project

Installation

Quick Setup (Recommended)

Use npx to add the component to your project:

npx 3drenderer init

This will copy ModelsRenderer.jsx to your current directory.

Options:

• npx 3drenderer init -y – Skip confirmation prompts
• npx 3drenderer init --output ./src/components – Install to custom path

Manual Installation

If you prefer to install as a dependency:

npm install 3drenderer

You'll also need to install the peer dependencies:

npm install react react-dom three @react-three/fiber @react-three/drei leva

Quick Start

After running npx 3drenderer init, import and use the component:

import ModelRenderer from "./ModelsRenderer";

export default function App() {
  const model = {
    modelPath: "/models/my-model.glb",
    editable: true, // Shows the Leva control panel
  };

  return <ModelRenderer model={model} />;
}

Props

model (required)

An object controlling the component state. Properties:

| Property | Type | Default | Description | | ------------------------------------- | ------- | ---------- | ----------------------------------------------------- | | modelPath | string | — | Required. Path or URL to your GLTF/GLB model file | | editable | boolean | false | Show/hide the Leva control panel | | camX, camY, camZ | number | 0, 0, 25 | Camera position | | fov | number | 75 | Camera field of view (degrees) | | ambientIntensity | number | 0.2 | Ambient light strength | | dirIntensity | number | 0.9 | Directional light strength | | hemiIntensity | number | 0.2 | Hemisphere light strength | | lightX, lightY, lightZ | number | 10, 15, 10 | Directional light position | | posX, posY, posZ | number | 0, 0, 0 | Model position | | rotX, rotY, rotZ | number | 0, 0, 0 | Model rotation (radians) | | scale | number | 1 | Model scale factor | | rotSpeedX, rotSpeedY, rotSpeedZ | number | 0, 0.01, 0 | Automatic rotation speed per axis |

Leva Control Panels

When model.editable is true, the component shows interactive Leva panels:

Camera Panel

• camX, camY, camZ (-50 to 50): Adjust camera position
• fov (20 to 100): Adjust field of view

Lights Panel

• ambientIntensity (0 to 5): Background light
• dirIntensity (0 to 5): Main directional light
• hemiIntensity (0 to 5): Sky/ground light

Light Position Panel

• lightX, lightY, lightZ (-50 to 50): Position of the directional light

Model Panel

• posX, posY, posZ (-10 to 10): Model position
• rotX, rotY, rotZ (-π to π): Model rotation
• scale (0.1 to 5): Model size

Rotation Speed Panel

• rotSpeedX, rotSpeedY, rotSpeedZ (-0.1 to 0.1): Auto-rotation per axis

Advanced Usage

State Persistence

Control values are synced back to the model object. Save them:

const model = { modelPath: "/model.glb", editable: true };

// ... user adjusts controls ...

// Save state
const savedState = JSON.stringify(model);
localStorage.setItem("modelState", savedState);

// Restore state
const restored = JSON.parse(localStorage.getItem("modelState"));
<ModelRenderer model={restored} />;

Dynamic Model Loading

const [modelPath, setModelPath] = useState("/models/default.glb");

return (
  <>
    <select onChange={(e) => setModelPath(e.target.value)}>
      <option value="/models/car.glb">Car</option>
      <option value="/models/house.glb">House</option>
    </select>
    <ModelRenderer model={{ modelPath, editable: true }} />
  </>
);

Performance Tips

• Large Models: Use optimized GLTF files (draco compression recommended)
• Mobile: The component auto-disables orbit controls on small screens; consider limiting update frequency
• State Updates: The model object is synced in a useEffect; avoid creating new objects every render
• Lighting: Simplify light count for better performance on low-end devices

Browser Support

• Chrome/Edge: ✅ (WebGL 2.0+)
• Firefox: ✅ (WebGL 2.0+)
• Safari: ✅ (WebGL 2.0+)
• Mobile browsers: ✅ (WebGL 2.0+, with responsive optimizations)

CLI Commands

# Initialize component in your project
npx 3drenderer init

# Skip confirmation prompts
npx 3drenderer init -y

# Install to custom directory
npx 3drenderer init --output ./src/components

# Show help
npx 3drenderer --help

License

MIT – See LICENSE for details

Author

hema hemdan [email protected]

Repository

https://github.com/HEMA-HEMDAN/3drenderer

Issues & Support

Found a bug? Have a feature request?
Please open an issue: https://github.com/HEMA-HEMDAN/3drenderer/issue