# Instances

> Reference for <Instances>: every prop, the InstanceItem fields, the three ways to give the shape, InstancePressEvent, the InstancesHandle ref for per-frame updates, materials and shadows.

```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` |

## Related

- [Instances guide](https://matthiasbrandolin.dev/apricot/guides/instances).
- [Performance](https://matthiasbrandolin.dev/apricot/concepts/performance).