▲ phase

Status: Alpha. APIs are evolving rapidly. Expect breaking changes.

Phase is a lightweight, lifecycle-aware UI performance layer for the web. It includes tools & guidance to optimize render performance, build performant animations, and manage layout and off-screen resources.

Why phase

You can't accidentally tank the main thread, leak an observer, jank on scroll, or ignore reduced motion. The hard parts are handled for you, so the slow path isn't even reachable:

Pauses when unseen. Off-screen or in a background tab, work stops and CPU drops to zero.
Respects reduced motion by default. Accessibility is built in, not an opt-in.
Never forces a reflow. No getBoundingClientRect, no layout thrash, anywhere in the package.
Zero re-renders from the frame loop. Per-frame work writes to refs and the DOM, never React state.
Frame-locked shared clock. Every animation on the page reads one clock, so nothing drifts out of sync.
Renders only what matters. Skip painting off-screen content, mount non-critical UI when idle.

Each guarantee is a tested invariant, not an aspiration. Every export stays sub-kilobyte to a few kilobytes.

Install

pnpm add phase

Getting started

import { useLoop } from 'phase/react';

function Orbit({ radius }) {
  const speed = 1; // radians per second
  const { ref } = useLoop({
    onTick: (frame) => {
      const angle = (frame.elapsed / 1000) * speed;
      ref.current.style.transform = `translate(${Math.cos(angle) * radius}px, ${Math.sin(angle) * radius}px)`;
    },
  });

  return <div ref={ref} className="dot" />;
}

Four lines of animation code. Behind them, performance-critical plumbing:

Pauses when invisible. Scrolled off-screen or background tab? Zero CPU consumed.
Respects reduced motion. Accessibility is the default, not an opt-in.
Resumes without teleporting. Elapsed time freezes during pause, picks up where it left off.
Clean teardown. Unmount the component and walk away. Nothing leaks.

Philosophy

Every primitive in phase exposes its state as a phase (a single string: idle, running, paused, active, exiting...) paired with a reason explaining why that transition happened.

const { phase, phaseReason } = useLoop({ onTick: draw });

// phase: 'paused'  phaseReason: 'sight'           → off-screen
// phase: 'paused'  phaseReason: 'reduced-motion'  → user disabled motion
// phase: 'running' phaseReason: 'resumed'         → came back into view

One string replaces if (running && visible && !paused && !prefersReducedMotion && mounted).

Each of those signals is also a CPU and battery decision. Animating while off-screen, ignoring reduced motion, or running after unmount is what burns cycles and causes jank. phase composes them once, correctly, instead of leaving each call site to get the conjunction right.

Safe behavior is automatic. Visibility awareness, reduced motion, observer cleanup, and delta clamping are defaults, not opt-ins. Bypassing reduced motion requires an explicit reducedMotion: 'ignore' in the diff.

Scope

phase composes signals (visibility, focus, reduced motion, frame budget) into a coherent lifecycle with a reason for every state transition.

Handles: lifecycle state, timing, visibility, scroll visibility-ratio, reduced motion, observer pooling, quality signals, frame loops.

Does not handle: spring physics, gesture systems, declarative keyframe orchestration. Reach for a dedicated library (e.g. motion) when you need those.

This narrow scope is deliberate. Shipping only the performance-critical plumbing (and nothing else) is what keeps every export sub-kilobyte to a few kilobytes.

Admission criteria

Every export must pass all four:

Wraps a browser API that is easy to misuse and causes measurable perf regressions without careful handling.
Manages a lifecycle (browser: visibility-pausing, reduced-motion, observer pooling; render: preventing re-renders, stable identities; CSS: containment state).
Makes the safe path shorter than the raw path. The primitive is less code and less error-prone than the browser API directly.
Stays individually lean. Every export is measured and budgeted in .size-limit.json. CI rejects regressions. Every byte must justify itself.

If a gap fails any criterion, phase closes it in the skill (audit rules, recipes, scanner signals) rather than shipping code.

Export taxonomy

Category	What it covers	Examples
Timing	Frame clocks and animation loops	createLoop, useLoop, useCanvas, useTween
Observation	Reactive wrappers around browser observers	useSight, useSize, useScrollProgress, useMediaQuery
Lifecycle	Activation signals composed from IO+MQL+rIC	useLifecycle, useIdle, useWhenIdle
Composition	Mount/unmount orchestration with transitions	Presence, Swap, WhenVisible, WhenIdle, Defer
Math	Pure easing and interpolation functions	lerp, clamp, easeOutCubic
Utility	React ref/callback patterns for phase users	useSyncedRef, useStableCallback

