Skip to Content
Post Canvas
Concepts

How adapters work

Adapters connect Post Canvas to your app: uploads, mentions, hashtags, embed and link lookups, and draft storage. All six are optional.

Post Canvas has no backend. When the editor needs something from outside the browser, such as a place to put an uploaded photo or a list of people to mention, it asks your code through an adapter: a plain object or function you pass in the adapters prop.

import { PostCanvas, type Adapters } from 'post-canvas';

const adapters: Adapters = {
  upload: { upload: async (file, ctx) => ({ src: await sendToStorage(file, ctx) }) },
  mentions: { search: async (query) => findPeople(query) },
};

<PostCanvas adapters={adapters} />;

Every adapter is optional. A missing one turns off, or limits, the part of the editor that needs it. Define the adapters object once, outside your component or in useMemo, so its identity stays stable.

AdapterUsed forWithout it
uploadPhotos, galleries, files and the coverImage, gallery and file are off, and the cover button is disabled
mentions@ suggestionsTyping @ shows no suggestions
hashtags# suggestionsA typed hashtag can still be created, with no suggestions
embedsA title and thumbnail for videos and embedsThey are inserted without a fetched title or thumbnail
linksLink cards from a pasted page linkA pasted page link becomes a plain link
storageWhere autosaved drafts livelocalStorage

upload

Sends a file to your storage and returns its final URL. It is called once per file, with a context for progress and cancelling.

Prop

Type

The context has kind (image or file), an AbortSignal that aborts when the writer cancels or removes the block, and onProgress(fraction) for a progress bar from 0 to 1:

Prop

Type

Return an UploadResult. Only src is required. Add id to have it stored as uploadId, and width, height, srcset and placeholder if you have them:

Prop

Type

Throw an error when the upload fails. The block shows a failed state with a retry button, and hasPendingUploads stays true until it is resolved or removed.

convertHeic is for photos from iPhones. Post Canvas does not bundle a HEIC converter. If you want one, install a package such as heic-to in your app and pass it in. That package is LGPL licensed, so check that the licence suits your project. See the uploads guide.

mentions and hashtags

Both have the same shape: a search function that returns suggestions for what the writer has typed after @ or #.

Prop

Type

Each result is a SuggestionItem:

Prop

Type

The editor shows up to 8 results. If search throws, the editor shows no suggestions and leaves the text as typed. A mention is stored as an inline mention node with your id and the label. Hashtags use the same node with a # character. See mentions and hashtags.

embeds

Looks up a title, description and thumbnail for a pasted video or embed URL. It is a function:

type EmbedMetadataResolver = (
  url: string,
  ctx: { signal: AbortSignal },
) => Promise<EmbedMetadata>;

Prop

Type

The browser cannot fetch most of these pages because of cross-origin rules, so this runs on your server. post-canvas/server has createEmbedResolver() for it. The lookup is best effort: if it fails, the embed stays as it is, and it never overwrites a title the writer typed.

Fetches the preview for a link card:

type LinkPreviewResolver = (
  url: string,
  ctx: { signal: AbortSignal },
) => Promise<LinkPreview>;

Prop

Type

Like embeds, it must run on your server. Use createLinkPreviewResolver() from post-canvas/server, which refuses to fetch private network addresses. Wire both resolvers behind one route handler: see the Next.js guide and embeds and link previews.

storage

Where autosaved drafts go. Turn autosave on with the autosave prop. By default drafts are kept in localStorage, under a key that starts with post-canvas:. Pass your own storage to keep drafts on your server or in IndexedDB:

Prop

Type

Each method can return a value or a promise. A snapshot holds the document, the fields and the save time:

Prop

Type

See the autosave guide.

Next steps

On this page