Hooks & Utilities

Ready signal — required for rendering

Important

You must call usePressReady or markPressReady for rendering to happen. The Press.js pagination engine waits for this signal before starting the capture pipeline. Without it, the CLI render times out and the previewer shows a waiting state indefinitely.

The ready signal tells Press.js: “The document has finished rendering in the browser — you can now measure and paginate it.”

When to call it:

• After all content has been rendered in the DOM
• After async data fetches complete
• After fonts, images, and other assets have loaded
• Not before <Page> and its children have mounted

In most cases, calling it at the top of your root component (after the initial render) is sufficient. For documents that load external data, defer the signal until the data is available (see disabled option below).

---

usePressReady

The standard way to signal readiness in a component-based app.

React

import { usePressReady, Page } from "@press-js/react";

function App() {
  // Basic usage
  usePressReady();

  // With options
  usePressReady({
    page: { type: "A4" },
    selector: "#content",
    disabled: false,
  });

  return (
    <Page type="A4">
      <h1>Document</h1>
    </Page>
  );
}

Vue

<script setup lang="ts">
  import { usePressReady, Page } from "@press-js/vue";

  // Basic usage
  usePressReady();

  // With options
  usePressReady({
    page: { type: "A4" },
    selector: "#content",
  });
</script>

<template>
  <Page type="A4">
    <h1>Document</h1>
  </Page>
</template>

Options

Option	Type	Default	Description
page	PressPageOptions	—	Page configuration (type, orientation, etc.) sent with the ready signal
selector	string	—	CSS selector for the root element to capture
disabled	boolean	false	When true, the ready signal is suppressed. Useful during page transitions or loading states

When to use

• Standard case: Call at the root of your document component — it fires automatically after the first render
• Deferred rendering: Set disabled: true initially, then flip it after async data loads:

function App() {
  const [data, setData] = useState(null);
  const [ready, setReady] = useState(false);

  useEffect(() => {
    fetch("/api/data")
      .then((res) => res.json())
      .then((data) => {
        setData(data);
        setReady(true);
      });
  }, []);

  usePressReady({ disabled: !ready });

  return (
    <Page type="A4">{data ? <Report data={data} /> : <p>Loading...</p>}</Page>
  );
}

• Selective capture: Use selector to target a specific DOM subtree instead of the full page

---

markPressReady

The imperative counterpart to usePressReady. Both functions send the same ready signal — choose the one that fits your code style.

import { markPressReady } from "@press-js/react"; // or "@press-js/vue"

// Simple signal
markPressReady();

// With page options
markPressReady({ page: { type: "Letter", margin: "10mm" } });

usePressReady vs markPressReady

	usePressReady	markPressReady
Style	Declarative (hook/composable)	Imperative (plain function)
Context	Component scope only	Anywhere (components, modules, callbacks)
Auto-cleanup	Re-fires on option changes	Call manually each time
Best for	Standard document components	Non-component code, precise timing control

When to use markPressReady

• In a plain JavaScript module that initializes document content
• After completing a complex async setup sequence outside a component
• When the document is generated dynamically and you control the timing exactly

---

reportPressRenderError

Reports a rendering error to the Press.js pipeline. When called, the render fails with the provided message.

React

import { reportPressRenderError } from "@press-js/react";

function DataFetcher() {
  useEffect(() => {
    fetch("/api/data")
      .then((res) => res.json())
      .catch((err) => reportPressRenderError(err));
  }, []);

  return null;
}

Vue

<script setup lang="ts">
  import { reportPressRenderError } from "@press-js/vue";

  try {
    const data = await fetch("/api/data");
  } catch (err) {
    reportPressRenderError(err);
  }
</script>

Accepts:

• An Error object (uses .message)
• A string
• Any other value (converted via String())

---

shouldUsePressPreviewer

Returns true when the page is viewed in a normal browser (not the headless Press.js renderer). Useful for conditionally rendering debug info or development-only styles.

import { shouldUsePressPreviewer } from "@press-js/react"; // or "@press-js/vue"

if (shouldUsePressPreviewer()) {
  console.log("Preview mode — showing debug overlay");
}

The detection works by checking whether the user agent contains Press.js/1.0. During CLI rendering, the Playwright renderer appends this token to the user agent, so the previewer is automatically suppressed in production.