Entry points

Import	Contents
`phase`	Core primitives: createLoop, createTicker, createSight, createLifecycle, createScrollProgress, errors
`phase/ease`	Easing functions and math utilities only
`phase/react`	React hooks and components

Each entry point is independently tree-shakeable. Importing phase/ease in a server component pulls zero browser APIs.

Core API

createLoop

The main primitive. Composes a ticker, visibility observer, and reduced-motion listener into a lifecycle-aware animation loop.

import { createLoop } from 'phase';

const loop = createLoop({
  element: el,
  onTick: (frame) => {
    // frame.time    — performance.now()
    // frame.delta   — ms since last tick (clamped to 40ms)
    // frame.elapsed — ms since start (paused time excluded)
    // frame.frame   — frame count
  },
});

loop.start();
// loop.phase       === 'running'
// loop.phaseReason === 'started'

Loop phases

Phase	Meaning	Possible reasons
`idle`	Created but not started	`initial`
`running`	Actively ticking	`started`, `resumed`
`paused`	Temporarily stopped, will resume	`sight`, `reduced-motion`, `degraded`
`stopped`	Permanently disposed	`manual`, `disposed`

Quality signals

phase and quality are orthogonal. A loop can be running + degraded (still animating, but at reduced fidelity to preserve resources).

Quality	Meaning	What changes
`full`	Normal operation	Configured FPS, full DPR
`degraded`	Resources constrained	FPS capped to 30, DPR drops to 1x

Two signals trigger degradation:

Trigger	`qualityReason`	When	Recovery
Window blur	`'unfocused'`	User switches to another window	Recovers on window focus
Frame budget	`'frame-budget'`	3+ consecutive frames exceed the 16.6ms budget	Does not auto-recover

Read loop.quality and loop.qualityReason to adapt rendering (fewer particles, lower-fidelity shaders, skip non-essential visual passes).

The `degraded` option

Controls the loop's response when quality degrades. Same three-value pattern as reducedMotion.

Value	Behavior	Use case
`'throttle'`	Cap FPS (default 30, configurable via `degradedFps`)	Most animations. Still runs, only slower
`'pause'`	Pause the loop entirely	Heavy canvas/WebGL. If it can't run well, don't run
`'ignore'`	Keep running at full quality	Critical UI that must never degrade

createLoop({
  element: el,
  onTick: draw,
  degraded: 'throttle', // default
  degradedFps: 20, // only accepted when degraded is 'throttle'
});

Loop options

Option	Type	Default	Description
`element`	`Element`	required	Element to observe for visibility
`onTick`	`(frame: FrameState) => void`	required	Called each frame while running
`fps`	`number`	—	Cap frames per second
`reducedMotion`	`'pause' \| 'complete' \| 'ignore'`	`'pause'`	Behavior when user prefers reduced motion
`degraded`	`'throttle' \| 'pause' \| 'ignore'`	`'throttle'`	Behavior when quality degrades
`degradedFps`	`number`	`30`	FPS cap in degraded throttle mode
`onPhaseChange`	`(phase, reason) => void`	—	Called on every phase transition

createTicker

The low-level rAF clock underneath createLoop. Use it when you need a frame loop without visibility management (background processing, audio sync, non-visual timing).

import { createTicker } from 'phase';

const ticker = createTicker({
  onTick: (frame) => {
    /* runs every frame */
  },
  fps: 30,
});
ticker.start();

All tickers share a single requestAnimationFrame loop. Every subscriber reads the same performance.now() value each frame, so independent animations stay in visual sync.

Ticker phases

Phase	Meaning	Transitions
`idle`	Created, not started	→ `running` via `start()`
`running`	Actively ticking	→ `paused` via `pause()`
`paused`	Suspended, resumable	→ `running` via `resume()`
`stopped`	Terminal, cannot restart	via `stop()` from any state

createSight

Answers one question: is this element visible right now? Combines document.visibilitychange, pageshow (bfcache restore), and IntersectionObserver into a single phase.

import { createSight } from 'phase';

const sight = createSight({
  element: el,
  onPhaseChange: (phase, reason) => {
    // phase:  'visible' | 'hidden' | 'unknown'
    // reason: 'initial' | 'viewport' | 'document' | 'bfcache' | 'all-hidden'
  },
});

phase is 'visible' only when the document is visible AND the element is in the viewport. Uses a pooled IntersectionObserver (20 elements with the same options share one observer instance).

