Skip to Content
Post Canvas
Concepts

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

  • title is 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.
  • cover is a picture with the same fields as an image in the body (src, width, height, alt, srcset, placeholder, uploadId) but without uploadKey, 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:

  1. The feature is on: features.title for the title, features.cover for the cover.
  2. The classifier, if the preset has one, says to show fields.
PresetTitle and cover
fullOff. Turn them on with features={{ title: true, cover: true }}.
articleOn. Its classifier always shows them, and once the document has content a missing title is a title.missing problem.
socialOn, 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.
commentOff.

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 src is an https URL on your upload host, and its width and height are numbers.

See security.

Next steps

On this page