Shared types
The shared TypeScript types of post-canvas: document attributes, features, adapters, translation, insert items, problems and views.
These types are exported from post-canvas. They are shared across the package: the document model, the feature set, the adapters your app plugs in, translation, and the extension points. Types that belong to one function or component are described next to it: see PostCanvas, Hooks, Render, Server, Embed providers and Utilities.
JSONContent is Tiptap's type for a document node, re-exported so you do not need to import it from @tiptap/core:
import type { JSONContent } from 'post-canvas';Document attributes
These types describe the attributes that nodes store in a saved document. The rules that clean each attribute are on Nodes and marks.
Text
type TextAlign = 'left' | 'center' | 'right' | 'justify' | null;TextAlign is the horizontal alignment of a paragraph or heading. null means the default (start).
type PaletteColor = 'gray' | 'brown' | 'orange' | 'yellow' | 'green' | 'blue' | 'purple' | 'pink' | 'red';PaletteColor is a named colour from the theme palette. Text colour and highlight store the name, never a hex value, so themes and dark mode recolour it and nothing unsafe reaches a style attribute. The paletteColors constant lists the names in menu order.
type HeadingLevel = 1 | 2 | 3 | 4;HeadingLevel is a heading level the editor offers.
Media
type GalleryLayout = 'carousel' | 'grid' | 'masonry' | 'collage';
type ImageAlign = 'center' | 'wide' | 'full' | 'left' | 'right';GalleryLayout is how a gallery lays out its photos (galleryLayouts lists them in menu order). ImageAlign is where a single image sits in the column.
MediaSource is an uploaded picture, shared by the image node, gallery photos and the cover:
Prop
Type
In a stored document, width and height can be 0, meaning unknown. renderHTML leaves them out, and the editor measures the picture on load, outside the undo history.
CollagePlace is where a collage photo sits on the base photo:
Prop
Type
GalleryPhoto is one photo in a gallery. It has every MediaSource field, plus:
Prop
Type
ImageAttrs are the attributes of the image block node. It has every MediaSource field, plus:
Prop
Type
GalleryAttrs are the attributes of the gallery block node:
Prop
Type
FileAttrs are the attributes of the file block node:
Prop
Type
Embeds
Player URLs are built at render time and never stored.
VideoAttrs are the attributes of the video block node:
Prop
Type
EmbedAttrs are the attributes of the embed block node. The iframe URL is built from provider and ref at render time:
Prop
Type
LinkCardAttrs are the attributes of the linkCard block node:
Prop
Type
EmbedInputAttrs are the attributes of the transient embedInput node, the inline "paste a link" field. It is never saved:
Prop
Type
The node also carries status (idle, loading or error), error (a message key or null) and kind (an EmbedInputKind). They are editor state too.
Post fields
CoverImage is a post's cover picture. It is a MediaSource without uploadKey, because a cover is only saved once its upload is done:
type CoverImage = Omit<MediaSource, 'uploadKey'>;PostFields are the optional fields outside the body, shown above the canvas by some presets:
Prop
Type
Features and presets
Features says which parts of the editor are on. resolveFeatures() builds a complete set from a preset and overrides (see Utilities).
Prop
Type
type PresetName = 'full' | 'article' | 'social' | 'comment';
type FeatureOverrides = { [K in keyof Features]?: Features[K] };PresetName is a named starting set of features. FeatureOverrides is a partial set of features that replaces the matching keys of a preset. It is the type of the features prop of PostCanvas.
<PostCanvas
preset="article"
features={{ table: false, gallery: { layouts: ['grid', 'carousel'], maxPhotos: 8 } }}
/>Adapters
Adapters are how the editor talks to your app. Adapters is the object of everything you plug in, and every one is optional. It goes in the adapters prop.
Prop
Type
Uploads
UploadAdapter uploads files to your storage. Without one, image, gallery and file are off unless you set them in features.
Prop
Type
upload receives the file and an UploadContext:
Prop
Type
It resolves with an UploadResult. Only src is required, and it must be an http or https URL.
Prop
Type
HEIC pictures need a converter. Pass convertHeic on the upload adapter. Post Canvas does not bundle one. The heic-to package is LGPL, and your app installs it itself.
import type { UploadAdapter } from 'post-canvas';
export const upload: UploadAdapter = {
async upload(file, { signal, onProgress }) {
const body = new FormData();
body.append('file', file);
const response = await fetch('/api/uploads', { method: 'POST', body, signal });
if (!response.ok) throw new Error('Upload failed');
onProgress(1);
const { url, width, height } = (await response.json()) as { url: string; width: number; height: number };
return { src: url, width, height };
},
accept: { image: 'image/jpeg,image/png,image/webp' },
maxBytes: { image: 10 * 1024 * 1024, file: 25 * 1024 * 1024 },
};Mentions and hashtags
SuggestionSource looks up mentions (@) or hashtags (#):
Prop
Type
search resolves with SuggestionItem entries, one per person or tag. The editor shows at most 8.
Prop
Type
Embeds and link cards
These two adapters usually call your server. See Server for resolvers you can wire to them.
EmbedMetadataResolver looks up an embed's title, description and thumbnail:
type EmbedMetadataResolver = (url: string, ctx: { signal: AbortSignal }) => Promise<EmbedMetadata>;Prop
Type
LinkPreviewResolver fetches a link card's preview:
type LinkPreviewResolver = (url: string, ctx: { signal: AbortSignal }) => Promise<LinkPreview>;Prop
Type
A lookup that takes longer than 10 seconds is given up, and the node stays as it is. Metadata is optional: the video or embed works without it.
Drafts
DraftStorage is where autosaved drafts live. The default is localStorage, in a try/catch. A method can return a value or a promise.
Prop
Type
DraftSnapshot is one autosaved draft:
Prop
Type
i18n
type TranslateValues = Record<string, string | number>;
type Translator = (key: string, values?: TranslateValues) => string;TranslateValues fill a message's placeholders. A Translator looks up a message by its dotted key, such as core.frame.remove, and fills in its placeholders. createTranslator builds one, and useTranslator reads the one in the current provider.
Locale is a language: its BCP 47 code and its flat, dotted messages.
Prop
Type
Editor core
type NotifyKind = 'info' | 'error';NotifyKind is how a notice is announced. PostCanvasCoreStorage is what every extension reads through editor.storage.postCanvasCore:
Prop
Type
Insert items and problems
Extensions provide these through the postCanvasInsert and postCanvasProblems fields. See Extension fields.
type InsertGroup = 'basic' | 'lists' | 'media' | 'embeds' | 'advanced';
type InsertSource = 'slash' | 'insert-button' | 'toolbar';InsertGroup is where an insert item appears in the + and / menus. InsertSource is where an insert item was chosen from, and run receives it.
InsertItem is one entry in the + and / menus:
Prop
Type
Problem is something that blocks or warns before publishing. These are the codes the package reports: limit.words, limit.characters, limit.media, limit.photos, limit.mentions, title.missing, media.uploading, media.failed, embeds.loading and embeds.unresolved. A problem with severity: 'error' blocks publishing, and one with 'warning' only warns.
Prop
Type
Sanitizers
type AttrsSanitizer = (attrs: Record<string, unknown>) => Record<string, unknown> | null;An AttrsSanitizer cleans one node's or mark's attributes. It returns null to drop the node or mark. It is pure, so it runs on the server too. Set it as postCanvasSanitize on a node or mark. See Extensions.
Read-only views
ViewProps are the props of a read-only view for one node type. The attributes are the sanitized ones.
Prop
Type
type ViewComponent = (props: ViewProps) => ReactNode;
type ViewMap = Partial<Record<string, ViewComponent>>;A ViewComponent renders one node type in the read-only PostCanvasView. A ViewMap is a set of them by node type. Pass one as the views prop of PostCanvasView to replace a built-in view. See Render.