Storage, picker and media hooks
Per-app and shared storage, wildcard packs and workflow files, checkpoint, resource and image pickers, uploading images and other media, saving images, and creating posts.
This page documents 12 of the 49 hooks in the Hooks reference, which indexes every hook by name. Generated from the published @civitai/blocks-react@0.79.0 package's type definitions and README.
Other pages: Context, frame and analytics hooks · Generation hooks · Batch, confirmed-step and training hooks · Buzz, purchase and tip hooks · Viewer, consent and navigation hooks
useWildcardPack
useWildcardPack(modelVersionId: number): UseWildcardPackinterface UseWildcardPack {
pack: BlockWildcardPack | null;
loading: boolean;
error: Error | null;
refetch: () => void;
}Import a wildcard pack's parsed prompt lists by model version — the host resolves + fetches + unzips + parses it **in the user's own page session** (every download gate enforced), so the untrusted iframe never sees the bytes. Returns `{ pack, loading, error, refetch }`. On failure `error` is a `WildcardPackError` with a discriminated `code` (`not-found` / `forbidden` / `too-large` / `parse-failed` / `busy` — `busy` is retryable), not free text.
const { pack, loading, error, refetch } = useWildcardPack(modelVersionId);
// `error.code === 'busy'` is retryable — call refetch(); the other codes are terminal.
if (error instanceof WildcardPackError && error.code === 'busy') void refetch();
if (!loading && pack) console.log(Object.keys(pack.lists));useResourceFile
useResourceFile(modelVersionId: number, fileId?: number): UseResourceFileinterface UseResourceFile {
file: BlockResourceFile | null;
loading: boolean;
error: Error | null;
refetch: () => void;
}Read a resource file's parsed JSON — for a workflow, its graphs — by model
version. The host resolves, fetches, unzips and parses the file **in the
viewer's own page session**, enforcing the real download gates, so the iframe
never sees the session, a signed URL or the raw bytes. No block scope is needed.
Returns `{ file, loading, error, refetch }`.
- `file.meta` names what was served (`modelId`, `modelVersionId`, `fileId`,
`fileName`, `modelName`, `versionName`, `creatorUsername`).
- `file.entries` holds one `{ path, format, graph }` per JSON document: one for a
plain `.json`, several for a `.zip` (non-JSON entries are skipped). `format`
is `'ui'` (a `nodes` array), `'api'` (every top-level value has `class_type`
and `inputs`) or `'unknown'`; check it before treating `graph` as a graph.
`file.truncated` is `true` when an entry was dropped: past 20 entries, over
the 4 MB per-entry or 16 MB total cap, unreadable, or not valid JSON.
- Pass `fileId` to pin one file of a multi-file version. Without it the host
picks one.
- Changing `modelVersionId` or `fileId` resets `file` and `error` to `null`
before the new fetch, so a file never shows for ids it does not belong to.
- The request waits up to 120 s, because the host downloads and unzips the file.
On failure `error` is a `ResourceFileError` whose `code` is one of a closed set:
| `code` | Means | Retry? |
|---|---|---|
| `not-found` | No such version or file, not a workflow, or not downloadable for free (see below) | No |
| `forbidden` | Above the viewer's maturity ceiling on this site, or the app is in review preview | No |
| `unauthorized` | The viewer is signed out | No. Offer sign-in with `useRequestSignIn()`: the page reloads signed in, the block re-inits, and the hook fetches again on mount |
| `too-large` | Over 32 MB, or every entry was over a size cap (4 MB per entry, 16 MB in total) | No |
| `parse-failed` | Not a `.json`/`.zip`, corrupt, or no valid JSON — **or** the host's catch-all: a network error, a failed fetch, no answer within its 110 s deadline, a transient storage failure, or another server error | Once, maybe: it can be transient |
| `busy` | Three fetches already in flight in this tab | Yes |
| `rate-limited` | The viewer's 30-a-minute budget is spent | Yes, later |
🔴 **Full-page app hosts only — not the model-page slot, not `dev:live`.** The
model-page slot does not answer it (the request times out), and `dev:live`
replies `parse-failed`. Develop against `dev:mock`: `createMockHost` takes a
`resourceFile` (the canned reply) and a `resourceFileError` (force a code);
`setScenario({ resourceFileError: undefined })` clears the forced error.
🔴 **Only free, public versions are served.** An unpublished draft (the owner's
included) and an early-access or paid version answer `not-found` — even for a
viewer who bought it. Only the owner gets their own published early-access
version. A POI model, or a model or version whose availability is not `Public`
or `Unsearchable` (e.g. `Private`), is refused to everyone but the owner,
moderators included. The owner can also read their own non-public files and a
version with downloads disabled; an archived or deleted model is `not-found`
for everyone, the owner included.
The example below retries `busy` and `rate-limited` with no limit. `parse-failed`
is worth at most one retry, so keep it out of that loop: the loop would
re-download a file of up to 32 MB every 2 s.const { file, loading, error, refetch } = useResourceFile(modelVersionId);
// Retry a retryable code from an effect, after a delay — never during render.
// Never add `parse-failed` here: it is worth at most ONE retry, and this loop
// would refetch a file of up to 32 MB every 2 s.
const retryable =
error instanceof ResourceFileError && (error.code === 'busy' || error.code === 'rate-limited');
useEffect(() => {
if (!retryable) return;
const t = setTimeout(refetch, 2_000);
return () => clearTimeout(t);
}, [retryable, refetch]);
const graphs = file?.entries.filter((e) => e.format !== 'unknown') ?? [];
if (!loading && file) console.log(file.meta.fileName, graphs.length, file.truncated);useCreatePostFromApp
useCreatePostFromApp(): UseCreatePostFromAppinterface UseCreatePostFromApp {
createPost: (args: BlockCreatePostRequest, options?: ConsentRetryOptions) => Promise<BlockCreatePostResult>;
pending: boolean;
error: CreatePostError | null;
}Publish a **real, published Post on the viewer's profile** from this app's own
outputs, host-mediated over `CREATE_POST_FROM_APP`. Returns
`{ createPost, pending, error }`.
The strictly-more-consequential sibling of `usePublishGenerationOutputs()`: that
one makes a bare `Image` row with no post, no feed presence, no reward and no
notification; this one makes **public, feed-visible, reward-earning content under
the viewer's byline**.
🔴 **Requires the `posts:write:self` scope**, which is **sensitive** and
**consent-gated**. Declare it in your manifest *with* a `scopeJustifications`
entry — the server rejects the manifest at submit without one — and expect the
viewer to be prompted to grant it before the first call succeeds.
🔴 **The grant is not the consent.** Every call opens a host-chrome confirm, and
what it shows is the **server's** resolution of your request, never your strings:
the tag names that will *actually* be applied, host-fetched model and version
names for a gallery attach, and real thumbnails. A block cannot show one post and
publish another.
🔴 **No arm of `sources` takes a URL.** Name a workflow from this app's own
subqueue plus indexes into its outputs, or `Image` ids from a previous
`usePublishGenerationOutputs()` publish or `useUploadImageBytes()` upload. The
server re-verifies both — ownership,
this app's provenance marker, and that the image is not already in a post.
⚠️ **Posting a published image removes it from this app's own grid.** The
app-scoped read behind `useGatedImages()` is conjoined with `postId IS NULL`, so
an image that joins a post stops resolving there. An app cannot both keep an
image in its shared grid and let the viewer post it — design around it.
Text is advisory: the server bounds `title`/`detail`, screens them, refuses a
`detail` containing a link, and resolves `tags` against **existing** tags only (a
name matching no tag is dropped, never minted, and is shown to the viewer on the
confirm).
`createPost` **rejects** with a `CreatePostError` on every non-success:
| | meaning | what to do |
|---|---|---|
| `err.declined` | the viewer dismissed the confirm — **no post was created** | revert, say nothing |
| `err.signInRequired` | no session | route into `useRequestSignIn()` |
| `err.timedOut` | no reply arrived within the 10-min consent bound | 🔴 **check this BEFORE `.message`** — it also has no `.code`, and its message is an SDK-internal string. It does **not** mean nothing happened; tell the viewer to check their profile and never retry automatically |
| `err.code` set otherwise | a host refusal (`review-mode` / `block is not ready` / `no images to post` / `no block token`) | show or ignore per case |
| `err.code === undefined` **and** `!err.timedOut` | a **server** message the host forwarded verbatim (rate limit, blocked title, refused gallery attach) | show `err.message` |const { createPost, pending } = useCreatePostFromApp();
const { requestSignIn } = useRequestSignIn();
async function share() {
try {
const post = await createPost({
sources: [{ kind: 'workflow', workflowId: w.workflowId, imageIndexes: [0, 2] }],
title: 'Made with Sticker Studio',
});
showToast(`Posted! ${post.url}`);
} catch (err) {
if (err instanceof CreatePostError) {
if (err.signInRequired) return requestSignIn();
if (err.declined) return; // the viewer said no — say nothing
if (err.timedOut) return showToast('Still working — check your profile.');
showToast(err.message); // a real server message, safe to render
}
}
}useAppStorage
useAppStorage(): UseAppStorageDeprecated: new apps keep per-viewer data in a private collection of the document store. This hook is shut down on 2026-11-10; from then on its calls fail with an error. See Storing data.
interface UseAppStorage {
get<T = unknown>(key: string): Promise<T | null>;
set<T = unknown>(key: string, value: T): Promise<{ ok: true; sizeBytes?: number; }>;
delete(key: string): Promise<{ ok: true; deleted: boolean; }>;
list(opts?: { prefix?: string; limit?: number; cursor?: string; }): Promise<AppStorageListResult>;
getQuota(): Promise<AppStorageQuota>;
}KV datastore, host-mediated. Keys are **namespaced** per (block instance, viewer); the byte and row **budgets** are enforced per (**app**, viewer), so every instance of one app shares one budget for that viewer.
import {
APP_STORAGE_MAX_VALUE_BYTES, // largest single value, in wire bytes
APP_STORAGE_MAX_BYTES, // total stored bytes per (app, viewer)
APP_STORAGE_MAX_ROWS, // total rows per (app, viewer)
} from '@civitai/app-sdk/blocks';
const storage = useAppStorage();
await storage.set('key', { any: 'json' }); // rejects over ANY of the three — and on a >200-char key
const v = await storage.get<MyShape>('key'); // null if unset / anon
await storage.delete('key'); // idempotent
const { keys } = await storage.list({ prefix: 'note-' });
const quota = await storage.getQuota(); // { usedBytes, rowCount, limitBytes, limitRows }import { classifyAppStorageError } from '@civitai/app-sdk/blocks';
let status = 'Saved.';
try {
await storage.set(key, note);
} catch (err) {
console.warn('[my-block] save failed:', err); // log the host's words
switch (classifyAppStorageError(err)) { // never render them
case 'value-too-large':
status = 'That note is too long to save. Try shortening it.';
break;
case 'user-row-limit':
status = 'You have no note slots left. Delete one to make room.';
break;
case 'request-failed':
// The bridge's fallback — a transport fault. Genuinely retryable.
status = 'Could not save that note. Please try again.';
break;
default:
// `null`: an unknown ceiling, or (more often) an expired/revoked token.
status =
'Could not save that note. Try reloading the page — if that does not ' +
'help, storage may be unavailable for this app right now.';
}
}useSharedStorage
useSharedStorage(): UseSharedStorageDeprecated: new apps keep data every viewer reads in a shared collection of the document store, which has authorship, counters and marks built in. This hook is shut down on 2026-11-10; from then on its calls fail with an error. See Storing data.
interface UseSharedStorage {
list(opts?: { prefix?: string; limit?: number; cursor?: string; }): Promise<SharedListResult>;
get(key: string): Promise<SharedListItem | null>;
report(key: string, reason?: string): Promise<void>;
getCount(key: string): Promise<number>;
getCounts(keys: string[]): Promise<Record<string, number>>;
append(value: SharedAppendValue): Promise<{ key: string; }>;
update(key: string, value: SharedAppendValue): Promise<void>;
vote(key: string): Promise<number>;
unvote(key: string): Promise<number>;
withdraw(key: string): Promise<{ ok: boolean; deleted: boolean; }>;
}App-scoped, append-only, community-votable SHARED datastore (every viewer sees the same list). Sibling of `useAppStorage`; anonymous viewers get the read path and a hard reject on mutations.
const shared = useSharedStorage();
const { key } = await shared.append({ title: 'Add dark mode', body: 'please' });
const { items } = await shared.list({ limit: 20 }); // newest-first
const count = await shared.vote(key); // idempotent up-vote
await shared.unvote(key);
await shared.withdraw(key); // remove my own entryimport { SharedStorageRateLimitError, useSharedStorage } from '@civitai/blocks-react';
const shared = useSharedStorage();
try {
await shared.append({ title: 'Add dark mode' });
} catch (err) {
if (err instanceof SharedStorageRateLimitError) {
// err.retryAt: ISO-8601 instant a retry can succeed; err.retryAfterSeconds: whole seconds, ≥ 1.
const at = new Date(err.retryAt).toLocaleTimeString();
showNotice(`You're posting fast. Try again at ${at}.`);
} else {
throw err;
}
}useCheckpointPicker
useCheckpointPicker(): UseCheckpointPickerinterface UseCheckpointPicker {
open: (opts?: { /** * 🔴 OMIT THIS BY DEFAULT. It is an ecosystem-family FILTER, not a label: * the host HIDES every checkpoint outside the family you pass. Passing the * family you are already in is therefore a trap — it makes the picker offer * only the ecosystem the user is trying to leave, and every other family * becomes unreachable for the life of the session. * * Omit it for an unconstrained pick: the host applies no base-model * narrowing and offers every checkpoint the viewer can generate with. * * Pass it ONLY when the block must stay inside a family it already holds — * a regenerate/variation flow pinned to one checkpoint's ecosystem, say — * and then DERIVE it from that checkpoint (`checkpoint.baseModel`, or * `useBlockContext().context.checkpoint?.baseModel`). Never a hardcoded * ecosystem string: a literal pins every viewer of the app to whichever * family the author happened to be testing with. Accepts an ecosystem key * (e.g. 'Flux1', 'SDXL') or any baseModel name in the family; the host * collapses either to the ecosystem family. * * An empty string is normalized to absent here and never reaches the wire, * and `''` is **not** an escape hatch — it does not even mean the same thing * on both hosts. On a **model slot** the host normalises whatever string you * send, so `''` resolves to the real ecosystem key `Other` and NARROWS to * that one family. On a **page** the host drops a zero-length value, so `''` * behaves exactly like omitting it. Neither is what you meant on at least one * surface: omit the key, or pass a family derived from a real checkpoint, and * never `''`. * * A WHITESPACE-ONLY string narrows on BOTH hosts — the page host's guard is * `length > 0`, which `' '` passes — which is why this hook trims before * deciding. */ baseModelGroup?: string; /** Currently-selected versionId so the picker can pre-highlight it. */ currentVersionId?: number; }) => Promise<{ selected?: BlockCheckpointInfo; }>;
persist: (versionId: number | null) => Promise<void>;
}Drive the platform Checkpoint picker + persist a viewer override. 🔴 **OMIT `baseModelGroup` BY DEFAULT.** It is an ecosystem-family FILTER, not a label: the host HIDES every checkpoint outside the family you pass, so passing the family you are already in is a trap — the picker then offers only the ecosystem the user is trying to leave. Omit it for an unconstrained pick and the host applies no narrowing at all, offering every checkpoint the viewer can generate with. Pass it ONLY when the block must stay inside a family it already holds — a regenerate/variation flow, say — and then DERIVE it from that checkpoint, never a hardcoded ecosystem string: a literal pins every viewer to whichever family the author happened to test with. `''` is **not** an escape hatch — it does not even mean the same thing on both hosts. On a **model slot** the host normalises whatever string you send, so `''` resolves to the real ecosystem key `Other` and NARROWS to that one family. On a **page** the host drops a zero-length value, so `''` behaves exactly like omitting it. Neither is what you meant on at least one surface: omit the key, or pass a family derived from a real checkpoint, and never `''`.
import { isModelSlotContext } from '@civitai/app-sdk/blocks';
const { context } = useBlockContext();
const { open, persist } = useCheckpointPicker();
// DEFAULT — pass no baseModelGroup. The viewer can reach every family.
if (isModelSlotContext(context) && context.checkpoint) {
const { selected } = await open({ currentVersionId: context.checkpoint.versionId });
if (selected) await persist(selected.versionId); // null clears the override
}import { isModelSlotContext } from '@civitai/app-sdk/blocks';
const { context } = useBlockContext();
const { open, persist } = useCheckpointPicker();
// ONLY to stay inside the family the block already holds — derived, never a literal.
if (isModelSlotContext(context) && context.checkpoint) {
const { selected } = await open({ baseModelGroup: context.checkpoint.baseModel });
if (selected) await persist(selected.versionId);
}useResourcePicker
useResourcePicker(): UseResourcePickerinterface UseResourcePicker {
open: { /** * Single pick. Resolves with the chosen resource, or `null` when the viewer * dismissed the picker. */ (opts: ResourcePickerOpenOptions & { multiple?: undefined; }): Promise<BlockResourceInfo | null>; /** * Multi-select (see {@link ResourcePickerMultiple}). Resolves with the * picked resources IN THE ORDER THE VIEWER PICKED THEM — never more than * `max` — or `[]` when the viewer dismissed. Each entry is the same * {@link BlockResourceInfo} a single pick returns. * * Against a host that predates multi-select the viewer gets the single-pick * picker, and this still resolves with a list: of the one resource they * picked, or `[]`. */ (opts: ResourcePickerOpenOptions & { resourceType: 'LORA'; multiple: ResourcePickerMultiple; }): Promise<BlockResourceInfo[]>; };
}Drive the platform resource picker for page blocks — `'Checkpoint' | 'LORA'`. The viewer searches in host chrome; the block only ever sees what the viewer picked: one resource, or with `multiple` the few LoRAs they chose. DISCOVERY ONLY — a returned `versionId` is re-validated + re-priced server-side at estimate/submit. 🔴 **OMIT `baseModelGroup` BY DEFAULT, and never pass a HARDCODED ecosystem.** It is an ecosystem-family FILTER, not a label: the host hides every resource outside the family you pass, so a literal ecosystem string makes the viewer's own valid LoRAs invisible and the picker look empty or broken. Omit it for an unconstrained pick and the viewer sees everything of that type. Pass it ONLY when the block already holds a chosen checkpoint the pick has to match, and then DERIVE it from that checkpoint (`checkpoint.baseModel`). For stack and matrix apps that pair LoRAs with a checkpoint, this is the recommended pattern: a derived family keeps incompatible LoRAs out of the picker. This hook is PAGE-ONLY, and a page slot has no `context.checkpoint` (that field lives on `ModelSlotContext` alone), so the family comes from `BlockResourceInfo.baseModel`, the `baseModel` of a Checkpoint a picker returned earlier. For a complete multi-LoRA app, see [`starters/examples/generate-studio`](https://github.com/civitai/civitai-app-starters/tree/main/starters/examples/generate-studio): `src/components/ModelSection.tsx` fills one LoRA slot per picker session, up to `MAX_LORAS`, with a `baseModelGroup` derived from the selected checkpoint, and `keepCompatibleLoras` (`src/studio/setup.ts`) re-filters the stack when the checkpoint changes, dropping LoRAs made for another family. To fill several slots in ONE session, use `multiple` (below).
const { open } = useResourcePicker();
const picked = await open({ resourceType: 'LORA' }); // unconstrained — the default
if (picked) {
const versionId = picked.versionId; // feed into body.additionalResources
const weight = picked.strength; // recommended default weight (may be undefined)
}const { open } = useResourcePicker();
const checkpoint = await open({ resourceType: 'Checkpoint' });
if (checkpoint) {
const matching = await open({
resourceType: 'LORA',
baseModelGroup: checkpoint.baseModel, // from the pick above — BlockResourceInfo.baseModel
});
}const { open } = useResourcePicker();
const loras = await open({ resourceType: 'LORA', multiple: { max: 3 } });
// [] when dismissed; otherwise up to 3 BlockResourceInfo, in pick order
const additionalResources = loras.map((lora) => ({
modelVersionId: lora.versionId,
strength: lora.strength ?? 1,
}));useImageUpload
useImageUpload(options: {
purpose: 'generationSource';
}): UseImageUploadGenerationSourceinterface UseImageUploadGenerationSource {
open: () => Promise<BlockGenerationSourceImageInfo | null>;
}Host-mediated image upload — the host opens its native upload modal and the iframe never handles the bytes. Resolves with a moderated image (or `null` on dismiss); pass `{ purpose: 'generationSource' }` for an unscanned img2img source, `{ purpose: 'trainingData' }` for several private training images in one call (`[{ url, air }] | null` — see the LoRA training section), or `{ asyncScan: true }` for the early-resolve + `scanStatus()` flow.
const { open } = useImageUpload();
const img = await open(); // BlockUploadedImageInfo | null
if (img) {
await submit({
kind: 'textToImage',
modelId,
modelVersionId,
sourceImage: { url: img.url, width: 1024, height: 1024 },
params: { prompt },
});
}useUploadImageBytes
useUploadImageBytes(): UseUploadImageBytesinterface UseUploadImageBytes {
upload: (bytes: ArrayBuffer, options?: UploadImageBytesOptions) => Promise<BlockUploadedImageInfo>;
}Upload an image the block **produced in the tab** (a healed PNG, an edited render), with no picker, so the app can then post it. Returns `{ upload }`. `upload(bytes, { filename? })` resolves with the same moderated image a picked `useImageUpload()` upload returns (`imageId`, `nsfwLevel`, `contentRating`, `url`). That `imageId` is postable by this app through `useCreatePostFromApp()` as a `{ kind: 'published', imageIds }` source. - 🔴 **Page apps only.** A slot (model) block's host has no handler for it. The host answers an unhandled request at once with its generic refusal, so on a slot `upload` rejects immediately with `unsupported on this host` rather than waiting out the 10-minute timeout. - 🔴 **Requires `posts:write:self`.** The server refuses the upload without it, and this hook does not prompt. Ask for the scope first with `useRequestConsent()` and upload only once `useBlockToken().scopes` holds it (the example below), because the upload runs before the `createPost()` call that would otherwise prompt. - **Images only:** PNG, WebP or JPEG by magic bytes. Anything else is refused with `file type is not allowed`. The host names the stored file from the sniffed type, whatever `filename` says. - **The cap is 40 MiB.** The hook refuses a larger buffer before sending it, with the host's error `file exceeds the maximum upload size`. The host also allows at most 8 uploads and 80 MiB per 60 seconds per page, and replies `busy` past that. - **The upload is blocking.** The host replies once the image is scanned, so allow for a wait of up to a few minutes. An image above the SFW ceiling or flagged by the scan is refused with the scan's message. - Pass an `ArrayBuffer` (`await blob.arrayBuffer()`). A `Blob`, a `Uint8Array` or an empty buffer is refused with `invalid image-upload request`. The buffer is copied, not transferred. `upload` **rejects** with the host's error string on every refusal: the ones above, `no block token`, or a server message passed through verbatim (the missing scope, the posting flag, page-only, a rate limit, the scan). It rejects with `the host returned no uploaded image` if the reply carries neither an image nor an error. If no reply arrives within 10 minutes it rejects with a `RequestTimeoutError`; the host may still have stored the image, so retrying after a timeout can create a duplicate. The hook ships in `@civitai/blocks-react` 0.67.0, and the `bytes` payload type it sends is in `@civitai/app-sdk` 0.62.0. What the upload does and does not give you on civitai.com: - 🔴 **Generation metadata embedded in the file is not read.** The posted image has no generation details (prompt, resources, sampler settings), whatever the PNG or JPEG carries. In the example below the healed pixels are posted, and the metadata the app repaired is not shown on the post. - 🔴 **Each uploaded image goes into exactly one post.** Once a post holds it, `createPost()` refuses that `imageId` with `an image is not available to post`. To post the same picture again, upload it again. - **An uploaded image never appears in `useGatedImages()`.** That read returns only what the app published with `usePublishGenerationOutputs()`. Keep the `imageId` and `url` that `upload` resolves with if you need to show it. - **A post holds at most 20 images and names at most 10 sources.** Past 20 images the server refuses with `a post may contain at most 20 images`. - **Posting from apps is still being rolled out.** A viewer who does not have it yet is refused with `posting from apps is not enabled`, and the refusal arrives from `upload` as well as from `createPost()`. Handle it as an ordinary error branch, not as a bug in your app. - **Creating the post needs an account with a verified email or a linked sign-in provider.** Other account checks apply too: onboarding must be finished, the account must not be brand new, and it must not be muted or banned. `upload` refuses a banned account but checks none of the rest, so a viewer can upload and then be refused at `createPost()`. - **Server-side limits also apply**, to the upload and to the post, beyond the host's per-page window above. A `busy` reply or a rate-limit error such as `Rate limit exceeded, please retry shortly.` means wait and retry.
import {
CreatePostError,
useBlockToken,
useCreatePostFromApp,
useRequestConsent,
useUploadImageBytes,
} from '@civitai/blocks-react';
function PostHealedButton({ healed }: { healed: Blob }) {
const { scopes } = useBlockToken();
const { requestConsent } = useRequestConsent();
const { upload } = useUploadImageBytes();
const { createPost } = useCreatePostFromApp();
const canPost = scopes.includes('posts:write:self');
async function onClick() {
if (!canPost) {
// Fire-and-forget: this opens the host's consent dialog and returns
// nothing. On a grant the host pushes a new token, `scopes` updates and
// the button re-renders as "Post". Never upload before that: the server
// refuses the upload without the scope.
requestConsent({ scopes: ['posts:write:self'] });
return;
}
try {
// 1. Bytes made in the tab, uploaded and scanned by the host.
const image = await upload(await healed.arrayBuffer(), { filename: 'healed.png' });
// 2. Posted through the existing bridge, with its own confirm.
const post = await createPost({
sources: [{ kind: 'published', imageIds: [image.imageId] }],
title: 'Fixed with Metadata Healer',
});
showToast(`Posted! ${post.url}`);
} catch (err) {
if (err instanceof CreatePostError && err.declined) return; // the viewer said no
showToast((err as Error).message); // e.g. 'busy', 'file type is not allowed'
}
}
return <button onClick={onClick}>{canPost ? 'Post' : 'Allow posting'}</button>;
}useImagePicker
useImagePicker(): UseImagePickerinterface UseImagePicker {
open: { /** * Single pick. Resolves with the chosen image, or `null` when nothing was * picked. Rejects when the host refuses the request. */ (opts?: ImagePickerOpenOptions & { multiple?: undefined; }): Promise<BlockPickedImageInfo | null>; /** * Multi pick (see {@link ImagePickerMultiple}). Resolves with the picked * images, never more than `max`, or `[]` when nothing was picked. Each * entry is the same {@link BlockPickedImageInfo} a single pick returns. * Rejects when the host refuses the request. */ (opts: ImagePickerOpenOptions & { multiple: ImagePickerMultiple; }): Promise<BlockPickedImageInfo[]>; /** * A `multiple` decided at runtime, e.g. * `open({ multiple: many ? { max: 3 } : undefined })`. The result is a list * when `multiple` was set and a single image or `null` when it was not, so * narrow it with `Array.isArray`. */ (opts: ImagePickerOpenOptions & { multiple?: ImagePickerMultiple | undefined; }): Promise<BlockPickedImageInfo | BlockPickedImageInfo[] | null>; };
}Let the viewer pick one of their **existing** Civitai images: the ones they have posted, and the ones they made with the Civitai generator. The host opens its own picker over the viewer's library, and your app receives only what the viewer picked. Returns `{ open }`. `open()` resolves with one image, or `null` if nothing was picked.
const { open } = useImagePicker();
const image = await open(); // BlockPickedImageInfo | null
if (image) {
// image.source 'posted' | 'generated'
// image.url a Civitai-hosted image URL
// image.width, image.height
// image.nsfwLevel the image's rating; it can be a mature level
// image.imageId set for a posted image, undefined for a generated one
}const { open } = useImagePicker();
const images = await open({ multiple: { max: 5 } });
// [] when nothing was picked; otherwise 1 to 5 images
const urls = images.map((image) => image.url);const { open } = useImagePicker();
const output = await open({ sources: ['generated'] });
// output?.imageId is always undefined here: a generator output has no image idconst { open } = useImagePicker();
const picked = await open({ multiple: allowSeveral ? { max: 3 } : undefined });
const images = Array.isArray(picked) ? picked : picked ? [picked] : [];useMediaUpload
useMediaUpload(): UseMediaUploadinterface UseMediaUpload {
open: (options: MediaUploadOpenOptions) => Promise<BlockMediaUploadInfo | null>;
upload: (options: MediaUploadBytesOptions) => Promise<BlockMediaUploadInfo>;
}**The way to pass any media (image, video or audio) into a workflow step.** The host refuses data URIs and inline base64 in step inputs, so upload the file with this hook and pass the `url` it returns into the step input. Returns `{ open, upload }`. - **`open({ kind })`** opens the host's own file picker for that kind. The viewer picks a file, the host uploads it, and `open` resolves with the upload, or `null` if nothing was uploaded. - **`upload({ kind, bytes, mimeType? })`** uploads media your app already holds in the tab, with no picker: a canvas export, a crop, a `MediaRecorder` recording. It resolves with the upload, and never resolves without one.
import { useMediaUpload } from '@civitai/blocks-react';
function UseRecording({ recording }: { recording: Blob }) {
const { upload } = useMediaUpload();
async function onClick() {
const audio = await upload({
kind: 'audio',
bytes: await recording.arrayBuffer(),
mimeType: recording.type, // optional; checked against the content
});
// audio.url goes into the step's audio input
startStep({ audioUrl: audio.url });
}
return <button onClick={onClick}>Use this recording</button>;
}const { open } = useMediaUpload();
const video = await open({ kind: 'video' }); // BlockMediaUploadInfo | null
if (video) {
// video.url, video.width, video.height, video.durationMs (when known)
}useSaveImage
useSaveImage(): UseSaveImageinterface UseSaveImage {
saveImage: (input: SaveImageInput) => Promise<void>;
}Ask the host to download a file to the viewer's device. **A block cannot download anything itself.** Its sandbox lacks `allow-downloads`, and the validator refuses that token for unverified blocks, so an `<a href="blob:…" download>` click silently does nothing. 🔴 **This hook is the sanctioned way to deliver a file**, including one the block produced in the tab. Pass exactly ONE of three inputs, each gated differently by the host: - **`{ url }`**: the block's own generation output. The host allowlists the origin to the civitai image CDN and refuses any other. - **`{ imageId }`**: an image from another user, read through the same per-viewer gate as `useGatedImages()`. A withheld image is never saved. - **`{ bytes }`**: an `ArrayBuffer` the block made in the tab, such as a healed image or a JSON sidecar. 🔴 **Page apps only.** The host classifies it by CONTENT. It accepts PNG, WebP and JPEG by magic bytes. Anything else must be valid UTF-8 with no NUL byte: it is saved as JSON when it parses and `filename` ends `.json` (any case) once the host has replaced each `?` and `#` with `_`, and as plain text otherwise. A GIF, a zip or other binary is refused with `file type is not allowed`. The host forces the extension from the classified type. The cap is 50 MiB, and the hook refuses a larger buffer before sending it: `file exceeds the maximum save size`. The buffer is copied, not transferred, so you can keep displaying it. 🔴 **On a host that predates the `bytes` variant, `saveImage({ bytes })` rejects with `invalid save-image request`.** The host also replies that when the input is not exactly one variant, or when `bytes` is empty or not an `ArrayBuffer`. Pass `await blob.arrayBuffer()`, not the `Blob` or a `Uint8Array`. The promise resolves once the host has started the download. On any refusal it rejects with the host's error string, which can also be `busy` when too many saves are in flight.
import { useSaveImage } from '@civitai/blocks-react';
const { saveImage } = useSaveImage();
// A file healed in the tab. It never leaves the device except to the viewer's disk.
const healed: Blob = await healPngMetadata(file);
await saveImage({ bytes: await healed.arrayBuffer(), filename: 'healed.png' });
// Its JSON sidecar. The .json filename makes valid JSON save as .json rather than .txt.
const sidecar = new TextEncoder().encode(JSON.stringify(metadata, null, 2));
try {
await saveImage({ bytes: sidecar.slice().buffer, filename: 'healed.json' });
} catch (err) {
// 'invalid save-image request' here means this host cannot save bytes yet.
setStatus(`Could not save the sidecar: ${(err as Error).message}`);
}
// The block's own generation output, or another user's image.
await saveImage({ url: output.url, filename: 'render.png' });
await saveImage({ imageId: cell.imageId });