---
url: /apps/reference/hooks.md
description: >-
  Every @civitai/blocks-react hook, indexed by name and linked to the topic page
  that documents it — signature, example and README notes, generated from the
  published package.
---

> Documentation index: https://developer.civitai.com/llms.txt — every page on this site has a markdown version at its URL + `.md`.

# React hooks

`@civitai/blocks-react` is the React-first way to build a Civitai App. Most
hooks wrap a slice of the [message bridge](https://developer.civitai.com/apps/reference/messages.md) so you never touch
`postMessage` directly — you call a hook, get typed state back, and the host
brokers the privileged work. A few call a REST route themselves; the **Trust
model** box below names them.

The signatures on the hook pages are generated from the published package's type
definitions; the examples, and everything each README section says after its
example, come from its README.

::: info Which transport for what
See [Concepts → Transport models](https://developer.civitai.com/apps/guide/concepts.md#transport-models).

Most hooks on this page are bridge hooks, and most of the data they carry also
has a REST route a block can call with the token it already holds. The
[porting guide](https://developer.civitai.com/apps/guide/porting.md#hook-replacements) maps every hook the package
exports to its route, or says why it stays on the bridge.

This page is generated from `@civitai/blocks-react`'s own type definitions and
README, so it describes each hook as the package ships it. That is a property of
the generator, not a recommendation of one transport over the other.
:::

::: tip Trust model
The hooks fall into three classes, and the credential is the boundary in all of
them.

* **Bridge hooks — most of this page.** The hook posts a message; the host
  resolves the viewer from the block token and performs the privileged call on
  Civitai's side of the iframe boundary, re-checking scopes each time.
* **Direct-fetch hooks — `useTip`, `useTipAllowance`, `useEntitlements`,
  `useGoodPurchase` and `useGenerationResources`.** These are *not*
  host-mediated. The hook calls `fetch()` on a `/api/v1/blocks/*` route at the
  validated host origin, sending the block token your block holds as a bearer.
  The server verifies that token on every request and, where the route declares
  one, checks its required scope (`social:tip:self` for the two tip hooks,
  `goods:purchase:self` and `goods:read:self` for the goods hooks;
  `generation-resources` takes any valid block token). An expired token is a
  401 here, and a mock host that only answers messages never sees these calls.
* **Local hooks.** A few read state the block already has or work entirely
  inside the frame, and call nothing on Civitai.

Calling a block route yourself has the same trust model as the direct-fetch
hooks: your block holds a short-lived scoped credential, and the server
re-checks it and its scopes on every request.
:::

::: warning Not every capability is a hook: generation has five body `kind`s
A search of this page for a hook name will not find everything the platform can
generate. One hook, `useBuzzWorkflow`, takes every kind of generation body, and
**what** it generates is chosen by the `kind` of the body you pass it, not by a
separate hook. [Its entry](https://developer.civitai.com/apps/reference/hooks/generation.md#hook-useBuzzWorkflow) is generated from the package README, whose
example sends only `kind: 'textToImage'`. The five kinds:

| Body `kind` | What it runs | Read |
|---|---|---|
| `'textToImage'` | An image from a prompt, with LoRAs and source images | [Generating images](https://developer.civitai.com/apps/guide/text-to-image.md) |
| `'customComfy'` | A ComfyUI workflow: a registered recipe, or your own graph | [Comfy on Civitai](https://developer.civitai.com/apps/guide/comfy-cloud.md) |
| `'step'` | One orchestrator step: a registered step id, or any step `$type` passed through | [What the bridge can and cannot do](https://developer.civitai.com/apps/reference/generation.md#what-the-bridge-can-and-cannot-do) |
| `'training'` | A LoRA trained on the viewer's own images | [`WorkflowBodyTraining`](https://developer.civitai.com/apps/reference/generation/training-and-multi-step.md#bridge-WorkflowBodyTraining) |
| `'workflow'` | Up to eight steps as one generation, a later step reading an earlier one's result | [Multi-step workflows](https://developer.civitai.com/apps/guide/workflows.md) |

See [Workflow bodies: the `kind` union](#workflow-bodies-the-kind-union) below
before concluding a capability is missing.
:::

## Hooks by page

The hooks are documented across the pages below, grouped by what they do, so
that each page's `.md` copy stays small enough for an agent's fetch tool to
read whole. Every hook the package exports is listed here by name; a hook you
cannot find in this index is not in the pinned package.

47 hooks across 6 pages. Each link goes to the page that documents the hook; fetch that page's `.md` for the full entry.

**[Context, frame and analytics hooks](https://developer.civitai.com/apps/reference/hooks/context.md)** — The host handshake, theme, sizing, the block token and settings, direct-load and nested documents, and analytics.

* [`useBlockContext`](https://developer.civitai.com/apps/reference/hooks/context.md#hook-useBlockContext)
* [`useBlockTheme`](https://developer.civitai.com/apps/reference/hooks/context.md#hook-useBlockTheme)
* [`useBlockResize`](https://developer.civitai.com/apps/reference/hooks/context.md#hook-useBlockResize)
* [`useBlockBreakpoint`](https://developer.civitai.com/apps/reference/hooks/context.md#hook-useBlockBreakpoint)
* [`useBlockToken`](https://developer.civitai.com/apps/reference/hooks/context.md#hook-useBlockToken)
* [`useHostOrigin`](https://developer.civitai.com/apps/reference/hooks/context.md#hook-useHostOrigin)
* [`useBlockSettings`](https://developer.civitai.com/apps/reference/hooks/context.md#hook-useBlockSettings)
* [`useBlockAnalytics`](https://developer.civitai.com/apps/reference/hooks/context.md#hook-useBlockAnalytics)
* [`useDirectLoad`](https://developer.civitai.com/apps/reference/hooks/context.md#hook-useDirectLoad)
* [`useNestedDocument`](https://developer.civitai.com/apps/reference/hooks/context.md#hook-useNestedDocument)

**[Generation hooks](https://developer.civitai.com/apps/reference/hooks/generation.md)** — `useBuzzWorkflow` and the hooks that list, publish and resource a generation.

* [`useBuzzWorkflow`](https://developer.civitai.com/apps/reference/hooks/generation.md#hook-useBuzzWorkflow)
* [`useAppWorkflows`](https://developer.civitai.com/apps/reference/hooks/generation.md#hook-useAppWorkflows)
* [`useGenerationResources`](https://developer.civitai.com/apps/reference/hooks/generation.md#hook-useGenerationResources)
* [`usePublishGenerationOutputs`](https://developer.civitai.com/apps/reference/hooks/generation.md#hook-usePublishGenerationOutputs)

**[Batch, confirmed-step and training hooks](https://developer.civitai.com/apps/reference/hooks/batches-and-training.md)** — Estimating and running batches, running one job above the per-call budget, and LoRA training.

* [`useBatchEstimate`](https://developer.civitai.com/apps/reference/hooks/batches-and-training.md#hook-useBatchEstimate)
* [`useWorkflowBatch`](https://developer.civitai.com/apps/reference/hooks/batches-and-training.md#hook-useWorkflowBatch)
* [`usePrepareTrainingDataset`](https://developer.civitai.com/apps/reference/hooks/batches-and-training.md#hook-usePrepareTrainingDataset)
* [`useRunConfirmedStep`](https://developer.civitai.com/apps/reference/hooks/batches-and-training.md#hook-useRunConfirmedStep)
* [`useRunTraining`](https://developer.civitai.com/apps/reference/hooks/batches-and-training.md#hook-useRunTraining)

**[Buzz, purchase and tip hooks](https://developer.civitai.com/apps/reference/hooks/buzz-and-purchases.md)** — Buzz balance and transactions, Buzz and goods purchases, entitlements, compensation and tips.

* [`useBuzzPurchase`](https://developer.civitai.com/apps/reference/hooks/buzz-and-purchases.md#hook-useBuzzPurchase)
* [`useGoodPurchase`](https://developer.civitai.com/apps/reference/hooks/buzz-and-purchases.md#hook-useGoodPurchase)
* [`useEntitlements`](https://developer.civitai.com/apps/reference/hooks/buzz-and-purchases.md#hook-useEntitlements)
* [`useBuzzBalance`](https://developer.civitai.com/apps/reference/hooks/buzz-and-purchases.md#hook-useBuzzBalance)
* [`useBuzzTransactions`](https://developer.civitai.com/apps/reference/hooks/buzz-and-purchases.md#hook-useBuzzTransactions)
* [`useBuzzAccounts`](https://developer.civitai.com/apps/reference/hooks/buzz-and-purchases.md#hook-useBuzzAccounts)
* [`useDailyCompensation`](https://developer.civitai.com/apps/reference/hooks/buzz-and-purchases.md#hook-useDailyCompensation)
* [`useTip`](https://developer.civitai.com/apps/reference/hooks/buzz-and-purchases.md#hook-useTip)
* [`useTipAllowance`](https://developer.civitai.com/apps/reference/hooks/buzz-and-purchases.md#hook-useTipAllowance)

**[Viewer, consent and navigation hooks](https://developer.civitai.com/apps/reference/hooks/viewer-and-navigation.md)** — The viewer, sign-in and consent prompts, maturity and gated images, following collections, and navigating the host.

* [`useViewer`](https://developer.civitai.com/apps/reference/hooks/viewer-and-navigation.md#hook-useViewer)
* [`useCollectionFollow`](https://developer.civitai.com/apps/reference/hooks/viewer-and-navigation.md#hook-useCollectionFollow)
* [`useCivitaiNavigate`](https://developer.civitai.com/apps/reference/hooks/viewer-and-navigation.md#hook-useCivitaiNavigate)
* [`useCivitaiRoute`](https://developer.civitai.com/apps/reference/hooks/viewer-and-navigation.md#hook-useCivitaiRoute)
* [`useRequestSignIn`](https://developer.civitai.com/apps/reference/hooks/viewer-and-navigation.md#hook-useRequestSignIn)
* [`useRequestConsent`](https://developer.civitai.com/apps/reference/hooks/viewer-and-navigation.md#hook-useRequestConsent)
* [`useConsentUnavailable`](https://developer.civitai.com/apps/reference/hooks/viewer-and-navigation.md#hook-useConsentUnavailable)
* [`useDomainMaturity`](https://developer.civitai.com/apps/reference/hooks/viewer-and-navigation.md#hook-useDomainMaturity)
* [`useGatedImages`](https://developer.civitai.com/apps/reference/hooks/viewer-and-navigation.md#hook-useGatedImages)

**[Storage, picker and media hooks](https://developer.civitai.com/apps/reference/hooks/storage-and-media.md)** — Per-app and shared storage, wildcard packs, checkpoint, resource and image pickers, uploading and saving images, and creating posts.

* [`useWildcardPack`](https://developer.civitai.com/apps/reference/hooks/storage-and-media.md#hook-useWildcardPack)
* [`useCreatePostFromApp`](https://developer.civitai.com/apps/reference/hooks/storage-and-media.md#hook-useCreatePostFromApp)
* [`useAppStorage`](https://developer.civitai.com/apps/reference/hooks/storage-and-media.md#hook-useAppStorage)
* [`useSharedStorage`](https://developer.civitai.com/apps/reference/hooks/storage-and-media.md#hook-useSharedStorage)
* [`useCheckpointPicker`](https://developer.civitai.com/apps/reference/hooks/storage-and-media.md#hook-useCheckpointPicker)
* [`useResourcePicker`](https://developer.civitai.com/apps/reference/hooks/storage-and-media.md#hook-useResourcePicker)
* [`useImageUpload`](https://developer.civitai.com/apps/reference/hooks/storage-and-media.md#hook-useImageUpload)
* [`useUploadImageBytes`](https://developer.civitai.com/apps/reference/hooks/storage-and-media.md#hook-useUploadImageBytes)
* [`useImagePicker`](https://developer.civitai.com/apps/reference/hooks/storage-and-media.md#hook-useImagePicker)
* [`useSaveImage`](https://developer.civitai.com/apps/reference/hooks/storage-and-media.md#hook-useSaveImage)

## Workflow bodies: the `kind` union

`estimate()` and `submit()` both take a full `WorkflowBody` — a discriminated
union keyed by `kind`. The hook forwards the body to the host verbatim and never
reads member-specific fields, so every member except `training` flows through the
same `estimate → submit → watch` lifecycle
[`useBuzzWorkflow`](https://developer.civitai.com/apps/reference/hooks/generation.md#hook-useBuzzWorkflow) documents. `training` is quoted with
`estimate()` but run with `useRunTraining()`, and `submit()` refuses it.

As of the pinned `@civitai/app-sdk@0.71.0` the union has five `kind` values, and
`kind: 'step'` is itself two arms — six members in all:

| `kind` | what it runs | what your block sends |
|---|---|---|
| `textToImage` | a Civitai **checkpoint** (plus optional LoRAs / img2img) | `modelId` + `modelVersionId` + `params` |
| `customComfy` | a **ComfyUI workflow** — a server-registered recipe, **or your own graph** | a registered `recipe` id, or `mode: 'inline'` plus the graph itself |
| `step` (`step` present) | a **server-registered orchestrator step** (`convert-image`, `chat-completion`) | a registered `step` id + bounded `params` |
| `step` (`step` omitted) | an orchestrator step type **named directly**, `input` forwarded unmodified | a `$type` + `input` + a `maxBuzz` amount — a reservation, **not** a spend ceiling |
| `training` | an ai-toolkit **LoRA training** run on a dataset of the viewer's own images | a `datasetId` from `usePrepareTrainingDataset()` + a base-model key + `params`; the `quoteId` from the estimate on the run |
| `workflow` | **up to 8 orchestrator steps as one generation**, a later step reading an earlier one's result | `steps` (each a `$type` + `input`, where any value may be a `{ $ref, path }` reference) + optional `arguments`; no `maxBuzz`. See [Multi-step workflows](https://developer.civitai.com/apps/guide/workflows.md) |

`training` is a page-app flow behind a host flag that ships off; its availability,
money rules and the three hooks it uses are under
[`usePrepareTrainingDataset`](https://developer.civitai.com/apps/reference/hooks/batches-and-training.md#hook-usePrepareTrainingDataset).

Narrow on `body.kind` before touching member-specific fields — and note that
`kind === 'step'` alone leaves both step arms in play, so narrow further on
whether `step` is present. The full field tables are in the
[generation bridge reference](https://developer.civitai.com/apps/reference/generation.md#what-the-bridge-can-and-cannot-do).

### `kind: 'customComfy'` — ComfyUI from a block

`customComfy` has **two arms**, selected by `mode`. This is the member most often
missed, because the generated `useBuzzWorkflow` example never shows it.

**Recipe arm** — `mode` omitted (or `'recipe'`). Your block names a
server-registered, code-reviewed workflow and passes bounded params; the server
owns the graph:

```ts
import type { WorkflowBodyCustomComfyRecipe } from '@civitai/app-sdk/blocks';

const body: WorkflowBodyCustomComfyRecipe = {
  kind: 'customComfy',
  recipe: 'starter-comfy-txt2img', // a SERVER-registered id — unknown ids are rejected fail-closed
  params: {
    prompt: 'a serene alpine lake at golden hour',
    // seed?: number | null — omit to let the orchestrator pick
  },
};
```

**Inline arm** — `mode: 'inline'` (required). Your block ships the ComfyUI graph
itself, plus a declared `resources` manifest and a `maxBuzz` ceiling:

```ts
import type { WorkflowBodyCustomComfyInline } from '@civitai/app-sdk/blocks';

const body: WorkflowBodyCustomComfyInline = {
  kind: 'customComfy',
  mode: 'inline', // REQUIRED, and exactly this value — see below
  workflow: {
    // the ComfyUI `/prompt` graph, keyed by node id — the shape
    // ComfyUI's "Save (API Format)" export produces
    '3': { class_type: 'KSampler', inputs: { seed: 42, steps: 20 } },
  },
  resources: ['urn:air:sdxl:checkpoint:civitai:101055@128078'],
  maxBuzz: 50, // integer 1…250, and ALSO the step timeout in seconds
};
```

Three things trip up a first attempt, all covered in the guide:

* **`mode: 'inline'` is required.** Including a `workflow` key does not select
  the arm — a body without `mode` routes to the recipe arm and is then rejected
  for a missing `recipe`.
* **`resources` is a declared manifest, not an inference.** Every AIR the graph
  names must also appear in `resources` or the submit is rejected.
* **`maxBuzz` is the only spend knob**, and doubles as the step timeout in
  seconds.

::: tip The published SDK types BOTH arms
`WorkflowBodyCustomComfy` is itself a union on `mode`, and both arms are
importable from `@civitai/app-sdk/blocks`: `WorkflowBodyCustomComfyRecipe` and
`WorkflowBodyCustomComfyInline` (plus `InlineComfyNode` for the graph nodes).
Import them rather than declaring the inline shape locally — a hand-declared
copy will drift from the SDK.

**Annotate the ARM, not the union**, as both examples above do. When the `mode`
discriminant is **omitted** — which is the shape this page recommends —
TypeScript's excess-property check runs against the whole union and accepts any
key belonging to *any* constituent, so a body annotated
`WorkflowBodyCustomComfy` silently tolerates a `workflow` key on a recipe body
and you find out at submit, server-side. (Spelling `mode` out explicitly narrows
the union to one constituent and *does* restore the error — but then you are
carrying a field the recommended shape leaves off.) Annotating
`WorkflowBodyCustomComfyRecipe` (or `…Inline`) makes it a compile error either
way. Use the union only where a value genuinely holds either arm.

Still narrow on the **value** of `body.mode === 'inline'`, never on whether the
key is present: `mode` is optional on the recipe arm, so a body that merely
carries a `workflow` key routes to the recipe arm and is rejected for a missing
`recipe`.
:::

Both arms are **mod-gated** and **page-token-only** — a model-bound token is
rejected before either arm is inspected. For the graph rules, the entitlement
and moderation gates, the budget model, and a runnable local example, read
**[Comfy on Civitai (`customComfy`)](https://developer.civitai.com/apps/guide/comfy-cloud.md)** — this section is a
pointer, not a replacement.

## Install

```bash
pnpm add @civitai/blocks-react @civitai/app-sdk
```

See the [Quickstart](https://developer.civitai.com/apps/guide/quickstart.md) for a full scaffold, and the
[message bridge reference](https://developer.civitai.com/apps/reference/messages.md) for the protocol these hooks sit on.