ReactとThree.jsで、3Dの模型を回して見せる方法
React Three Fiber(R3F)を使うと、Three.js の 3D のシーンを React のコンポーネントとして書けます。glb 形式の 3D モデルを読み込み、自動でゆっくり回しながら、ドラッグで好きな向きから見られるようにする書き方を示します。商品の 3D ビューや、作品・フィギュアの紹介ページのように、模型をぐるりと見せたい場面で使えます。
回す処理は useFrame の中で、向き(rotation.y)に「経過した秒数 × 速さ」を足すだけです。ただし、秒数(delta)を使わずに決まった量を足すと、画面を描き直す回数が多い環境ほど速く回ります。検証ではその差がはっきり出たので、数字で示します。
検証環境は Ubuntu 24.04、Node.js 22.23.4 です。three 0.187.0、@react-three/fiber 9.8.2、@react-three/drei 10.7.9、@types/three 0.187.0、react / react-dom 19.3.1、typescript 7.0.2、vite 8.3.7 を使い、tsc で型チェックしてから Vite で動かしました。ブラウザは Playwright 1.63.0 で動かした Chromium 153(ヘッドレス)だけで、WebGL は、GPU の処理をソフトウェアで代わりに行う SwiftShader(Chromium に入っているもの)で描画されました。模型は、検証用に Three.js で直方体や円柱を組み合わせて作った glb ファイルです。Firefox・Safari・実機のスマートフォン、タッチ操作、本物の GPU での描画、Next.js などでのサーバーサイドレンダリングは試していません。
three と React Three Fiber、drei を入れる
R3F は Three.js を React から使うためのライブラリで、three 本体は自分で入れます。R3F のインストールの説明では、@react-three/fiber@9 は React 19 と組み合わせるものとされています。drei は、モデルの読み込みやカメラの操作など、よく使う部品をまとめた R3F 用のライブラリです。
npm install three @react-three/fiber @react-three/drei
npm install -D @types/three
検証で使った @react-three/fiber 9.8.2 の peerDependencies は、react と react-dom が >=19 <19.4、three が >=0.156 でした。
TypeScript では、tsconfig.json に "skipLibCheck": true がないと、tsc が drei の依存パッケージ(three-stdlib 2.36.1)の型定義でエラーを出しました。
node_modules/three-stdlib/loaders/SVGLoader.d.ts(3,18): error TS2430: Interface 'SVGResultPaths' incorrectly extends interface 'ShapePath'.
node_modules/three-stdlib/loaders/TGALoader.d.ts(13,3): error TS2416: Property 'parse' in type 'TGALoader' is not assignable to the same property in base type 'DataTextureLoader'.
自分のコードではなく、three-stdlib の型定義と @types/three 0.187.0 の食い違いで起きているエラーです。"skipLibCheck": true を付けると、エラーは出なくなりました。
まず箱を1つ回してみる
モデルを読み込む前に、R3F で物を回す仕組みを、箱で確かめます。
// SpinningBox.tsx
import { useRef } from 'react';
import { Canvas, useFrame } from '@react-three/fiber';
import type { Mesh } from 'three';
function Box() {
const ref = useRef<Mesh>(null);
useFrame((_, delta) => {
if (ref.current) ref.current.rotation.y += delta;
});
return (
<mesh ref={ref} name="box" rotation={[0.4, 0, 0]}>
<boxGeometry args={[1.5, 1.5, 1.5]} />
<meshStandardMaterial color="#00c8e8" />
</mesh>
);
}
export function SpinningBox() {
return (
<div style={{ height: 300 }}>
<Canvas>
<ambientLight intensity={0.5} />
<directionalLight position={[2, 3, 4]} intensity={2} />
<Box />
</Canvas>
</div>
);
}
<Canvas> の中に書いた <mesh> は Three.js の Mesh として作られてシーンに加わり、その中の <boxGeometry> は、R3F のオブジェクトの説明のとおり、親の mesh の geometry として取り付けられます。useFrame に渡した関数は、R3F のフックの説明のとおり、画面を描く直前に毎回呼ばれます。2つ目の引数 delta は、前に描いたときからの経過時間(秒)です。
この関数の中では、ref で受け取った Three.js のオブジェクトを直接書き換えます。同じ説明には、useFrame の中で setState をしてはいけないとも書かれています。R3F のよくある落とし穴の説明によると、setState を使うと、値の更新が React のスケジューラーを通り、コンポーネントの再レンダリングまで起きてしまうためです。
検証環境で試したところ、2.011 秒で rotation.y が 2.016 増えました。Three.js の Euler の説明のとおり rotation.y の単位はラジアンなので、+= delta は「1秒に1ラジアン(約57度)」回すという意味になります。
delta を使わないと、描画の回数しだいで速さが変わる
rotation.y += 1 / 60 のように、1回の描画ごとに決まった量を足す書き方と比べました。ふつうに起動した Chromium は1秒に60回描いたので、どちらも1秒に約1ラジアンで、差はありません。ところが、Chromium を --disable-gpu-vsync --disable-frame-rate-limit を付けて起動し、描画の回数の上限を外すと、結果が分かれました。
| 書き方 | 1秒に描いた回数 | 1秒に回った角度 |
|---|---|---|
+= delta(経過時間を足す) |
329回 | 1.000 rad |
+= 1 / 60(決まった量を足す) |
321回 | 5.342 rad |
経過時間を足す書き方は、描く回数が5倍以上に増えても同じ速さで回りました。決まった量を足す書き方は、描く回数に比例して速くなっています。R3F のフックの説明によると、useFrame の関数は画面のリフレッシュレートに合わせて呼ばれます。落とし穴の説明でも、決まった値ではなく delta を使うよう勧めています。そうすればリフレッシュレートに左右されず、どの環境でも同じ速さで動きます。
glb のモデルを読み込んで回す
ここからが本題です。3D モデルを public/models/robot.glb に置き、drei の useGLTF で読み込みます。glb は、glTF の JSON とバイナリデータを1つのファイルにまとめた形式で、glTF の仕様で定められています。
// ModelViewer.tsx
import { Suspense, useRef, type RefObject } from 'react';
import { Canvas, useFrame } from '@react-three/fiber';
import { Center, OrbitControls, useGLTF } from '@react-three/drei';
import type { Group } from 'three';
const MODEL_URL = '/models/robot.glb';
function Model({ paused }: { paused: RefObject<boolean> }) {
const { scene } = useGLTF(MODEL_URL);
const turntable = useRef<Group>(null);
// 1フレームごとに呼ばれる。delta は前のフレームからの経過秒数
useFrame((_, delta) => {
if (!turntable.current || paused.current) return;
turntable.current.rotation.y += delta * 0.8; // 1秒に0.8ラジアン
});
return (
<group ref={turntable} name="turntable">
<Center>
<primitive object={scene} />
</Center>
</group>
);
}
export function ModelViewer() {
const paused = useRef(false);
return (
<div style={{ height: 400 }}>
<Canvas camera={{ position: [0, 1.5, 5], fov: 45 }}>
<ambientLight intensity={0.6} />
<directionalLight position={[3, 5, 4]} intensity={2} />
<Suspense fallback={null}>
<Model paused={paused} />
</Suspense>
<OrbitControls
enablePan={false}
minDistance={3}
maxDistance={8}
onStart={() => { paused.current = true; }}
onEnd={() => { paused.current = false; }}
/>
</Canvas>
</div>
);
}
useGLTF.preload(MODEL_URL);
コードの各部分は、次のように働きます。
useGLTF:drei のフックで、Three.js のGLTFLoaderでモデルを読み込む。戻り値のsceneが、モデル全体の入ったGroup<primitive object={scene} />:すでにある Three.js のオブジェクトを、そのままシーンに置く(R3F のオブジェクトの説明によると、同じオブジェクトを2か所に置くことはできない)<Center>:中に入れたものを包む箱(バウンディングボックス)の中心が、原点に来るようにずらす<group ref={turntable}>:回転台。モデルではなく、この入れ物を回す<Suspense>:読み込みが終わるまでfallbackを表示する。useGLTFのもとになっている R3F のuseLoaderは、読み込みが終わるまでコンポーネントをサスペンドさせる(その間は<Suspense>のfallbackが表示される)useGLTF.preload:コンポーネントが表示される前に、読み込みを始めておく
モデルを <Center> で原点に置いてから外側の group を回すので、模型は自分の中心を軸にして、その場で回ります。
読み込みの書き方は、R3F のモデルの読み込みの説明と、drei の useGLTF の説明にあるものです。検証環境で開発サーバーのページを開くと、ブラウザは /models/robot.glb を1回だけ取得し、模型が表示されて回り始めました。測ったところ、3.01 秒で turntable の rotation.y が 2.408 増え、1秒あたり 0.799 ラジアンでした。
npx vite build でビルドし、npx vite preview で開いた場合も、public/models/robot.glb は dist/models/robot.glb にコピーされ、同じように表示されました。ModelViewer だけのページをビルドすると、JavaScript は 1,228.87 kB(gzip で 337.30 kB)になり、Vite が「500 kB を超えるチャンクがある」と警告しました。
drei の説明によると、useGLTF は既定で、Draco で圧縮されたモデルを展開するデコーダーを https://www.gstatic.com/draco/v1/decoders/ から読み込みます。読み込むのは圧縮されたモデルを開くときだけ、とされています。検証で使った glb は圧縮していないもので、gstatic への通信は起きませんでした。
ドラッグで見回す間は、自動の回転を止める
drei の <OrbitControls> を置くと、ドラッグでカメラを模型のまわりに動かし、ホイールで寄ったり離れたりできます。中身は、drei が使っている three-stdlib というパッケージの OrbitControls です。three-stdlib は、Three.js の examples にあるコードを単独のライブラリとしてまとめたものです。
見たい向きでじっくり見られるように、操作している間は自動の回転を止め、操作が終わったら再び回します。three-stdlib の OrbitControls は、元になった Three.js の OrbitControls と同じく、操作の始まりに start、終わりに end のイベントを出します。drei の <OrbitControls> では、それぞれ onStart と onEnd で受け取れます。
止めているかどうかは、useState ではなく useRef で持ちます。useFrame の中で毎回読むだけの値なので、変わるたびに再レンダリングする必要がありません。

