tessl/npm-react-three--drei

Useful add-ons for react-three-fiber providing 100+ components for 3D web applications

—

Pending

Overview

Eval results

Files

Controls

Name: tessl/npm-react-three--drei
Author: tessl

Camera and interaction controls for navigating and manipulating 3D scenes. All control components integrate with React Three Fiber's camera system and provide smooth, configurable interaction patterns.

Capabilities

OrbitControls

Orbit camera controls for rotating around a target point, with support for zooming, panning, and damping.

/**
 * Orbit camera controls for rotating around a target
 * @param props - Orbit controls configuration
 * @returns JSX element for the controls
 */
function OrbitControls(props: OrbitControlsProps): JSX.Element;

interface OrbitControlsProps extends Omit<ThreeElement<OrbitControlsImpl>, 'ref' | 'args'> {
  /** Makes this the default controls, false */
  makeDefault?: boolean;
  /** The camera to control */
  camera?: Camera;
  /** DOM element for event listeners */
  domElement?: HTMLElement;
  /** Enable damping (inertia), false */
  enableDamping?: boolean;
  /** Damping factor, 0.05 */
  dampingFactor?: number;
  /** Enable zoom, true */
  enableZoom?: boolean;
  /** Zoom speed, 1 */
  zoomSpeed?: number;
  /** Enable rotation, true */
  enableRotate?: boolean;
  /** Rotation speed, 1 */
  rotateSpeed?: number;
  /** Enable panning, true */
  enablePan?: boolean;
  /** Pan speed, 1 */
  panSpeed?: number;
  /** Auto-rotate, false */
  autoRotate?: boolean;
  /** Auto-rotate speed, 2 */
  autoRotateSpeed?: number;
  /** Minimum polar angle, 0 */
  minPolarAngle?: number;
  /** Maximum polar angle, Math.PI */
  maxPolarAngle?: number;
  /** Minimum azimuth angle */
  minAzimuthAngle?: number;
  /** Maximum azimuth angle */
  maxAzimuthAngle?: number;
  /** Minimum zoom distance, 0 */
  minDistance?: number;
  /** Maximum zoom distance, Infinity */
  maxDistance?: number;
  /** Target position */
  target?: Vector3;
  /** Change event handler */
  onChange?: (e?: OrbitControlsChangeEvent) => void;
  /** Start event handler */
  onStart?: (e?: OrbitControlsChangeEvent) => void;
  /** End event handler */
  onEnd?: (e?: OrbitControlsChangeEvent) => void;
}

interface OrbitControlsChangeEvent {
  target: OrbitControlsImpl;
  type: 'change' | 'start' | 'end';
}

Usage Examples:

import { OrbitControls } from '@react-three/drei';

// Basic orbit controls
<OrbitControls enableDamping />

// Advanced orbit controls with constraints
<OrbitControls
  enableDamping
  dampingFactor={0.1}
  minDistance={2}
  maxDistance={20}
  minPolarAngle={Math.PI / 6}
  maxPolarAngle={Math.PI - Math.PI / 6}
  autoRotate
  autoRotateSpeed={0.5}
  onChange={(e) => console.log('Controls changed', e)}
/>

TransformControls

Interactive transformation gizmo for translating, rotating, and scaling objects in 3D space.

/**
 * Transform gizmo for object manipulation
 * @param props - Transform controls configuration
 * @returns JSX element for the transform controls
 */
function TransformControls(props: TransformControlsProps): JSX.Element;

interface TransformControlsProps extends Omit<ThreeElement<TransformControlsImpl>, 'ref' | 'args'> {
  /** Object to transform */
  object?: Object3D;
  /** The camera to use */
  camera?: Camera;
  /** DOM element for events */
  domElement?: HTMLElement;
  /** Control mode: 'translate' | 'rotate' | 'scale' */
  mode?: 'translate' | 'rotate' | 'scale';
  /** Transform space: 'world' | 'local' */
  space?: 'world' | 'local';
  /** Control size, 1 */
  size?: number;
  /** Show X axis, true */
  showX?: boolean;
  /** Show Y axis, true */
  showY?: boolean;
  /** Show Z axis, true */
  showZ?: boolean;
  /** Enable translation, true */
  translationSnap?: number;
  /** Enable rotation snap */
  rotationSnap?: number;
  /** Enable scale snap */
  scaleSnap?: number;
  /** Dragging event handler */
  onDragging?: (dragging: boolean) => void;
  /** Change event handler */
  onChange?: () => void;
  /** Mouse down event handler */
  onMouseDown?: () => void;
  /** Mouse up event handler */
  onMouseUp?: () => void;
}

