Skip to main content
rule CX Codex

perf-visibility-toggle — Claude Code rule: what it does and install

perf-visibility-toggle guides the AI to toggle the visible prop on Three.js components rather than conditionally unmounting them, avoiding GPU shader recompilation.

MIT ★ 4,719 updated 2026-10-24

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

What perf-visibility-toggle does

The rule instructs coding assistants to prefer visible={showModel} over conditional rendering patterns like {showModel && <ExpensiveModel />} in React Three.js scenes. When React unmounts and remounts 3D components, Three.js destroys existing objects, recreates geometries and materials, re-uploads buffers to GPU memory, and recompiles shaders.

Toggling visible leaves the mesh resident in memory while the renderer skips it during the draw pass. The rule also covers direct property mutation on mesh references inside useFrame for smoother animation loops, along with Three.js camera layers for selective view rendering.

Unmounting components remains recommended only under tight memory budgets or when objects appear rarely in the scene.

What it helps with

  • stop shader recompilations caused by toggling Three.js meshes
  • keep 3D geometry in GPU memory during frequent show and hide cycles
  • mutate visibility flags directly in useFrame using component refs
  • isolate objects across different cameras with Three.js layers

Example prompts for the agent

  • Refactor our 3D scene toggles to use the visible prop instead of conditional mounts
  • Optimize mesh visibility changes inside the useFrame animation loop
  • Set up Three.js layers on this model for camera-specific rendering

How to install perf-visibility-toggle

Manually: put the files in place

.claude/rules/perf-visibility-toggle.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 perf-visibility-toggle

How to install perf-visibility-toggle in Claude Code?

Save the rule file to .claude/rules/perf-visibility-toggle.md in your project repository.

What does perf-visibility-toggle do?

It directs AI coding agents to toggle component visibility in Three.js instead of unmounting, preventing expensive GPU buffer reallocations.

When should conditional mounting still be used?

Conditional mounting is preferred when memory is tightly constrained, the scene has numerous objects, or a model appears infrequently.

Source text

perf-visibility-toggle.md · MIT
# Toggle Visibility Instead of Remounting

> Source: [100 Three.js Tips - Utsubo](https://www.utsubo.com/blog/threejs-best-practices-100-tips)

Toggle the `visible` prop instead of conditionally mounting/unmounting components.

## Why It Matters

Remounting a component:
1. Destroys the Three.js object
2. Triggers disposal (if configured)
3. Creates new geometry/material
4. Uploads new data to GPU
5. Recompiles shaders

Toggling visibility:
1. Sets `object.visible = false`
2. That's it - object stays in memory

## BAD: Conditional Mounting

```jsx
function Scene({ showModel }) {
  return (
    <>
      {showModel && <ExpensiveModel />}
    </>
  );
}
```

Every toggle destroys and recreates the entire model.

## GOOD: Visibility Toggle

```jsx
function Scene({ showModel }) {
  return (
    <ExpensiveModel visible={showModel} />
  );
}
```

Model stays in memory, just skipped during render.

## When to Use Each

### Use Visibility Toggle When:
- Frequent show/hide (e.g., UI state)
- Object is expensive to create
- Object is needed again soon
- Object count is manageable

### Use Conditional Mounting When:
- Object is rarely shown
- Memory is constrained
- Object is cheap to create
- Large number of potential objects

## With Refs

```jsx
function ToggleableModel() {
  const meshRef = useRef();
  const [visible, setVisible] = useState(true);

  // Direct mutation for animations
  useFrame(() => {
    if (meshRef.current) {
      meshRef.current.visible = shouldBeVisible;
    }
  });

  return <mesh ref={meshRef} visible={visible} />;
}
```

## Visibility vs Layers

For complex visibility logic, consider using Three.js layers:

```jsx
function SelectiveRendering() {
  const meshRef = useRef();

  useEffect(() => {
    // Set to layer 1 (not rendered by default camera)
    meshRef.current.layers.set(1);
  }, []);

  return <mesh ref={meshRef} />;
}
```

Layers allow camera-selective rendering without changing visibility.

© zebbern · MIT · zebbern/claude-code-guide

Similar IDE rules

All IDE rules for Game dev and 3D: Unity, Unreal, Godot, Blender →

From the same set86

The whole set →
render-delta-time render-delta-time instructs agents to use delta time in animation loops so motion remains consistent across all display refresh rates. CX Codex +1 ★ 4,719repo stars memory-dispose-geometry memory-dispose-geometry is a Claude Code rule that tells the agent to release geometry when removing scene objects. It applies to Three.js resource cleanup. CX Codex +1 ★ 4,719repo stars root-cause-debugger The root-cause-debugger subagent for Claude Code and Codex reproduces failures and finds bug root causes before code changes. It helps diagnose bugs without editing code. CX Codex ★ 4,719repo stars code-reviewer code-reviewer is a Claude Code subagent that checks completed work for bugs and regressions. It runs after implementation or when an existing diff needs review. CX Codex ★ 4,719repo stars perf-r3f-perf The perf-r3f-perf rule teaches Claude Code about r3f-perf, a performance monitoring library for Three.js scenes in real time. Spot frame drops, memory leaks, and unnecessary matrix recalculations as they happen. CX Codex +1 ★ 4,719repo stars codebase-mapper codebase-mapper maps repository structure, call chains, and data flows before code changes without mutating any files. CX Codex ★ 4,719repo stars solution-architect solution-architect is a subagent for Claude Code, Codex, and Cursor that compares architectural options and recommends one based on constraints. It is used when requirements are set but several designs are viable. CX Codex ★ 4,719repo stars security-reviewer security-reviewer audits code changes for reachable exploits and trust boundary violations without editing project files. CX Codex ★ 4,719repo stars

Project sponsors

Companies that keep this analytics open