検証環境で、模型の上でマウスのボタンを押してドラッグし、押したまま1秒待ったところ、rotation.y は 5.129 のまま変わりませんでした。ボタンを離してから1秒後には 5.929 になり、0.800 増えていました。上の GIF のように、ドラッグの間は見る向きだけが変わり、模型自体は回りません。
ほかの props の働きも確かめました。
minDistance={3}とmaxDistance={8}:ホイールで寄り続けるとカメラと中心の距離は 3.000 で止まり、離れ続けると 8.000 で止まった(最初は 5.220)enablePan={false}:右ボタンでドラッグしても、カメラの位置は変わらなかった
enablePan は、カメラを上下左右に平行移動する操作を許すかどうかの設定で、既定は true です。模型を回して見せるだけなら平行移動は使わないので、今回は無効にしました。
真っ黒になるとき、高さが足りないとき
光を置かないと、模型が真っ黒になる
<ambientLight> と <directionalLight> を置かずに同じ模型を描くと、真っ黒な影絵のようになりました。今回の glb のマテリアルは、Three.js の MeshStandardMaterial として読み込まれていました。Three.js のリファレンスで「物理ベース」と説明されているマテリアルです。光が1つもないシーンでは、水色やピンクの色を付けた部分も黒く描かれました。

Three.js のリファレンスによると、AmbientLight(<ambientLight>)はシーンのすべての物を同じように照らす光、DirectionalLight(<directionalLight>)は太陽の光のように、決まった方向から平行に差す光です。今回は2つを組み合わせました。
Canvas の親に高さがないと、150px になる
<Canvas> は、親の要素の大きさに合わせて広がります。高さ 300px の div に置いた箱の例では、canvas も幅 768px・高さ 300px になりました。ところが、親の div に高さを付けずに置くと、canvas の高さは 150px になりました(幅は 768px)。150px は、MDN の canvas 要素の説明にある、高さの既定値と同じです。模型を大きく見せたいときは、上のコードの style={{ height: 400 }} のように、親に高さを付けます。
THREE.Clock の警告が出る
検証の間、ブラウザのコンソールに次の警告が出ました。
THREE.Clock: This module has been deprecated. Please use THREE.Timer instead.
three は r183 から THREE.Clock を非推奨にしていて、@react-three/fiber 9.8.2 が内部で new THREE.Clock() を作っているために出る警告です。記事のコードは THREE.Clock を使っていません。この警告が出ている状態で、ここまでに書いた動きはすべて確かめました。





