Skip to main content
rule CX Codex

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

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/rules/loading-suspense.md
Open on GitHub

What 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 useGLTF model in a Suspense boundary with a fallback
  • show scene loading progress through useProgress
  • split environment and character loading into nested boundaries
  • catch a failed .glb load and offer a retry
  • kill the fallback flash by preloading textures

Example prompts for the agent

  • Wrap the component that calls useGLTF in <Suspense> and give it a wireframe placeholder
  • Put an ErrorBoundary from react-error-boundary around the model scene
  • Preload /model.glb with useGLTF.preload so the canvas doesn't flash

How to install loading-suspense

Manually: put the files in place

.claude/rules/loading-suspense.md

The paths frontmatter field limits the files

Step 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

Similar IDE rules

All IDE rules for Frontend and UI →

From the same set86

The whole set →
tsl-material-slots tsl-material-slots is a Claude Code rule with a reference to Three.js TSL material slots. It helps write node-based shader logic without mistyping slot names or property types. CX Codex +1 ★ 4,719repo stars core-web-vitals core-web-vitals is a Claude Code rule for loading Three.js models and textures without letting heavy 3D delay first paint or degrade LCP, FID and CLS. CX Codex +1 ★ 4,719repo stars postprocessing-optimization postprocessing-optimization is a rule for Three.js and React Three Fiber that helps optimize post-processing by combining shader passes and tuning render settings. CX Codex +1 ★ 4,719repo stars timeline-builder timeline-builder is a Claude Code skill that turns JSON event data into interactive HTML timelines with vertical, horizontal, or dual-side layouts. It covers project milestones, release histories, and resumes. CX Codex +1 ★ 4,719repo stars lighting-shadows-advanced The lighting-shadows-advanced rule covers lighting and shadow settings in Three.js with rendering cost in mind. Use it when tuning a scene with several lights or shadow maps. CX Codex +1 ★ 4,719repo stars migration-checklist migration-checklist teaches the agent how to migrate code when Three.js updates. Lists breaking changes from r125 onwards and current import paths. CX Codex +1 ★ 4,719repo stars audio-spatial The audio-spatial rule for Claude Code provides Three.js 3D audio patterns for source positioning, distance falloff, and response to user interaction. CX Codex +1 ★ 4,719repo stars debug-devtools The debug-devtools rule guides an agent through adding diagnostics for Three.js performance, scene parameters, and WebGL context loss. Use it when tracking down a rendering bottleneck or inspecting a scene. CX Codex +1 ★ 4,719repo stars

Project sponsors

Companies that keep this analytics open