Hooks

import { useAnimatable, useAttach, useFrame, useParent, useScene, useSceneTouches, useTransform } from "@apricot/react";

Index#

useScene#

Returns the closest scene's ApricotScene: invalidate(), camera, scene, size, onResize(), ready, onReady(), report(), threeRenderer. Throws outside <Scene>. See Scene reference.

Call invalidate() after changing three.js objects outside useFrame (in an event handler, a timer) when frameloop="demand".

useFrame#

useFrame((state: { time: number; delta: number; frame: number }) => boolean | undefined)

Runs the callback before every rendered frame. time is seconds since the loop started; delta is seconds since the previous frame, capped at 0.1 (so a pause does not make objects jump); frame counts rendered frames.

Return true while animating, to keep the scene rendering; return false (or nothing) to let it sleep until something else changes. The callback can change between renders without re-subscribing.

useAnimatable#

const read = useAnimatable(value); // value: T | SharedValue<T>
useFrame(() => { const now = read(); … });

Returns a reader for a prop that is a plain value or a Reanimated shared value (including useDerivedValue). Shared values are mirrored from the UI thread without blocking it, and every change wakes the scene. A new plain value wakes it too. Use it to make your own components' props accept shared values, the way Apricot's do.

type Animatable<T> = T | DerivedValue<T>.

useSceneTouches#

useSceneTouches(listener: SceneTouchListener, active = true)

Receives the fingers on the enclosing scene while active; the scene then claims touches that start on it (drags stop reaching views behind it). Taps on objects keep working.

useParent and useAttach#

useParent() returns the three.js object new children attach to: the scene root or the closest <Group>, shape, model or behavior. useAttach(object) adds object to it while the component is mounted, requests a frame and warms up its shaders. Provide ParentContext with your object to make it the parent of your component's children.

useTransform#

useTransform(object, { position, rotation, scale })

Keeps a three.js object's transform in sync with transform props (plain or shared values). Unset values are left alone. applyTransform(object, values) does it once, outside React.

Diagnostics#

Related#

• Animation and shared values.
• Custom geometry and behaviors.