createLifecycle

The activation decision for an animation, decoupled from who drives the frames. Composes visibility (createSight), reduced motion, and a manual pause into a single active / paused phase.

Use createLifecycle when you own your render loop (a three.js/WebGL renderer, a Web Worker, or any non-rAF work that should pause when off-screen or under reduced motion). When you want phase to drive the loop for you, use createLoop instead.

import { createLifecycle } from 'phase';

const lifecycle = createLifecycle({
  element: canvas,
  onPhaseChange: (phase, reason) => {
    // phase:  'idle' | 'active' | 'paused' | 'stopped'
    // reason: 'started' | 'resumed' | 'sight' | 'reduced-motion' | 'manual' | 'disposed' | 'initial'
    if (phase === 'active') renderer.start();
    else renderer.stop(); // your loop, your teardown
  },
});

// Manual pause (e.g. a panel opened over the hero):
lifecycle.pause();
lifecycle.resume();

// cleanup:
lifecycle.stop();

createLoop is built on createLifecycle (it adds a ticker and quality signals on top). Loop-level optimizations (shared clock, zero-allocation FrameState, delta clamping, FPS cap, strong pause) only apply when phase drives the loop. Lifecycle-level optimizations (pooled observers, composed document-visibility + bfcache + viewport, reduced motion) carry over to consumer-owned loops.

Lifecycle phases

Phase	Meaning	Possible reasons
`idle`	Created but not started	`initial`
`active`	Should be animating	`started`, `resumed`
`paused`	Off-screen, reduced motion, etc.	`sight`, `reduced-motion`, `manual`
`stopped`	Permanently disposed	`disposed`

Pause priority is reduced-motion > sight > manual.

createScrollProgress

Reports what fraction of an element is currently visible in the viewport (0–1), via the shared IntersectionObserver pool. Zero forced reflows, zero extra observers. Ideal for reveal/opacity effects.

Not a scroll-scrubbing engine. This reports intersectionRatio, which plateaus for tall elements once they fill the viewport. For continuous scroll-driven animation, use motion's useScroll or the native ScrollTimeline API.

import { createScrollProgress } from 'phase';

const progress = createScrollProgress({
  element: el,
  onProgress: (ratio) => {
    el.style.opacity = String(ratio);
  },
});

// progress.ratio === 0.65 (synchronous read)

// cleanup:
progress.stop();

The steps option controls threshold granularity. Default 20 generates 21 evenly-spaced thresholds (0%, 5%, 10%, …, 100%). Multiple instances with the same steps share a single IO, adding zero extra observers.

ScrollProgress options

Option	Type	Default	Description
`element`	`Element`	required	Element to observe
`onProgress`	`(ratio: number) => void`	required	Called at each threshold crossing
`steps`	`number`	`20`	Number of evenly-spaced thresholds
`root`	`Element \| Document \| null`	—	IO root element
`rootMargin`	`string`	—	IO root margin

prefersReducedMotion

Returns true when reduced motion is enabled at the OS level. Use it to gate expensive setup or dynamic imports.

import { prefersReducedMotion } from 'phase';

if (!prefersReducedMotion()) {
  const { startParticleSystem } = await import('./particles');
  startParticleSystem(canvas);
}

All hooks and primitives consult this signal automatically. You only need it directly for conditional imports or setup logic.

Easing and math

Pure functions with no browser APIs, side effects, or React. Safe in server components, build scripts, and tests.

import { lerp, clamp01, easeOutCubic, remap } from 'phase/ease';

Easing functions

Function	Character
`easeOutCubic`	Fast start, smooth deceleration
`easeOutQuart`	Sharper deceleration
`easeOutBack`	Overshoots target, snaps back
`easeInOutCubic`	Symmetric S-curve
`linear`	No easing (identity)

All easing functions take a progress value (0–1) and return a curved progress value (0–1). They don't know about time, pixels, or anything else. They reshape a number.

Math utilities

Function	Description	Example
`clamp(value, min, max)`	Constrain to range	`clamp(150, 0, 100)` → `100`
`clamp01(value)`	Constrain to 0–1	`clamp01(-0.5)` → `0`
`lerp(start, end, t)`	Linear interpolation	`lerp(0, 100, 0.5)` → `50`
`inverseLerp(start, end, value)`	Where is value in range? (0–1)	`inverseLerp(0, 100, 75)` → `0.75`
`remap(options)`	Map from one range to another	Input range → output range

