R3F Object Controls

A lightweight custom rotation control component for React Three Fiber.
Supports smooth mouse and touch rotation with optional OrbitControls integration.

• ThreeJS orbit controls were designed to make the camera orbit around a target in your scene. This is ideal for exploring a scene from different angles while keeping a central point in focus.
• In contrast, our R3F object controls allow you to rotate the target object itself within the scene. This is perfect when you want to directly manipulate and inspect a specific 3D model.

Demo

Demo Page

Installation

npm install r3f-object-controls
# or
yarn add r3f-object-controls

Features

• 🎯 Rotate only when clicking/tapping on the object
• 🌀 Smooth, damped rotation
• 🔒 Clamp X-axis rotation within a custom range
• 🔄 Works alongside OrbitControls (disables Orbit during drag)
• 🖱️ Mouse + 📱 Touch support
• ✅ Plug-and-play React component

Screenshot

Orbit Controls Demo

Object Controls Demo

Usage

import { ObjectControls } from "r3f-object-controls";
import { Canvas } from "@react-three/fiber";
import { OrbitControls } from "@react-three/drei";
import { useRef } from "react";
import { Mesh } from "three";

export default function Scene() {
  const objectRef = useRef<Mesh>(null);
  const orbitRef = useRef<any>(null);

  return (
    <Canvas>
      <ambientLight />
      <OrbitControls ref={orbitRef} />
      <mesh ref={objectRef}>
        <boxGeometry />
        <meshStandardMaterial color="orange" />
      </mesh>

      <ObjectControls
        object={objectRef}
        orbitControl={orbitRef}
        dampingFactor={0.1}
        maxRotationX={Math.PI / 2}
        minRotationX={-Math.PI / 2}
        enableXRotation={true}
        enableYRotation={true}
      />
    </Canvas>
  );
}

Props

| Prop | Type | Default | Description | | ----------------- | ----------------------- | -------------- | ------------------------------------------------------------- | | object | React.RefObject<Mesh> | Required | The mesh object to apply rotation controls to | | orbitControl | React.RefObject<any> | undefined | Reference to OrbitControls to auto-disable during interaction | | dampingFactor | number | 0.1 | How smoothly the rotation transitions (0 to 1) | | maxRotationX | number | Math.PI / 2 | Maximum X-axis rotation (in radians) | | minRotationX | number | -Math.PI / 2 | Minimum X-axis rotation (in radians) | | enableXRotation | boolean | true | Enable rotation along the X-axis | | enableYRotation | boolean | true | Enable rotation along the Y-axis |

How It Works

• Uses Raycaster to detect if the pointer is on the mesh.
• On drag (mouse or touch), calculates delta movement.
• Applies smoothed rotation to the object using MathUtils.lerp.
• While interacting, OrbitControls (if present) are disabled.

Example

<ObjectControls
  object={meshRef}
  orbitControl={orbitRef}
  dampingFactor={0.15}
  maxRotationX={Math.PI / 3}
  minRotationX={-Math.PI / 3}
  enableXRotation={true}
  enableYRotation={false}
/>

Mobile Support

Fully touch-optimized:

• One-finger drag rotates the object.
• Prevents page scroll while touching the object.

License

MIT © [Craftpixels]