} style={{ ...style, borderRadius: "50%" }} />;
}
```
**When to use `directDOM`:** decorative animated backgrounds, glow orbs, or any element where the animation should not trigger parent re-renders.
**When not to use it:** when you need the `progress` value in React state (e.g. to drive other components).
For GPU-heavy scenes, cap animation updates with `maxFPS` (default `30`):
```tsx
useGradient({
type: "radial",
animate: true,
directDOM: true,
cssAnimation: true, // compositor-driven path when supported
webgl: true, // integrated WebGL mode in the same hook (no external libs)
webglDprCap: 1.25, // reduce GPU load on high-DPR screens
maxFPS: 24,
});
```
```
### useTimeline
#### Single range per layer
Each layer animates over one `start` → `end` scroll range. Flat keys on the layer object are the quickest API:
```tsx
import { useTimeline } from "@zuzjs/hooks";
function ScrollScene() {
const { containerRef, layers, effects, layerStates, getLayerScrollRange } = useTimeline({
mode: "scroll",
sceneHeight: 2200,
layers: [
{
id: "intro",
start: 0,
end: 0.25,
opacity: { from: 0, to: 1 },
y: ["32px", 0, "easeOut"],
scale: { from: 0.96, to: 1 },
},
{
id: "expand",
start: 0.25,
end: 0.8,
opacity: { from: 0.7, to: 1 },
borderRadius: ["24px", 0],
perspective: ["400px", "900px"],
rx: ["12deg", 0],
ry: ["-8deg", 0],
z: ["-80px", 0],
scale3d: {
x: { from: 0.92, to: 1 },
y: { from: 0.92, to: 1 },
z: { from: 1, to: 1 },
},
},
{
id: "content",
start: 1,
end: 0.8,
opacity: { from: 1, to: 0 },
},
],
});
const introRange = getLayerScrollRange("intro");
// introRange?.span = total scroll px consumed by the intro range
return (
Timeline-driven hero
3D transform scene
expand active: {String(layerStates.expand.active)}
{" | intro px span: "}{introRange?.span ?? 0}
);
}
```
#### Multiple ranges per layer (`keyframes`)
Use `keyframes` on a layer to chain several `start`/`end` ranges under the same ID. Each keyframe supports the same flat-key API as a single-range layer. Effects from each keyframe are applied in order — once a keyframe completes it holds its end state until the next one begins, giving seamless chaining.
```tsx
const { containerRef, effects } = useTimeline({
mode: "scroll",
sceneHeight: 3000,
layers: [
{
id: "hero",
keyframes: [
// Phase 1: enters from below while fading in
{ start: 0, end: 0.3, opacity: [0, 1], y: ["60px", 0, "easeOut"] },
// Phase 2: scales down while drifting up
{ start: 0.3, end: 0.7, scale: [1, 0.85], y: ["0px", "-40px"] },
// Phase 3: collapses and fades out
{ start: 0.7, end: 1.0, scale: [0.85, 0.1], opacity: [1, 0] },
],
},
],
});
return (
);
```
`layers.hero` gives the overall 0→1 progress across the full `keyframes` timeline.
`effects.hero` gives the merged CSS style for the currently active keyframe(s).
#### Anchor references (`start`/`end` linked to other layers)
You can link `start`/`end` to another layer (or keyframe) instead of hardcoding numbers.
Supported forms:
- `"hero"` → defaults to `hero:end`
- `"hero:start"` / `"hero:end"`
- `"hero#intro:end"` (target keyframe by keyframe `id`)
- `"hero@0:start"` (target keyframe by index)
- `"hero:end+0.03"` / `"hero:end-0.02"` (offset in progress space)
- `{ layerId: "hero", edge: "end", offset: 0.03 }`
```tsx
useTimeline({
mode: "scroll",
interpolate: true,
layers: [
{
id: "heroGradient",
keyframes: [
{ id: "shrink", start: 1, end: 0.5, scale: [1, 0.3] },
],
},
{
id: "dashboard",
keyframes: [
// Starts slightly after heroGradient ends, then eases in
{ start: "heroGradient:end+0.03", end: 0.78, y: [0, 200, "easeOut"] },
],
},
],
});
```
Tip: if `start` and `end` resolve to the same point, the animation can look like a snap. Use an offset (`+0.02` to `+0.08`) or a larger range.
#### Built-in debug overlay
You no longer need to render a debug panel in each page. Enable `debug: true` and `useTimeline` mounts a floating overlay on `document.body` automatically.
```tsx
useTimeline({
mode: "scroll",
debug: process.env.NODE_ENV !== "production",
// debugOverlay defaults to true
// debugOverlay: false, // optional: disable built-in overlay
layers: [...],
});
```
The overlay shows:
- live `sceneHeight`, `viewportHeight`, `scrollTop`, `scrollProgress`
- per-layer pixel ranges
- px <-> progress conversions
- **recommended offset hints** when a linked span is near-zero and likely to snap/flicker
#### Apple-style reveal + stack example
This pattern reveals multiple objects in phases, then stacks/compresses them like a product scroll narrative.
```tsx
const { containerRef, effects } = useTimeline({
mode: "scroll",
interpolate: true,
lerpFactor: 0.08,
layers: [
{
id: "phone",
keyframes: [
{ id: "enter", start: 0.02, end: 0.2, opacity: [0, 1], y: [80, 0, "easeOut"], scale: [0.86, 1, "easeOut"] },
{ id: "float", start: "phone#enter:end", end: 0.48, y: [0, -18], ry: [0, -6], rx: [0, 4] },
{ id: "stack", start: "cards#enter:end+0.02", end: 0.85, y: [-18, -56], scale: [1, 0.88], opacity: [1, 0.95] },
],
},
{
id: "cards",
keyframes: [
{ id: "enter", start: "phone#enter:end+0.02", end: 0.58, opacity: [0, 1], y: [120, 0, "easeOut"], sx: [0.9, 1], sy: [0.9, 1] },
{ id: "stack", start: "phone#stack:start", end: 0.9, y: [0, 48], scale: [1, 0.84], opacity: [1, 0.82] },
],
},
{
id: "headline",
keyframes: [
{ start: 0, end: 0.16, opacity: [0, 1], y: [24, 0] },
{ start: "phone#stack:start", end: 0.92, opacity: [1, 0.1], y: [0, -40] },
],
},
],
});
return (
Powerful. Layered. Cinematic.
{/* phone mock */}
{/* card stack */}
);
```
#### Smooth scroll mode (`interpolate`)
By default the playhead snaps directly to the scroll position on every frame. Set `interpolate: true` to lerp the playhead toward the scroll target — producing a smooth, inertia-like response:
```tsx
useTimeline({
mode: "scroll",
interpolate: true,
lerpFactor: 0.08, // 0.01 (very slow) → 0.5 (near-instant). Default: 0.1
maxFPS: 45, // cap playhead state updates during scroll/lerp
layers: [
{
id: "hero",
entry: {
duration: 800,
delay: 80,
opacity: [0, 1],
y: [36, 0, "easeOut"],
scale: [0.96, 1, "easeOut"],
},
keyframes: [
{ start: 0.08, end: 0.42, y: [0, -42] },
],
},
],
})
```
`entry` runs once per layer on mount and uses the same flat effect API as keyframes.
#### Triggers
Every layer span, keyframe, and entry supports a `trigger` option that controls *when and how* the animation plays.
##### Span / Keyframe trigger
| Value | Behaviour |
|---|---|
| `"timeline"` (default) | Sticky chaining — once a span starts it holds its end-state until the next span takes over. Classic scroll timeline. |
| `"inView"` | Active **only while** the playhead is inside this span's range. Reverses when you scroll back. |
```tsx
// Layer default — all keyframes on this layer reverse on scroll-back
{
id: "card",
trigger: "inView",
keyframes: [
{ start: 0.1, end: 0.3, y: [60, 0], opacity: [0, 1] },
{ start: 0.3, end: 0.6, scale: [1, 1.08] },
],
}
// Per-keyframe override — only this span reverses
{
id: "badge",
keyframes: [
{ trigger: "inView", start: 0.2, end: 0.4, y: [40, 0] },
{ start: 0.4, end: 0.7, opacity: [1, 0] }, // sticky
],
}
```
##### Entry trigger
| Value | Behaviour |
|---|---|
| `"mount"` (default) | Runs **once** after the component mounts, then stops. |
| `"inView"` | Progress is tied to the layer's scroll range — plays forward and **reverses** when you scroll back out. |
```tsx
// One-time mount animation (default)
{
id: "hero",
entry: {
duration: 700,
y: [80, 0, "$easing-spring"], // $token → var(--easing-spring)
opacity: [0, 1],
},
}
// Reversible in-view entry — animates in/out as you scroll
{
id: "feature",
start: 0.15,
end: 0.45,
entry: {
trigger: "inView",
y: [60, 0, "easeOut"], // inline tuple easing per property
opacity: [0, 1],
scale: [0.94, 1],
},
}
```
#### Value API
`useTimeline` supports both forward ranges (`start: 0 → end: 0.5`) and reverse ranges (`start: 1 → end: 0.5`).
Use `effects[layerId]` for auto-composed style output and `layers[layerId]` when you need direct 0→1 progress.
Flat keys on a layer (or keyframe) accept `TransformValueEffect`:
- **Object mode:** `{ from: "24px", to: 0, easing: "easeOut" }`
- **Tuple mode:** `["24px", 0, "easeOut"]`
Units are inferred from `from`/`to` — no separate `unit` field needed.
Easing presets: `"linear"` | `"easeIn"` | `"easeOut"` | `"easeInOut"` or a custom `(t: number) => number`.
If easing is omitted, `useTimeline` defaults to `"easeOut"`.
**Transform shorthand aliases** (work as flat keys or inside `transforms`):
| Shorthand | CSS function |
|---|---|
| `x`, `y`, `z` | `translateX`, `translateY`, `translateZ` |
| `rx`, `ry`, `rz` | `rotateX`, `rotateY`, `rotateZ` |
| `sx`, `sy`, `sz` | `scaleX`, `scaleY`, `scaleZ` |
| `skx`, `sky` | `skewX`, `skewY` |
| `skew` | `skew(angle)` or `{ x, y }` pair |
### useParallax
### useParallax
```tsx
import { useParallax } from "@zuzjs/hooks";
import { useRef } from "react";
function GlowLayer() {
const anchorRef = useRef
(null);
const offset = useParallax(0.18, anchorRef);
return (
Floating glow layer
);
}
```
`useParallax` and `useTimeline` automatically use `ScrollView`'s internal scroll container when mounted inside `ScrollView`, otherwise they use native window scroll.
Scroll updates are batched \u2014 only one `requestAnimationFrame` is ever in flight at a time. Micro-changes below 0.5 px are skipped to avoid unnecessary re-renders.
## Data and DB Usage
### useDatabase
```tsx
import { useDatabase } from "@zuzjs/hooks";
function TodoStore() {
const db = useDatabase({
dbName: "todos-db",
storeName: "todos",
version: 1,
keyPath: "id",
});
// db.add / db.get / db.update / db.remove pattern depends on your schema setup.
return null;
}
```
### DBProvider Hooks
```tsx
import { DatabaseProvider, useDB, useWatchDB } from "@zuzjs/hooks";
function Todos() {
const db = useDB();
useWatchDB("todos", () => {
// react to db mutations
});
return null;
}
```
## Additional Exports
The package also exports related types and helpers, including:
- Calendar and crop types: `CalendarMonthFormat`, `CalendarWeekdayFormat`, `CropShape`.
- Keyboard and anchor enums: `KeyCode`, `AnchorType`.
- Command and chart types: `Command`, `CommandActionProps`, `LineChartProps`, `DataPoint`.
- DnD types: `DragSpec`, `DragProbe`, `DropSpec`, `DropProbe`.
- DB provider utilities: `DatabaseProvider`, `DB_HEAL_BLOCKED_KEY`, `DB_HEAL_STATE_KEY`, `DB_HEALED_KEY`.
- Timeline types: `TimelineLayer`, `TimelineKeyframe`, `TimelineLayerState`, `TimelineEffect`, `TimelineEasing`, `TimelineMode`, `TimelineOptions`, `TimelineTransformEffects`, `TransformValueEffect`, `TransformValueTuple`.
- Gradient types: `UseGradientOptions`, `UseGradientResult`, `GradientType`, `GradientAnimation`, `GradientMotionPreset`, `GradientStop`, `OrbLayer`.
## Notes
- Hooks touching browser APIs must run in client-rendered environments.
- Use TypeScript in your app to get strongly-typed options and return values for each hook.
## License
MIT
---
_Source: https://npm.io/package/@zuzjs/hooks · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._