The pattern

const progress = clamp01(elapsed / duration); // normalize time to 0–1
const eased = easeOutCubic(progress); // reshape the curve
const value = lerp(startPos, endPos, eased); // map to your range

Easing, interpolation, and your value range are three separate concerns. phase keeps them separate so you can mix and match.

Choosing a primitive

Need	Use
Check on-screen visibility	`useSight` (visibility only)
Run a frame loop via `phase`	`useLoop` (DOM) / `useCanvas` (canvas)
Pause/resume your own loop (WebGL, three.js, Web Worker)	`useLifecycle` (active/paused signal)
Animate a single value in render output	`useTween`
Animate mount/unmount transitions	`Presence` / `Swap` / `WhenVisible`
Skip painting off-screen content (keep in DOM)	`Defer`
Defer non-critical UI until the browser is idle	`WhenIdle` / `useIdle`
Run a side effect or prefetch when idle	`useWhenIdle`
Pause non-`phase` work inside a `Defer` subtree	`useRenderState`
Subscribe to scroll, size, or media values reactively	`useScrollProgress` / `useSize` / `useContainerQuery` / `useMediaQuery`
Scroll/size/visibility without re-renders?	Same hooks with a callback (`onProgress` / `onResize` / `onVisibilityChange`), read via ref

useSight vs useLifecycle: useSight reports pure visibility (for lazy-mounting, analytics, WhenVisible). useLifecycle folds in reduced motion and a manual pause, so you can't accidentally animate for users who asked not to. If you're gating an animation, use useLifecycle. If you're gating content, use useSight.

React hooks

useLoop

The primary React hook. Wraps createLoop with React lifecycle management.

import { useLoop } from 'phase/react';

const { ref, phase, phaseReason } = useLoop({
  onTick: (frame) => {
    ref.current.style.transform = `translateX(${frame.elapsed * 0.1}px)`;
  },
});
return <div ref={ref} />;

Attach the returned ref to the element you want to animate. To bring your own, pass ref in the options.

Your onTick callback always sees the latest props, state, and refs without restarting the loop (stored internally via useSyncedRef).

Never call setState inside onTick. It runs 60 times per second. Write to refs or the DOM directly. The only re-render trigger is phase changing (an infrequent lifecycle event).

useLifecycle

The activation signal for a loop you own. Wraps createLifecycle, returning active / paused so a consumer-owned render loop (WebGL, three.js, a Web Worker) can pause when off-screen or under reduced motion.

import { useLifecycle } from 'phase/react';

function Hero() {
  const { ref, isActive } = useLifecycle();

  useEffect(() => {
    if (!isActive) return; // off-screen / reduced motion / paused
    let raf = requestAnimationFrame(function render() {
      renderer.render();
      raf = requestAnimationFrame(render);
    });
    return () => cancelAnimationFrame(raf);
  }, [isActive]);

  return <canvas ref={ref} />;
}

Option	Type	Default	Description
`ref`	`RefObject`	returned	Bring your own, or attach the returned `ref`
`reducedMotion`	`'pause' \| 'ignore'`	`'pause'`	Whether reduced motion pauses the lifecycle
`paused`	`boolean`	`false`	Manual pause (e.g. a panel opened over the animation)
`enabled`	`boolean`	`true`	When `false`, tears down and reports `idle`
`intersectionOptions`	`IntersectionObserverInit`	—	Forwarded to the underlying observer

Returns { ref, phase, phaseReason, isActive }. See Choosing a primitive for useSight vs useLifecycle.

useCanvas

Everything useLoop provides, plus DPR-aware buffer sizing, ResizeObserver coalescing, and GPU context loss recovery.

import { useRef } from 'react';
import { useCanvas } from 'phase/react';

const containerRef = useRef(null);
const canvasRef = useRef(null);

const { phase } = useCanvas({
  containerRef,
  canvasRef,
  draw: (ctx, frame, size) => {
    ctx.clearRect(0, 0, size.width, size.height);
    // ctx is already scaled for devicePixelRatio — draw in CSS pixels
  },
});

return (
  <div ref={containerRef}>
    <canvas ref={canvasRef} />
  </div>
);

useCanvas coordinates two elements (a sizing container and the canvas), so you pass both refs in.

Concern	How useCanvas handles it
DPR (retina)	Uses `devicePixelContentBoxSize` for exact physical pixels when available, falls back to `width * dpr`. Listens for DPR changes.
Resize	Shared ResizeObserver. Canvas resized on container change. No `getBoundingClientRect`.
Context loss	Listens for `contextlost`/`contextrestored`. Pauses on loss, recovers on restore.
Quality	When degraded, DPR drops to 1x automatically (halves GPU pixel count).

