Title and cover fields
How Post Canvas holds a post's title and cover picture outside the document, and when each preset shows them.
A post often has a title and a cover picture that are not part of the body. Post Canvas keeps them in a small object called PostFields, next to the document JSON but not inside it. The editor shows them above the text when the preset asks for them.
Prop
Type
titleis plain text, at most 200 characters. Line breaks become spaces. Enter or the down arrow at the end of the title moves the caret into the body.coveris a picture with the same fields as an image in the body (src,width,height,alt,srcset,placeholder,uploadId) but withoutuploadKey, because a cover is only stored after its upload has finished. See document JSON.
Read and set the fields
Fields work in two ways, like a normal React input.
Uncontrolled. Pass a starting value with defaultFields (read once on mount) and listen with onFieldsChange:
import { PostCanvas, type PostFields } from 'post-canvas';
function Editor({ saved }: { saved: PostFields }) {
return (
<PostCanvas
preset="article"
defaultFields={saved}
onFieldsChange={(fields) => console.log(fields.title, fields.cover)}
/>
);
}Controlled. Pass fields and update it in onFieldsChange. This is the way to go when the title also appears somewhere else in your page.
import { useState } from 'react';
import { PostCanvas, type PostFields } from 'post-canvas';
function Editor() {
const [fields, setFields] = useState<PostFields>({ title: 'Three days in Lisbon' });
return (
<>
<h1>{fields.title || 'Untitled'}</h1>
<PostCanvas preset="article" fields={fields} onFieldsChange={setFields} />
</>
);
}onFieldsChange receives the whole PostFields object each time. The document and the fields change independently: onChange does not fire when only the title changes, and onFieldsChange does not fire when only the body changes. Save both. The ref handle's clear() empties the document and the fields together.
Prop
Type
When the fields show
Two things must be true for a field to show:
- The feature is on:
features.titlefor the title,features.coverfor the cover. - The classifier, if the preset has one, says to show fields.
| Preset | Title and cover |
|---|---|
full | Off. Turn them on with features={{ title: true, cover: true }}. |
article | On. Its classifier always shows them, and once the document has content a missing title is a title.missing problem. |
social | On, but the classifier shows them only when the post is an article. A text, photo, video or embed post has no title. Once it becomes an article, the title is required. |
comment | Off. |
If you pass classify={null} to social or article, the classifier goes away: the fields show whenever their features are on, and a missing title is no longer a problem. See classify.
In read-only mode (readOnly), the editor shows the title as a heading and no cover. To show a saved post to readers, build the page yourself from your stored fields and the document, as in rendering.
The cover needs an upload adapter
The cover picture uploads through adapters.upload, the same one the body uses. Without it, the "Add cover" button is disabled. CoverField reports a finished upload only: its value never holds a local preview.
Use CoverField on its own
CoverField is exported, so you can place the cover control elsewhere in your own layout:
Prop
Type
It reads the upload adapter and the translator from the nearest PostCanvasProvider. Inside PostCanvas that is automatic. On its own, wrap it in a PostCanvasProvider. The headless guide covers using the pieces without PostCanvas.
Check fields on the server
sanitizeDocument and validateDocument look at the document only. They never see PostFields. Treat the title and the cover as untrusted input of your own:
- Store the title as text and escape it when you render it. React and most template engines do this for you.
- Accept a cover only when its
srcis anhttpsURL on your upload host, and itswidthandheightare numbers.
See security.
Next steps
- Presets and features: the classifier that gates the fields.
- Autosave: drafts keep the fields too.
Presets and features
Pick a preset for the kind of writing you need, change single features, and set limits and a classifier for post-or-article rules.
How adapters work
Adapters connect Post Canvas to your app: uploads, mentions, hashtags, embed and link lookups, and draft storage. All six are optional.