r3f-geometry

React Three Fiber geometry

Inspect installed Three.js, Fiber, and Drei versions before copying constructor arguments or helper props. Examples target Fiber 9 / React 19 and Three.js r185.

Choose the representation

• Use native JSX geometry for ordinary shapes. args match the Three.js constructor; changing them reconstructs geometry, so animate transforms rather than constructor inputs.
• Use BufferGeometry for custom topology and buffer-based points for large particle sets. Keep generated arrays stable and use deterministic generation when results must be reproducible.
• Use Drei Instances for convenient declarative instances with events. For large or frequently updated sets, read native instancing to avoid per-instance React overhead.
• Instancing shares geometry/material and reduces draw calls. Merely sharing a geometry among separate meshes does not batch their draws.
• Drei Merged creates instancing abstractions from meshes, not BufferGeometry objects; it does not concatenate arbitrary static geometry. For actual merging, inspect mergeGeometries from three/addons/utils/BufferGeometryUtils.js and ensure compatible attributes/indexing.

Declarative instances

Mount below Canvas with lighting. Each Instance belongs to its nearest Instances provider.

import { Instance, Instances } from '@react-three/drei'

export default function Example() { return ( <boxGeometry args={[0.7, 0.7, 0.7]} /> <Instance position={[-1.2, 0, 0]} color="coral" /> <Instance position={[0, 0, 0]} color="skyblue" /> <Instance position={[1.2, 0, 0]} color="gold" /> ) }

## Custom buffers and updates

- `position` and `normal` attributes usually have item size 3; UVs have item size 2. Construct JSX buffer attributes with `args={[typedArray, itemSize]}` and the correct `attach`, not just `array`/`count` props with no constructor arguments.
- Indices refer to vertices; winding determines the front face. Duplicate vertices at hard normals or UV seams. Indexed vertices share all attributes, not just positions.
- Lit geometry needs normals. Use `computeVertexNormals()` when appropriate; do not recompute every frame if a shader or analytic normals can express the deformation more cheaply.
- After CPU buffer writes, set `attribute.needsUpdate = true`. Choose dynamic usage before the first GPU upload when buffers will change often.
- Recompute bounding boxes/spheres after geometry changes that affect them. GPU vertex displacement does not update CPU bounds or raycasting automatically.
- UV selection is explicit on modern Three.js: `texture.channel` selects `uv`, `uv1`, `uv2`, or `uv3`. Do not unconditionally copy `uv` into `uv2` for AO.
- Avoid rebuilding buffers for pointer movement. If topology is fixed, change attribute contents or uniforms instead.

## Helpers and tradeoffs

- Drei `Line` supports useful line widths; native WebGL line width is limited by the platform. Check `worldUnits` when choosing screen-space versus world-space thickness.
- Use Drei `Text` for flat text and `Text3D` for extruded geometry. Current TextGeometry uses `depth`, not the historical `height`; verify the helper's installed types and font format.
- Use `Edges` for sharp-edge outlines, not as a replacement for screen-space selection effects.
- `Bounds` and `Center` change framing/transforms; decide whether they should update after asset loading, resizing, or interaction.
- Segment count should follow silhouette, deformation, and viewing distance. A “high quality” fixed count is not universally better.
- Declaratively created geometry can be owned by R3F. Shared or cached geometry needs a shared lifetime; do not dispose it from one instance while others remain mounted.

## Verify

Check bounds/culling after updates, raycast hit positions, resource cleanup, and draw calls. Test at the intended object count; three instances do not establish performance at ten thousand.

## Sources

- [BufferGeometry](https://threejs.org/docs/#BufferGeometry), [BufferAttribute](https://threejs.org/docs/#BufferAttribute), [InstancedMesh](https://threejs.org/docs/#InstancedMesh).
- [Drei Instances](https://drei.docs.pmnd.rs/performances/instances), [Merged](https://drei.docs.pmnd.rs/performances/merged), [Text3D](https://drei.docs.pmnd.rs/abstractions/text3d).