Both hooks accept the same quality controls as createLoop: degraded and degradedFps. For heavy GPU work, consider degraded: 'pause'.

useTween

Animates a number from A to B over a duration. Calls setState per frame (appropriate when the animated value is used in render output).

import { useTween } from 'phase/react';

const opacity = useTween({ target: isVisible ? 1 : 0, duration: 300 });

Use useTween for single values where the render is cheap (counters, progress bars, opacity). Use useLoop when animating many elements or doing canvas work, since per-frame setState doesn't scale.

Reduced motion default: 'complete' (jumps to target instantly). The value still reaches its destination; it skips the animation.

usePresence

The hook behind <Presence>. Use directly when you need full control over mount/unmount lifecycle.

import { usePresence } from 'phase/react';

const { phase, ref, mounted, enter } = usePresence({ show: isOpen });
if (!mounted) return null;
return (
  <div
    ref={ref}
    data-phase={phase}
    data-enter={enter === 'animate' ? 'animate' : undefined}
    className="transition-opacity data-[enter=animate]:starting:opacity-0 data-[phase=exiting]:opacity-0"
  />
);

Presence phases

idle → entered → exiting → exited

Phase	Meaning	`mounted`
`idle`	Not shown (initial or after reveal exit)	`false`
`entered`	Visible and active	`true`
`exiting`	Exit animation in progress	`true`
`exited`	Exit complete, ready for unmount	`false`

Options

Option	Type	Default	Description
`show`	`boolean`	required	Visibility toggle
`mode`	`'mount' \| 'reveal'`	`'mount'`	Unmount after exit or stay in DOM
`enter`	`'animate' \| 'instant'`	`'animate'`	First-mount behavior
`exitDuration`	`number`	`5000`	Safety timeout for exit (ms)
`reducedMotion`	`'respect' \| 'ignore'`	`'respect'`	Reduced motion preference handling

useScrollProgress

Element visibility ratio as a 0–1 value. Wraps createScrollProgress with React lifecycle management (see its note on scope for the distinction between visibility ratio and scroll-scrubbing).

import { useScrollProgress } from 'phase/react';

function FadeIn({ children }) {
  const { ref, progress } = useScrollProgress();
  return (
    <div ref={ref} style={{ opacity: progress }}>
      {children}
    </div>
  );
}

Re-renders only at threshold crossings (~20 per full viewport traversal at default steps). progress is 0 before first observation.

Utility hooks

Hook	Purpose
`useSight`	Element visibility as a phase. Pass `onVisibilityChange` for zero-re-render mode
`useSize`	Element dimensions via shared ResizeObserver. Pass `onResize` for zero-re-render mode
`useContainerQuery`	Breakpoint matching against element width
`useScrollProgress`	Element visibility ratio (0–1). Pass `onProgress` for zero-re-render mode
`useMediaQuery`	CSS media query subscription (shared MQL pool)
`useSyncedRef`	Ref always in sync with latest value
`useStableCallback`	Stable-identity function that calls latest closure

useSight, useSize, and useScrollProgress each support a transient mode: pass a callback (onVisibilityChange, onResize, onProgress) and the hook delivers updates via callback with zero re-renders. The reactive state field is omitted from the return type so accessing it is a compile-time error. An always-current ref (phaseRef, sizeRef, progressRef) is available in both modes.

React components

How animations work

One CSS pattern covers enter and exit across Presence, WhenVisible, and Swap:

className =
  'transition-opacity data-[enter=animate]:starting:opacity-0 data-[phase=exiting]:opacity-0';

No motion-reduce: class needed because reduced motion is handled automatically.

Enter: CSS @starting-style animates the element natively when data-enter="animate" is present. Zero JS during the animation.

Exit: phase stamps data-phase="exiting", waits for transitionend/animationend (or a safety timeout), then unmounts. JS coordination is required because CSS has no "animate then remove from DOM" primitive.

Reduced motion: phase suppresses data-enter="animate" and skips the exit animation (instant unmount). No consumer effort.

Presence

Renders a div that manages its own mount/unmount lifecycle, stamping data-phase for exit and data-enter="animate" for enter.

import { Presence } from 'phase/react';

<Presence
  show={isOpen}
  className="transition-opacity data-[enter=animate]:starting:opacity-0 data-[phase=exiting]:opacity-0"