Usage Examples:

import { TransformControls } from '@react-three/drei';

// Basic transform controls
function TransformableBox() {
  const boxRef = useRef();
  
  return (
    <>
      <mesh ref={boxRef}>
        <boxGeometry />
        <meshStandardMaterial />
      </mesh>
      <TransformControls object={boxRef.current} />
    </>
  );
}

// Transform controls with constraints
<TransformControls
  object={objectRef.current}
  mode="translate"
  space="world"
  size={1.5}
  showZ={false}
  translationSnap={0.5}
  onDragging={(dragging) => {
    // Disable orbit controls while dragging
    orbitControlsRef.current.enabled = !dragging;
  }}
/>

CameraControls

Advanced camera controls with smooth transitions, focus functionality, and programmatic animation.

/**
 * Advanced camera controls with smooth transitions
 * @param props - Camera controls configuration
 * @returns JSX element for the camera controls
 */
function CameraControls(props: CameraControlsProps): JSX.Element;

interface CameraControlsProps extends Omit<ThreeElement<CameraControlsImpl>, 'ref' | 'args'> {
  /** Makes this the default controls, false */
  makeDefault?: boolean;
  /** The camera to control */
  camera?: Camera;
  /** DOM element for events */
  domElement?: HTMLElement;
  /** Smooth time for transitions, 0.25 */
  smoothTime?: number;
  /** Enable smooth dragging, true */
  smoothTime?: number;
  /** Drag smooth time, 0.25 */
  draggingSmoothTime?: number;
  /** Maximum speed, Infinity */
  maxSpeed?: number;
  /** Azimuth rotation speed, 1 */
  azimuthRotateSpeed?: number;
  /** Polar rotation speed, 1 */
  polarRotateSpeed?: number;
  /** Dolly speed, 1 */
  dollySpeed?: number;
  /** Truck speed, 2 */
  truckSpeed?: number;
  /** Enable dolly, true */
  dollyToCursor?: boolean;
  /** Dolly damping factor, 0.01 */
  dollyDragInverted?: boolean;
  /** Change event handler */
  onChange?: (e?: any) => void;
}

type CameraControls = CameraControlsImpl;

Usage Examples:

import { CameraControls } from '@react-three/drei';

// Basic camera controls
<CameraControls makeDefault />

// Camera controls with smooth transitions
<CameraControls
  smoothTime={0.5}
  maxSpeed={10}
  azimuthRotateSpeed={0.3}
  polarRotateSpeed={0.3}
  dollySpeed={0.5}
  truckSpeed={1}
/>

// Programmatic camera animation
function AnimatedCameraControls() {
  const controlsRef = useRef();
  
  const focusOnObject = () => {
    controlsRef.current?.fitToBox(boxRef.current, true);
  };
  
  return (
    <>
      <CameraControls ref={controlsRef} />
      <button onClick={focusOnObject}>Focus on Object</button>
    </>
  );
}

MapControls

Map-style controls optimized for top-down navigation, commonly used for architectural visualizations and map interfaces.

/**
 * Map-style controls for top-down navigation
 * @param props - Map controls configuration
 * @returns JSX element for the map controls
 */
function MapControls(props: MapControlsProps): JSX.Element;

interface MapControlsProps extends Omit<ThreeElement<MapControlsImpl>, 'ref' | 'args'> {
  /** Makes this the default controls, false */
  makeDefault?: boolean;
  /** The camera to control */
  camera?: Camera;
  /** DOM element for events */
  domElement?: HTMLElement;
  /** Enable screen space panning, true */
  screenSpacePanning?: boolean;
  /** Enable damping, false */
  enableDamping?: boolean;
  /** Damping factor, 0.05 */
  dampingFactor?: number;
  /** Enable zoom, true */
  enableZoom?: boolean;
  /** Zoom speed, 1 */
  zoomSpeed?: number;
  /** Enable rotation, true */
  enableRotate?: boolean;
  /** Rotation speed, 1 */
  rotateSpeed?: number;
  /** Enable panning, true */
  enablePan?: boolean;
  /** Pan speed, 1 */
  panSpeed?: number;
  /** Keyboard pan speed, 7 */
  keyPanSpeed?: number;
  /** Minimum zoom distance, 0 */
  minDistance?: number;
  /** Maximum zoom distance, Infinity */
  maxDistance?: number;
  /** Target position */
  target?: Vector3;
}

