From Plite to Plate

PreviousNext

Move a Plite React editor to Plate's editor, plugin, and rendering model.

Plate keeps Plite's document model and moves editor setup, rendering, handlers, and command wiring into plugins. Migrate the editor shell first, then move custom rendering and behavior into plugins.

Install

pnpm add platejs
pnpm add platejs

Use feature packages only for the nodes, marks, or behavior you add to the editor. Plate UI users should start with Plate UI instead of rebuilding every component by hand.

Migration Map

Plite surfacePlate surface
createEditor() plus withReact()usePlateEditor() in React components, or createPlateEditor() in factories and tests.
<Plite> plus <Editable><Plate> plus <PlateContent>.
renderElement / renderLeaf switch statementsPlugin components through .withComponent() or node.component.
withX(editor) plugin functions.extendApi() for read/services, .extendTx() for plugin commands, .extendTxGroup() for shared command groups, or .overrideEditor() only when wrapping an existing editor.api method.
Top-level event handlers on EditablePlugin handlers or shortcuts.
Transforms.* importseditor.update((tx) => tx.*).
Editor.* importseditor.read((state) => state.*), or a plugin-owned editor.api.* service.

Editor Shell

Move the editor value into the editor creation call and render the editable with PlateContent.

components/editor.tsx
'use client';
 
import { Plate, PlateContent, usePlateEditor } from 'platejs/react';
 
const initialValue = [
  {
    children: [{ text: 'Hello Plate.' }],
    type: 'p',
  },
];
 
export function Editor() {
  const editor = usePlateEditor({
    value: initialValue,
  });
 
  return (
    <Plate editor={editor}>
      <PlateContent className="p-4" />
    </Plate>
  );
}
components/editor.tsx
'use client';
 
import { Plate, PlateContent, usePlateEditor } from 'platejs/react';
 
const initialValue = [
  {
    children: [{ text: 'Hello Plate.' }],
    type: 'p',
  },
];
 
export function Editor() {
  const editor = usePlateEditor({
    value: initialValue,
  });
 
  return (
    <Plate editor={editor}>
      <PlateContent className="p-4" />
    </Plate>
  );
}

Use createPlateEditor() when the editor is created outside React memoization.

lib/create-editor.ts
import { createPlateEditor } from 'platejs/react';
 
export const editor = createPlateEditor({
  value: [
    {
      children: [{ text: 'Draft' }],
      type: 'p',
    },
  ],
});
lib/create-editor.ts
import { createPlateEditor } from 'platejs/react';
 
export const editor = createPlateEditor({
  value: [
    {
      children: [{ text: 'Draft' }],
      type: 'p',
    },
  ],
});

Custom Elements

Replace renderElement branches with node plugins. Use .withComponent() when the only change is the React component.

components/editor/paragraph-plugin.tsx
import {
  ParagraphPlugin,
  PlateElement,
  type PlateElementProps,
} from 'platejs/react';
 
export function ParagraphElement({
  children,
  ...props
}: PlateElementProps) {
  return (
    <PlateElement className="m-0 px-0 py-1" {...props}>
      {children}
    </PlateElement>
  );
}
 
export const AppParagraphPlugin = ParagraphPlugin.withComponent(
  ParagraphElement
);
components/editor/paragraph-plugin.tsx
import {
  ParagraphPlugin,
  PlateElement,
  type PlateElementProps,
} from 'platejs/react';
 
export function ParagraphElement({
  children,
  ...props
}: PlateElementProps) {
  return (
    <PlateElement className="m-0 px-0 py-1" {...props}>
      {children}
    </PlateElement>
  );
}
 
export const AppParagraphPlugin = ParagraphPlugin.withComponent(
  ParagraphElement
);

If your Plite document stores a custom type like paragraph, keep that type on the plugin.

components/editor/paragraph-plugin.tsx
export const AppParagraphPlugin = ParagraphPlugin.configure({
  node: { type: 'paragraph' },
}).withComponent(ParagraphElement);
components/editor/paragraph-plugin.tsx
export const AppParagraphPlugin = ParagraphPlugin.configure({
  node: { type: 'paragraph' },
}).withComponent(ParagraphElement);

Custom Behavior

Use .extendTx() when a plugin owns a reusable document command. The command is available inside editor.update(...) under the plugin key.

components/editor/limit-exclamation-plugin.tsx
import { createPlatePlugin } from 'platejs/react';
 
