@vctrl/hooks#

Browser-side React hooks for loading, optimizing, and exporting 3D models. The runtime counterpart to @vctrl/core — built for React apps that need to handle 3D files directly in the browser.

Installation#

npm install @vctrl/hooks
# or
pnpm add @vctrl/hooks

Hooks overview#

useLoadModel#

Loads 3D files and exposes the parsed Three.js Object3D scene.

import { ModelProvider, useLoadModel } from '@vctrl/hooks/use-load-model'
 
function Uploader() {
  const { load, file, isFileLoading } = useLoadModel()
 
  const handleDrop = (e: React.DragEvent) => {
    e.preventDefault()
    void load(Array.from(e.dataTransfer.files))
  }
 
  if (isFileLoading) return <p>Loading...</p>
  if (file.model) return <p>Model loaded: {file.name}</p>
 
  return <div onDrop={handleDrop} onDragOver={(e) => e.preventDefault()}>Drop a file</div>
}
 
export default function App() {
  return (
    <ModelProvider>
      <Uploader />
    </ModelProvider>
  )
}

Context and direct usage#

useLoadModel can be used in two ways:

1. Context mode (recommended) — wrap your app with ModelProvider, then consume with useModelContext() anywhere in that tree.
2. Direct mode — call useLoadModel() outside a provider to manage a local model state.

Return values#

useLoadModel events#

on and off support these typed events:

Scene loading option types#

loadFromServer(options) uses:

loadFromData(options) uses:

useOptimizeModel#

Runs mesh simplification and texture compression using glTF-Transform in a Web Worker.

import { useOptimizeModel } from '@vctrl/hooks/use-optimize-model'
import { useLoadModel } from '@vctrl/hooks/use-load-model'
 
function Optimizer() {
  const optimizer = useOptimizeModel()
  const { file, optimizer: integrated } = useLoadModel(optimizer)
 
  const handleOptimize = async () => {
    if (!file?.model || !integrated) return
    await integrated.applyOptimization(integrated.simplifyOptimization, {
      ratio: 0.6,
      error: 0.001
    })
  }
 
  return (
    <button onClick={handleOptimize} disabled={optimizer.loading}>
      {optimizer.loading ? 'Optimizing...' : 'Optimize model'}
    </button>
  )
}

Key API surface#

Optimization option types#

useOptimizeModel methods map directly to @vctrl/core/model-optimizer option types:

serverOptions is provided by @vctrl/core and supports endpoint, API key, and headers.

useExportModel#

Exports the current scene (from ModelProvider context) to a downloadable file.

import { useExportModel } from '@vctrl/hooks/use-export-model'
import type { ModelFile } from '@vctrl/hooks/use-load-model'
 
function ExportButton({ file }: { file: ModelFile | null }) {
  const { handleThreeGltfExport } = useExportModel()
 
  return (
    <button onClick={() => void handleThreeGltfExport(file, true)}>
      Download GLB
    </button>
  )
}

Methods#

binary = true writes .glb; binary = false writes a zipped .gltf package.

Additional exports#

• ServerCommunicationService from @vctrl/hooks
• reconstructGltfFiles from @vctrl/hooks
• ModelProvider and useModelContext from @vctrl/hooks/use-load-model
• Shared types such as ModelFile, SceneLoadResult, and ServerSceneData

ServerCommunicationService methods:

ServerRequestConfig fields:

Peer dependencies#

Source#

Full source and detailed README in packages/hooks/.

Related docs#

• Uploading Models — file ingestion and bundle handling
• Optimizing & Configuring — optimization presets and behavior
• @vctrl/viewer — rendering integration target