loading-suspense — Claude Code rule: Suspense for R3F async loads
loading-suspense — a rule that keeps async React Three Fiber components inside Suspense, so a model still downloading doesn't leave the canvas blank.
MIT ★ 4,719 updated 2026-10-24
.claude/rules/loading-suspense.mdWhat loading-suspense does
Written for scenes built with React Three Fiber. Any component pulling assets through useGLTF or useTexture suspends while the file travels over the network, so it needs a Suspense boundary and something to show meanwhile. The rule spells that out with copyable examples.
Inside are snippets for the common shapes: a canvas wrapping one model, several async pieces sharing a single boundary, and nested boundaries where the environment resolves on its own while the character keeps a visible loader. The progress bar comes from useProgress in @react-three/drei, which exposes active, progress and item.
Failures get their own layer: an ErrorBoundary from react-error-boundary sits outside the Suspense tree and offers a retry button. That package has to be a dependency, because React itself doesn't export ErrorBoundary. Preloading at module scope with useGLTF.preload('/model.glb') is the other trick: once the asset sits in cache, the component renders straight away.
What it helps with
- wrap a
useGLTFmodel in a Suspense boundary with a fallback - show scene loading progress through
useProgress - split environment and character loading into nested boundaries
- catch a failed
.glbload and offer a retry - kill the fallback flash by preloading textures
Example prompts for the agent
- Wrap the component that calls
useGLTFin<Suspense>and give it a wireframe placeholder - Put an
ErrorBoundaryfromreact-error-boundaryaround the model scene - Preload
/model.glbwithuseGLTF.preloadso the canvas doesn't flash
How to install loading-suspense
Manually: put the files in place
.claude/rules/loading-suspense.mdThe paths frontmatter field limits the files
AGENTS.md
Codex reads AGENTS.md: paste the rule text there
Manually: put the files in place
.cursor/rules/loading-suspense.mdcFrontmatter: description, globs, alwaysApply
Manually: put the files in place
.github/instructions/loading-suspense.instructions.mdThe applyTo field sets which files it applies to
Manually: put the files in place
.devin/rules/loading-suspense.mdManually: put the files in place
.clinerules/loading-suspense.mdStep by step, with commands for each platform: AGENTS.md vs CLAUDE.md: what they are and which one to use
Questions about loading-suspense
How do I install loading-suspense in Claude Code?
Copy the rule file to .claude/rules/loading-suspense.md. It loads from there.
What does loading-suspense do?
It tells the agent to keep async R3F components inside a Suspense boundary with a fallback, and ships examples for loaders, nesting and errors.
Do I need react-error-boundary?
Only for the error-handling part: the example imports ErrorBoundary from that package, so add it to your dependencies if you want the retry fallback.
Source text
loading-suspense.md · MIT
# loading-suspense
**Wrap async components in Suspense.**
## Why It Matters
R3F integrates with React Suspense for loading states. Components using `useGLTF`, `useTexture`, or other async loaders will suspend and need a Suspense boundary with a fallback.
## Basic Example
```jsx
import { Suspense } from 'react';
import { Canvas } from '@react-three/fiber';
import { useGLTF } from '@react-three/drei';
function Model() {
const { scene } = useGLTF('/model.glb');
return <primitive object={scene} />;
}
function App() {
return (
<Canvas>
<Suspense fallback={<LoadingFallback />}>
<Model />
</Suspense>
</Canvas>
);
}
function LoadingFallback() {
return (
<mesh>
<boxGeometry />
<meshBasicMaterial wireframe color="white" />
</mesh>
);
}
```
## Multiple Async Components
```jsx
function Scene() {
return (
<Suspense fallback={<Loader />}>
<Environment preset="city" />
<Model url="/character.glb" />
<Ground />
</Suspense>
);
}
```
## Nested Suspense Boundaries
```jsx
function Scene() {
return (
<>
{/* Environment loads first */}
<Suspense fallback={null}>
<Environment preset="sunset" />
</Suspense>
{/* Main content with visible loader */}
<Suspense fallback={<Loader />}>
<Character />
<Props />
</Suspense>
{/* Background loads last, no blocking */}
<Suspense fallback={null}>
<BackgroundDetails />
</Suspense>
</>
);
}
```
## Using useProgress
```jsx
import { useProgress, Html } from '@react-three/drei';
function Loader() {
const { active, progress, errors, item, loaded, total } = useProgress();
return (
<Html center>
<div className="loader">
<div className="progress-bar">
<div
className="progress-fill"
style={{ width: `${progress}%` }}
/>
</div>
<p>{progress.toFixed(0)}% loaded</p>
<p className="loading-item">{item}</p>
</div>
</Html>
);
}
function App() {
return (
<Canvas>
<Suspense fallback={<Loader />}>
<Scene />
</Suspense>
</Canvas>
);
}
```
## Error Boundaries
```jsx
import { ErrorBoundary } from 'react-error-boundary';
function ModelErrorFallback({ error, resetErrorBoundary }) {
return (
<Html center>
<div>
<p>Failed to load model</p>
<button onClick={resetErrorBoundary}>Try again</button>
</div>
</Html>
);
}
function SafeModel({ url }) {
return (
<ErrorBoundary
FallbackComponent={ModelErrorFallback}
onReset={() => {
// Reset any state if needed
}}
>
<Suspense fallback={<LoadingBox />}>
<Model url={url} />
</Suspense>
</ErrorBoundary>
);
}
```
## Preloading to Avoid Suspense
```jsx
import { useGLTF, useTexture } from '@react-three/drei';
// Preload at module level
useGLTF.preload('/model.glb');
useTexture.preload('/texture.png');
// Component won't suspend if already loaded
function Model() {
const { scene } = useGLTF('/model.glb'); // Instant if preloaded
return <primitive object={scene} />;
}
```
## Animated Fallback
```jsx
function AnimatedLoader() {
const meshRef = useRef();
useFrame((state) => {
meshRef.current.rotation.x = state.clock.elapsedTime;
meshRef.current.rotation.y = state.clock.elapsedTime * 0.5;
});
return (
<mesh ref={meshRef}>
<icosahedronGeometry args={[1, 1]} />
<meshBasicMaterial wireframe color="cyan" />
</mesh>
);
}
```
## References
- [React Suspense](https://react.dev/reference/react/Suspense)
- [Drei useProgress](https://github.com/pmndrs/drei#useprogress)
© zebbern · MIT · zebbern/claude-code-guide