> Aperture 0.1.0 — experimental, unpublished. [Package archive](/downloads/bolted-aperture-0.1.0.tgz).

# React integration

Read [the shared guide](guide.md). Use the React starter for the complete native-dialog pattern, live settings and Strict Mode.

```tsx
import { useAperture } from "@bolted/aperture/react";
import { recipeToOptions, type Recipe } from "@bolted/aperture/recipes";

export function Scene({ recipe }: { recipe: Recipe }) {
  const { hostRef, contentRef, aperture } = useAperture(
    recipeToOptions(recipe),
  );
  return (
    <>
      <div
        ref={hostRef}
        style={{
          position: "relative",
          height: 480,
          overflow: "hidden",
          padding: 0,
        }}
      >
        <div ref={contentRef}>Revealed content</div>
      </div>
      <button
        type="button"
        disabled={!aperture}
        onClick={() => {
          void aperture?.toggle();
        }}
      >
        Open / close
      </button>
    </>
  );
}
```

Both callback refs must mount before `aperture` is non-null. The hook creates/destroys the controller, handles conditional elements and Strict Mode, and patches changed settings. Do not create a second controller on the same pair or destroy the hook's controller after each render.

Settings should be immutable. Equivalent inline colors and normalized origins do not reset the controller. Supplied values patch existing options; omitted values retain the previous setting. Reset by supplying an explicit value. Callbacks use the latest committed props. Memoize custom drivers; changing driver identity or either element creates a new closed controller and settles pending work as destroyed.

Controller `phase`, `progress`, and `mode` are imperative values, not React state. The hook does not render each frame. Subscribe through `onUpdate` only when needed; avoid writing progress into parent state for a decorative effect. Check result status before follow-up focus/navigation. The hook owns controller cleanup; the app still owns dialog, focus, Escape, scroll locks and its other event listeners.