Skip to Content
Post Canvas
Reference

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.

components/plain-editor.tsx
'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: a DragCallbacks object, described below.
  • options: a PointerDragOptions object, 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.

components/drag-grip.tsx
'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>
  );
}

On this page