ts
import { Instances } from "@apricot/react";
import type { InstanceItem, InstancePressEvent, InstancesHandle, InstancesProps } from "@apricot/react";Draws many copies of one shape in one draw call per part. Use it for anything repeated more than a few dozen times.
Props#
| Prop | Type | Default | Description |
|---|---|---|---|
items |
T[] where T extends InstanceItem |
required | The copies. Your own fields may ride along and come back in onPress |
geometry |
THREE.BufferGeometry |
The shape to copy… | |
object |
THREE.Object3D | null |
…or every mesh of an object, such as useModel(src).object… |
|
children |
shapes | …or the shapes inside, copied together as one. Their positions place them within each copy | |
material |
MaterialInput |
"standard" |
For every part. With object or children, parts keep their own materials unless this or color is given |
color |
colour | white when items have colours | The material's colour |
onPress |
(event: InstancePressEvent<T>) => void |
Which copy was tapped | |
name |
string | The group's name | |
visible |
boolean | true |
Hides every copy |
castShadow, receiveShadow |
boolean | automatic | With <Scene shadows> |
ref |
Ref<InstancesHandle> |
For per-frame updates |
Plus transform props, which move all copies together. Give exactly one of geometry, object or children.
InstanceItem#
| Field | Type | Default |
|---|---|---|
position |
Vec3 |
[0, 0, 0] |
rotation |
Vec3 radians |
[0, 0, 0] |
scale |
number | Vec3 |
1 |
color |
colour | none: tints this copy (multiplies the material's colour) |
visible |
boolean | true |
A new items array updates every copy on the next frame; more items than at first grow the set. For selections and state changes, pass a new array. For animation, use the handle.
InstancePressEvent<T>#
{ index, item, hit }: the copy's index in items, the item (with your fields), and the PressHit.
InstancesHandle#
| Member | Description |
|---|---|
group |
The three.js group holding the copies |
set(index, item) |
Changes one copy at once, with no React render. Call it from useFrame |