export const SignaturePlugin = createPlatePlugin({
  key: 'signature',
}).extendTx(() => (tx) => ({
  insert() {
    tx.text.insert(' - Plate');
  },
}));
components/editor/limit-exclamation-plugin.tsx
import { createPlatePlugin } from 'platejs/react';
 
export const SignaturePlugin = createPlatePlugin({
  key: 'signature',
}).extendTx(() => (tx) => ({
  insert() {
    tx.text.insert(' - Plate');
  },
}));

Call it from a shortcut, toolbar, menu item, or test:

commands.ts
editor.update((tx) => {
  tx.signature.insert();
});
commands.ts
editor.update((tx) => {
  tx.signature.insert();
});

Use .extendTxGroup() when a plugin adds a command to a shared command group. That keeps related commands together without making a global alias.

components/editor/callout-plugin.tsx
import { createPlatePlugin } from 'platejs/react';
 
export const CalloutPlugin = createPlatePlugin({
  key: 'callout',
}).extendTxGroup('insert', () => (tx) => ({
  callout() {
    tx.nodes.insert({
      children: [{ text: '' }],
      type: 'callout',
    });
  },
}));
components/editor/callout-plugin.tsx
import { createPlatePlugin } from 'platejs/react';
 
export const CalloutPlugin = createPlatePlugin({
  key: 'callout',
}).extendTxGroup('insert', () => (tx) => ({
  callout() {
    tx.nodes.insert({
      children: [{ text: '' }],
      type: 'callout',
    });
  },
}));
commands.ts
editor.update((tx) => {
  tx.insert.callout();
});
commands.ts
editor.update((tx) => {
  tx.insert.callout();
});

Use .extendApi() for editor-scoped read or service methods. Use .overrideEditor() only when you need to wrap an existing editor.api method and keep access to the original implementation.

Handlers And Shortcuts

Move editor events into the plugin that owns the behavior.

components/editor/tab-plugin.tsx
import { createPlatePlugin } from 'platejs/react';
 
export const TabPlugin = createPlatePlugin({
  key: 'tab',
  handlers: {
    onKeyDown: ({ event }) => {
      if (event.key !== 'Tab') return false;
 
      event.preventDefault();
 
      return true;
    },
  },
});
components/editor/tab-plugin.tsx
import { createPlatePlugin } from 'platejs/react';
 
export const TabPlugin = createPlatePlugin({
  key: 'tab',
  handlers: {
    onKeyDown: ({ event }) => {
      if (event.key !== 'Tab') return false;
 
      event.preventDefault();
 
      return true;
    },
  },
});

Use shortcuts when the key combination should call a plugin API, transform, or explicit handler.

components/editor/save-plugin.tsx
import { createPlatePlugin } from 'platejs/react';
 
export const SavePlugin = createPlatePlugin({
  key: 'save',
}).extend({
  shortcuts: {
    draft: {
      keys: 'mod+s',
      handler: ({ event }) => {
        event.preventDefault();
 
        return true;
      },
    },
  },
});
components/editor/save-plugin.tsx
import { createPlatePlugin } from 'platejs/react';
 
export const SavePlugin = createPlatePlugin({
  key: 'save',
}).extend({
  shortcuts: {
    draft: {
      keys: 'mod+s',
      handler: ({ event }) => {
        event.preventDefault();
 
        return true;
      },
    },
  },
});

API Calls

Plate keeps reads and writes separate. Read editor state with editor.read(...). Mutate the document with editor.update(...). Use editor.api.* for plugin services and host/runtime APIs, not document mutations.

editor-commands.ts
const text = editor.read((state) => state.text.string([]));
 
editor.update((tx) => {
  tx.marks.toggle('bold');
  tx.text.insert('Hello');
});
 
editor.api.debug.log(text);
editor-commands.ts
const text = editor.read((state) => state.text.string([]));
 
editor.update((tx) => {
  tx.marks.toggle('bold');
  tx.text.insert('Hello');
});
 
editor.api.debug.log(text);

Headless Code

Use createBaseEditor from platejs for non-React importers, serializers, transforms, and tests.

lib/headless-editor.ts
import { createBaseEditor } from 'platejs';
 
export const editor = createBaseEditor({
  value: [
    {
      children: [{ text: 'Headless document.' }],
      type: 'p',
    },
  ],
});
lib/headless-editor.ts
import { createBaseEditor } from 'platejs';
 
export const editor = createBaseEditor({
  value: [
    {
      children: [{ text: 'Headless document.' }],
      type: 'p',
    },
  ],
});

Related