React hooks
The React hooks of post-canvas: build your own editor chrome, read the editor context, translate strings and drag blocks.
The hooks below are exported from post-canvas. They are for apps that build their own editor chrome instead of using the PostCanvas component. All of them run on the client.
usePostCanvasEditor
function usePostCanvasEditor(options?: UsePostCanvasEditorOptions): PostCanvasEditorState;usePostCanvasEditor creates a Tiptap editor with the Post Canvas kit for a preset and a feature set, and keeps it current as the options change. It is the headless core of PostCanvas: no toolbar, no menus, no fields, no autosave. Render the editor with Tiptap's <EditorContent editor={editor} />.
Parameters. options is a UsePostCanvasEditorOptions object. Its fields are listed in the PostCanvas props (the second table). Every field is optional.
Returns. A PostCanvasEditorState:
Prop
Type
editor is null on the server and on the first client render, because the editor renders on the client.
What rebuilds the editor. A change to features, preset or the presence of adapters.upload rebuilds the editor and keeps its content, because the schema follows the features. You can pass a new features or limits object on every render: the hook compares values, not object identity. Everything else (locale, adapters, limits, classify, placeholder, readOnly) updates in place. Changing extensions does not rebuild the editor.
Notices. Without a notify function, notices go to the console. PostCanvas passes its toast area.
'use client';
import { EditorContent } from '@tiptap/react';
import { usePostCanvasEditor } from 'post-canvas';
import 'post-canvas/styles.css';
export function PlainEditor({ onText }: { onText: (text: string) => void }) {
const { editor } = usePostCanvasEditor({
preset: 'comment',
placeholder: 'Write a reply',
onChange: ({ editor }) => onText(editor.getText()),
});
return (
<div className="pc-root">
<EditorContent editor={editor} />
</div>
);
}EditorContent comes from @tiptap/react, which you add to your app. Without the pc-root wrapper and post-canvas/styles.css the content has no Post Canvas styling.
PostCanvasChange
onChange and onSubmit receive a PostCanvasChange:
Prop
Type
ContentFormat
ContentFormat is the type of the contentFormat option, which says how to read a string defaultContent.
type ContentFormat = 'json' | 'html' | 'markdown';The default is html. With a string defaultContent and contentFormat: 'markdown' the hook parses the string as Markdown. For an object defaultContent (Tiptap JSON) you do not need contentFormat. The hook always loads Tiptap's Markdown extension, so setContent(content, 'markdown') on the ref handle, which takes the same type, parses Markdown on any editor. To turn Markdown into JSON without an editor, use fromMarkdown from post-canvas/render.
usePostCanvasContext
function usePostCanvasContext(): PostCanvasContextValue;usePostCanvasContext reads the nearest PostCanvasProvider: the editor (or null before it mounts), the translator, the adapters and the resolved features. It throws outside a provider. Use it in components you render inside PostCanvas or inside your own PostCanvasProvider. See PostCanvasContextValue.
import { usePostCanvasContext } from 'post-canvas';
export function WordCount() {
const { editor, t } = usePostCanvasContext();
if (!editor) return null;
return <span>{t('core.editor.label')}: {editor.getText().split(/\s+/).filter(Boolean).length}</span>;
}useOptionalPostCanvasContext
function useOptionalPostCanvasContext(): PostCanvasContextValue | null;useOptionalPostCanvasContext reads the nearest PostCanvasProvider, or returns null outside one. Use it for components that work with or without the editor around them, such as CoverField.
useTranslator
function useTranslator(): Translator;useTranslator returns the translator of the nearest PostCanvasProvider, or an English translator outside one. A Translator takes a dotted message key and optional placeholder values and returns a string. See the Translator type and createTranslator on the utilities page.
import { useTranslator } from 'post-canvas';
export function RemoveLabel() {
const t = useTranslator();
return <span>{t('core.frame.remove')}</span>;
}usePointerDrag
function usePointerDrag(callbacks: DragCallbacks, options?: PointerDragOptions): PointerDragHandlers;usePointerDrag handles a press and drag with a mouse, a finger or a pen. It is what the block handle and the gallery thumbnails use. A press that never becomes a drag stays an ordinary click, and the click after a drag is swallowed. While a drag runs, the class pc-dragging is set on <html>, for global cursor and selection styles. Escape cancels a running drag.
Parameters.
callbacks: aDragCallbacksobject, described below.options: aPointerDragOptionsobject, described below. Both fields are optional.
Returns. PointerDragHandlers: spread them on the element that starts the drag.
Prop
Type
Prop
Type
Prop
Type
With touchDelay, a finger has to rest first, so a swipe still scrolls the page.
'use client';
import { useState } from 'react';
import { usePointerDrag } from 'post-canvas';
export function DragGrip() {
const [offset, setOffset] = useState(0);
const handlers = usePointerDrag(
{
onStart: () => setOffset(0),
onMove: (event) => setOffset(event.clientY),
onEnd: () => console.log('dropped at', offset),
onCancel: () => setOffset(0),
},
{ threshold: 6, touchDelay: 200 },
);
return (
<button type="button" {...handlers}>
Drag me
</button>
);
}