TrackballControls

Trackball-style controls providing unconstrained rotation around the scene center.

/**
 * Trackball controls for unconstrained rotation
 * @param props - Trackball controls configuration
 * @returns JSX element for the trackball controls
 */
function TrackballControls(props: TrackballControlsProps): JSX.Element;

interface TrackballControlsProps extends Omit<ThreeElement<TrackballControlsImpl>, 'ref' | 'args'> {
  /** The camera to control */
  camera?: Camera;
  /** DOM element for events */
  domElement?: HTMLElement;
  /** Rotation speed, 1 */
  rotateSpeed?: number;
  /** Zoom speed, 1.2 */
  zoomSpeed?: number;
  /** Pan speed, 0.3 */
  panSpeed?: number;
  /** No rotate, false */
  noRotate?: boolean;
  /** No zoom, false */
  noZoom?: boolean;
  /** No pan, false */
  noPan?: boolean;
  /** Static moving, false */
  staticMoving?: boolean;
  /** Dynamic damping factor, 0.2 */
  dynamicDampingFactor?: number;
  /** Minimum distance, 0 */
  minDistance?: number;
  /** Maximum distance, Infinity */
  maxDistance?: number;
}

PointerLockControls

First-person pointer lock controls for immersive camera navigation.

/**
 * First-person pointer lock controls
 * @param props - Pointer lock controls configuration
 * @returns JSX element for the pointer lock controls
 */
function PointerLockControls(props: PointerLockControlsProps): JSX.Element;

interface PointerLockControlsProps extends Omit<ThreeElement<PointerLockControlsImpl>, 'ref' | 'args'> {
  /** The camera to control */
  camera?: Camera;
  /** DOM element for events */
  domElement?: HTMLElement;
  /** Minimum polar angle, 0 */
  minPolarAngle?: number;
  /** Maximum polar angle, Math.PI */
  maxPolarAngle?: number;
  /** Pointer speed, 1 */
  pointerSpeed?: number;
  /** Lock event handler */
  onLock?: () => void;
  /** Unlock event handler */
  onUnlock?: () => void;
  /** Change event handler */
  onChange?: (e?: any) => void;
}

ArcballControls

Arcball controls providing intuitive 3D rotation with visual feedback.

/**
 * Arcball controls for intuitive 3D rotation
 * @param props - Arcball controls configuration
 * @returns JSX element for the arcball controls
 */
function ArcballControls(props: ArcballControlsProps): JSX.Element;

interface ArcballControlsProps extends Omit<ThreeElement<ArcballControlsImpl>, 'ref' | 'args'> {
  /** The camera to control */
  camera?: Camera;
  /** DOM element for events */
  domElement?: HTMLElement;
  /** Cursor radius, 1 */
  cursorZoom?: boolean;
  /** Adjust near and far planes, false */
  adjustNearFar?: boolean;
  /** Scale factor, 1 */
  scaleFactor?: number;
  /** Damping factor, 20 */
  dampingFactor?: number;
  /** Enable animations, false */
  enableAnimations?: boolean;
  /** Enable grid, false */
  enableGrid?: boolean;
  /** Enable zoom, true */
  enableZoom?: boolean;
  /** Enable rotate, true */
  enableRotate?: boolean;
  /** Enable pan, true */
  enablePan?: boolean;
}

Integration Patterns

Making Controls Default

Any control can be made the default for the scene:

// These controls will be used by other components that need controls
<OrbitControls makeDefault enableDamping />

Combining Controls with Cameras

Controls automatically work with the default camera or can target specific cameras:

<PerspectiveCamera makeDefault position={[0, 0, 5]} />
<OrbitControls /> // Uses the default camera

// Or specify a camera explicitly
<OrbitControls camera={customCameraRef.current} />

Disabling Controls Temporarily

Controls can be disabled during interactions:

function InteractiveScene() {
  const [controlsEnabled, setControlsEnabled] = useState(true);
  
  return (
    <>
      <OrbitControls enabled={controlsEnabled} />
      <TransformControls
        object={objectRef.current}
        onDragging={setControlsEnabled}
      />
    </>
  );
}

Event Handling

Controls provide comprehensive event handling:

<OrbitControls
  onChange={(e) => console.log('Camera changed')}
  onStart={(e) => console.log('Interaction started')}
  onEnd={(e) => console.log('Interaction ended')}
/>

Install with Tessl CLI