>
  Modal content
</Presence>;

Prop	Type	Default	Description
`show`	`boolean`	required	Visibility toggle
`mode`	`'mount' \| 'reveal'`	`'mount'`	Unmount after exit or stay in DOM
`enter`	`'animate' \| 'instant'`	`'animate'`	First-mount animation behavior
`exitDuration`	`number`	`5000`	Safety timeout for exit (ms)
`reducedMotion`	`'respect' \| 'ignore'`	`'respect'`	Reduced motion handling

Two modes:

Mode	Behavior	Use case
`'mount'`	Added to DOM on show, removed after exit completes	Modals, toasts, menus
`'reveal'`	Always in DOM, visibility toggled via phase	Scroll reveals, SEO content, IO re-entry

WhenVisible

Mounts children when the element enters the viewport. One-shot (once triggered, stays mounted). Uses the pooled IntersectionObserver via useSight.

import { WhenVisible } from 'phase/react';

<WhenVisible
  rootMargin="200px"
  className="transition-opacity data-[enter=animate]:starting:opacity-0"
>
  <HeavyInteractiveChart />
</WhenVisible>;

Common pattern for viewport-gated lazy loading:

const HeavyChart = lazy(() => import('./heavy-chart'));

<WhenVisible
  rootMargin="200px"
  className="transition-opacity data-[enter=animate]:starting:opacity-0"
>
  <Suspense fallback={<Skeleton />}>
    <HeavyChart />
  </Suspense>
</WhenVisible>;

Prop	Type	Default	Description
`rootMargin`	`string`	`'200px'`	IO rootMargin (preload headroom)
`threshold`	`number \| number[]`	—	IO threshold
`root`	`Element \| null`	—	IO root element
`fallback`	`ReactNode`	—	Shown while awaiting intersection

Reduced motion is automatic: data-enter="animate" is not stamped when reduced motion is preferred.

Swap

Coordinated exit-then-enter transitions. The old state fully exits before the new state enters (no overlap, no z-index issues).

import { Swap } from 'phase/react';

<Swap active={success ? 'success' : 'form'}>
  <Swap.State
    id="form"
    className="transition-all data-[phase=exiting]:opacity-0"
  >
    <Form />
  </Swap.State>
  <Swap.State
    id="success"
    className="transition-all data-[enter=animate]:starting:opacity-0 data-[phase=exiting]:opacity-0"
  >
    <SuccessMessage />
  </Swap.State>
</Swap>;

