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
.claude/rules/perf-visibility-toggle.mdWhat 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
useFrameusing 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.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/perf-visibility-toggle.mdcFrontmatter: description, globs, alwaysApply
Manually: put the files in place
.github/instructions/perf-visibility-toggle.instructions.mdThe applyTo field sets which files it applies to
Manually: put the files in place
.devin/rules/perf-visibility-toggle.mdManually: put the files in place
.clinerules/perf-visibility-toggle.mdStep 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