Rapid changes (A → B → C during A's exit) skip intermediate states and advance directly to the latest active. First state appears instantly (CLS prevention); subsequent states animate via @starting-style.

Rendering

phase is the when layer (when to animate, when to render, when to pause), built from one set of signals. Alongside WhenVisible, two helpers skip rendering work for off-screen content. They differ in how aggressively they skip and whether the content survives server rendering:

Helper	Defers	In DOM?	In SSR HTML?	Reach for it when
`Defer`	browser render (style/layout/paint)	yes	yes	content must stay crawlable but need not paint yet
`WhenIdle`	React mount until idle	no	no	non-critical UI that shouldn't block first paint
`WhenVisible`	React mount until near viewport	no	no	viewport-gated lazy loading / reveals

Defer

Skips the browser's rendering work (style, layout, paint) for off-screen content via content-visibility: auto, using pure CSS with no JS or observers. Children stay in the DOM and are server-rendered.

import { Defer } from 'phase/react';

<Defer estimatedHeight="600px" className="my-section">
  <ArticleSection />
</Defer>;

// Use `as` for semantic elements (no wrapper div needed)
<ul>
  {items.map((item) => (
    <Defer as="li" key={item.id} estimatedHeight="80px">
      <ItemContent item={item} />
    </Defer>
  ))}
</ul>;

Prop	Type	Default	Description
`as`	`ElementType`	`'div'`	HTML element to render (`'li'`, `'tr'`, `'section'`, etc.)
`estimatedHeight`	`string`	`'1000px'`	Reserved size before first paint (any CSS length)
...rest	`Omit<HTMLAttributes<HTMLElement>, 'style'>`	—	Standard HTML attributes except `style` (use `className`)

contain-intrinsic-size: auto <estimatedHeight> reserves space, so there is no layout shift. The browser remembers the real size after first paint. Defer defers rendering only, not hydration or mounting. There is no style prop: the render-skip styles are encapsulated so they can't be overridden. Style the wrapper with className.

content-visibility: auto applies paint containment, which clips all overflow to the element's padding edge. Box shadows, negative margins, and positioned content that bleeds outside the boundary will be cut off. If your content needs to overflow, move it outside the Defer or skip Defer for that container.

Animations inside a Defer keep running. content-visibility skips paint, not JavaScript. phase's own loops (useLoop, useCanvas, useLifecycle) already self-pause off-screen via their own visibility observer. For raw work (a hand-written requestAnimationFrame loop, setInterval), gate it with useRenderState.

WhenIdle

Mounts children once the browser is idle after first paint. One-shot. Use it for non-critical UI that should not compete with the critical path. Backed by the whenIdle core utility (requestIdleCallback).

import { WhenIdle } from 'phase/react';

<WhenIdle
  fallback={<Skeleton />}
  className="transition-opacity data-[enter=animate]:starting:opacity-0"
>
  <SecondaryPanel />
</WhenIdle>;

Prop	Type	Default	Description
`timeout`	`number`	—	Max ms to wait before mounting anyway
`fallback`	`ReactNode`	—	Shown until the browser is idle

Idle never fires during SSR, so WhenIdle children are absent from server HTML. Reserve it for non-critical content. For content that must be crawlable, use Defer. Reduced motion is automatic: data-enter="animate" is not stamped when reduced motion is preferred.

useWhenIdle

Runs a callback once when the browser is idle after mount (the effect-shaped counterpart to useIdle). Use it for side effects (prefetching a chunk, warming a cache) rather than rendering. Cancels on unmount and always calls the latest callback.

import { lazy, Suspense, useState } from 'react';
import { useWhenIdle } from 'phase/react';

const openPanel = () => import('./chat-panel');
const ChatPanel = lazy(openPanel);

function Chat() {
  const [open, setOpen] = useState(false);
  useWhenIdle(() => void openPanel()); // prefetch the chunk during idle

  return open ? (
    <Suspense fallback={<Skeleton />}>
      <ChatPanel />
    </Suspense>
  ) : (
    <button onClick={() => setOpen(true)}>Open</button>
  );
}

It replaces the common (and leak-prone) hand-rolled useEffect(() => { const id = requestIdleCallback(...); return () => cancelIdleCallback(id); }, []). useWhenIdle handles cancellation and the SSR guard. Reach for useIdle instead when you need to render from the idle signal.

useRenderState

Reads whether the browser is rendering an element or skipping it under content-visibility. Pass it the ref from a Defer to pause raw, non-phase work when the subtree stops painting.

import { useRef, useEffect } from 'react';
import { Defer, useRenderState } from 'phase/react';

function Chart() {
  const ref = useRef<HTMLDivElement>(null);
  const phase = useRenderState(ref); // 'rendered' | 'skipped'

  useEffect(() => {
    if (phase === 'skipped') clock.pause();
    else clock.resume();
  }, [phase]);

  return (
    <Defer ref={ref}>
      <RawCanvasThing />
    </Defer>
  );
}

useRenderState only listens and reports. It has no layout effect, so it never breaks Defer's no-layout-shift guarantee. You rarely need it for phase loops, which already self-pause off-screen.

Guarantees

These are the performance invariants behind Why phase. They are tested in CI, not aspirations.

Zero per-frame allocations

FrameState is created once and mutated in place every frame. No objects, arrays, closures, template literals, or spread operators in the tick path, and no GC pressure at 60 fps.

Strong pause

When paused, the ticker calls cancelAnimationFrame and stops scheduling entirely. Zero callbacks fire, zero CPU consumed. This is not the "weak pause" pattern of scheduling rAF and returning early.

Zero forced reflows

No getBoundingClientRect(), offsetWidth, scrollWidth, or getComputedStyle() anywhere in the package. All dimensions come from ResizeObserver (async, compositor-aligned) and all visibility from IntersectionObserver.

Zero React re-renders from the frame loop

The rAF loop never triggers a React re-render. All per-frame state lives in refs; onTick writes to refs or the DOM directly. Only phase changes trigger re-renders (infrequent lifecycle transitions).

Frame-locked shared clock

All tickers share one requestAnimationFrame loop with a single performance.now() read per frame, keeping multiple animations on the same page in visual sync.

Delta clamping

When a loop resumes after a pause, frame.delta is clamped to 40 ms. Animations resume from where they left off with no teleporting.

Errors

Every error includes a machine-readable code and an actionable message.

import { PhaseError, isPhaseError } from 'phase';

Code	Trigger
`server_context`	Calling a browser-only primitive during SSR
`no_element`	Passing a null or undefined `element` to a primitive
`invalid_duration`	`useTween` duration is zero, negative, or NaN
`ticker_stopped`	Calling `start`/`resume` on a stopped ticker
`missing_context`	`<Swap.State>` used outside `<Swap>`

Relationship to View Transitions

phase doesn't wrap React's View Transition API, and it doesn't need to. The two compose cleanly. Reach for <ViewTransition> when you animate between committed UI states like route changes and shared-element morphs, and reach for Presence, Swap, and the frame loops for component-local lifecycle on stable React. A phase loop keeps ticking inside a view-transitioned subtree without conflict.

Bundle size

Minimal footprint is a core promise (see Why phase). Every export is individually measured with Size Limit and budgeted in CI. Sizes reflect minified + brotli-compressed bytes.

Regenerate with pnpm size:readme.

Export	Size (min+brotli)
Core
`createTicker`	837 B
`createSight`	963 B
`createLifecycle`	1.48 kB
`createLoop`	2.6 kB
`createScrollProgress`	869 B
`createRenderState`	495 B
`createDevicePixelRatio`	544 B
`createMutation`	1.2 kB
`whenIdle`	409 B
`prefersReducedMotion`	101 B
Ease
`ease (all)`	210 B
React
`useLoop`	2.81 kB
`useLifecycle`	1.68 kB
`useSight`	1.18 kB
`useCanvas`	3.44 kB
`useMutation`	1.38 kB
`useTween`	620 B
`usePresence`	593 B
`useScrollProgress`	996 B
`useSize`	388 B
`useContainerQuery`	365 B
`useMediaQuery`	246 B
`usePrefersReducedMotion`	273 B
`useDevicePixelRatio`	231 B
`useSyncedRef`	22 B
`useStableCallback`	39 B
`Presence`	743 B
`WhenVisible`	1.44 kB
`WhenIdle`	593 B
`Defer`	85 B
`useIdle`	435 B
`useWhenIdle`	449 B
`useRenderState`	527 B
`Swap`	1.13 kB

Agent skill

phase ships with an agent skill that teaches AI coding agents to implement the API correctly, follow performant-animation best practices, and audit existing code to recommend the cheapest sufficient approach (CSS-only, minimal JS, phase, or a heavier library).

Install it three ways:

# skills.sh
npx skills add vercel-labs/phase --skill phase

Or copy skills/phase/ into your project's .agents/skills/phase/ and reference its SKILL.md from your AGENTS.md, or download skills/phase/dist/phase-skill.zip and unzip it into your skills directory.

The audit scanner ships with the skill (no separate install needed). Ask your agent to audit your animation code and it runs scripts/scan.mjs for you, or run it standalone with node <skill-dir>/scripts/scan.mjs <target-dir>. See the skill README for details.

Name		Name	Last commit message	Last commit date
Latest commit History 9 Commits
.github		.github
.vscode		.vscode
scripts		scripts
skills/phase		skills/phase
src		src
.editorconfig		.editorconfig
.gitignore		.gitignore
.nvmrc		.nvmrc
.oxfmtrc.json		.oxfmtrc.json
.oxlintrc.json		.oxlintrc.json
.size-limit.json		.size-limit.json
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
lefthook.yml		lefthook.yml
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
tsconfig.json		tsconfig.json
tsdown.config.ts		tsdown.config.ts
vitest.config.ts		vitest.config.ts

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

▲ phase

Why phase

Table of contents

Install

Getting started

Philosophy

Scope

Admission criteria

Export taxonomy

Entry points

Core API

createLoop

Loop phases

Quality signals

The degraded option

Loop options

createTicker

Ticker phases

createSight

createLifecycle

Lifecycle phases

createScrollProgress

ScrollProgress options

prefersReducedMotion

Easing and math

Easing functions

Math utilities

The pattern

Choosing a primitive

React hooks

useLoop

useLifecycle

useCanvas

useTween

usePresence

Presence phases

Options

useScrollProgress

Utility hooks

React components

How animations work

Presence

WhenVisible

Swap

Rendering

Defer

WhenIdle

useWhenIdle

useRenderState

Guarantees

Zero per-frame allocations

Strong pause

Zero forced reflows

Zero React re-renders from the frame loop

Frame-locked shared clock

Delta clamping

Errors

Relationship to View Transitions

Bundle size

Agent skill

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

The `degraded` option

Packages