# Introduction

Source: https://platejs.org/docs

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Introduction
description: Build rich-text editors with Plate, Plate UI, AI, MCP, and shadcn/ui.
---

Plate is a React framework for building rich-text editors. It gives you a headless editor runtime, composable plugins, and optional Plate UI components that you copy into your app. Start with Plate UI for a complete editor, or use the packages directly when you need a headless setup.

## Choose a Path

<Cards>
  <Card
    href="/docs/installation/plate-ui"
    title="Install Plate UI"
    description="Use the shadcn CLI to add the editor UI, kits, and starter components."
  />
  <Card
    href="/docs/installation"
    title="Pick an install guide"
    description="Choose Next.js, React, RSC, Node.js, or manual setup."
  />
  <Card
    href="/docs/plugin"
    title="Learn plugins"
    description="Understand the headless plugin model before customizing behavior."
  />
  <Card
    href="/editors"
    title="Start from a template"
    description="Copy a complete editor configuration and adapt it in your app."
  />
</Cards>

## What Plate Owns

| Layer | What it owns | Start here |
| --- | --- | --- |
| `platejs` | Core editor runtime, React bindings, and editor APIs. | [Installation](/docs/installation) |
| `@platejs/*` packages | Headless plugins for nodes, marks, serialization, collaboration, AI, and editor behavior. | [Plugin guide](/docs/plugin) |
| Plate UI registry | App-local UI components, kits, editor templates, and API routes installed through the shadcn CLI. | [Plate UI](/docs/installation/plate-ui) |
| Your app | The copied component code, styling, routing, data model, and product-specific editor behavior. | [Plugin Components](/docs/plugin-components) |

## Why Plate UI?

Plate UI follows the shadcn/ui model: you copy the code, own it, and keep editing it in your app.

- **Open code:** The UI layer is app-local code, not a sealed component package.
- **Composition:** Components use predictable React and shadcn/ui conventions.
- **CLI distribution:** Add kits, templates, components, API routes, and docs through the shadcn CLI.
- **AI-ready:** Open component code and consistent registry metadata give agents real context.
- **MCP-ready:** The [MCP setup](/docs/installation/mcp) lets AI tools inspect and apply Plate registry items.

Done. You can install the full UI path, drop down to headless packages, or start from an editor template.

## FAQ

<Accordions>
  <Accordion title="Which frameworks are Plate compatible with?">
    Plate works in React environments. Use the [Next.js guide](/docs/installation/next) for server-rendered apps, the [React guide](/docs/installation/react) for Vite and client-side apps, [RSC](/docs/installation/rsc) for server components, and [Node.js](/docs/installation/node) for backend-only processing.
  </Accordion>

  <Accordion title="What's the difference between Plate and Plate UI?">
    **Plate** is the headless editor framework: runtime, plugins, transforms, APIs, and React bindings. **Plate UI** is the copied UI layer: components, kits, editor templates, and API routes installed into your app.
  </Accordion>

  <Accordion title="Can I use Plate / Plate UI in my project?">
    Yes. Plate and Plate UI are free for personal and commercial projects. Attribution is not required.
  </Accordion>

  <Accordion title="Is Plate UI a replacement for shadcn/ui?">
    No. Plate UI uses [shadcn/ui](https://ui.shadcn.com/) conventions for editor-specific UI. Use shadcn/ui for the rest of your application.
  </Accordion>

  <Accordion title="How do I manage updates with an Open Code approach?">
    Package behavior updates through `platejs` and `@platejs/*` dependencies. Copied UI code is yours, so update it by comparing the Plate registry source with your local files or by using the [MCP setup](/docs/installation/mcp).
  </Accordion>

  <Accordion title="Why copy/paste components instead of using an npm package?">
    The copied component layer lets you change markup, styles, toolbar behavior, and product details without waiting for a package API to expose every option.
  </Accordion>

  <Accordion title="Will Plate UI be published as an npm package?">
    No. Plate UI is distributed as registry code through the shadcn CLI so the UI layer stays owned by your app.
  </Accordion>
</Accordions>

## Credits

- [shadcn/ui](https://ui.shadcn.com/) - For UI inspiration, documentation, and the CLI.
- [Radix UI](https://radix-ui.com) - For the unstyled, accessible primitives.
- [Vercel](https://vercel.com) - For hosting.
- [Shu Ding](https://shud.in) - Typography style adapted from [Nextra](https://nextra.site).
- [cmdk](https://cmdk.paco.me) - For the `<Command />` component.


# Getting Started

Source: https://platejs.org/docs/installation

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Getting Started
description: Choose the right Plate installation path for your React project.
---

Plate has different setup paths for UI-first editors, headless React editors, server components, and backend processing. Start with Plate UI when you want a complete editor surface. Use the lower-level guides when you need to own the rendering, runtime environment, or server-only pipeline.

## Choose a Path

<Cards>
  <Card
    href="/docs/installation/plate-ui"
    title="Plate UI"
    description="Recommended. Install the shadcn-based editor UI, kits, and starter components."
  />
  <Card
    href="/docs/installation/next"
    title="Next.js"
    description="Use Plate in a server-rendered React app."
  />
  <Card
    href="/docs/installation/react"
    title="React"
    description="Use Plate in Vite, React Router, or another client-side React app."
  />
  <Card
    href="/docs/installation/manual"
    title="Manual"
    description="Build a headless editor with direct package installs."
  />
</Cards>

<Steps>

### Install Plate UI

Use Plate UI when you want the fastest working editor path.

```bash
npx shadcn@latest add @plate/plate-ui
```

### Pick the Runtime Guide

After Plate UI is installed, choose the runtime guide that matches your app:

- [Next.js](/docs/installation/next) for server-rendered React apps.
- [React](/docs/installation/react) for Vite, React Router, and other client-side apps.

### Add Features

Use feature kits when you want complete plugin + UI wiring. Use manual plugin docs when you want only the headless package behavior.

</Steps>

## Other Environments

| Environment | Use it when | Guide |
| --- | --- | --- |
| Manual React | You do not want Plate UI or shadcn/ui. | [Manual Installation](/docs/installation/manual) |
| React Server Components | You need static content generation or server-side editor processing without client-side interactivity. | [RSC](/docs/installation/rsc) |
| Node.js | You need backend migration, validation, or serialization scripts. | [Node.js](/docs/installation/node) |

<Callout type="note">
  Server-only environments use base package imports like `platejs` and `@platejs/basic-nodes`. Do not import from `/react` subpaths in RSC or Node.js.
</Callout>

## Next Steps

Once the editor runs, use these docs to customize it:

- [Editor](/docs/editor) explains the editor instance.
- [Plugin](/docs/plugin) explains plugin configuration.
- [Plugin Components](/docs/plugin-components) explains node and mark rendering.
- [Troubleshooting](/docs/troubleshooting) covers common setup issues.

Done. You now have the right install path for your app surface.


# Controlled Editor Value

Source: https://platejs.org/docs/controlled

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Controlled Editor Value
description: Control initial values, persistence, replacement, and async initialization.
---

Plate is not a normal controlled text input. The editor owns content, selection, history, plugin state, and normalization. This guide shows the safe control points: initial values, change persistence, explicit replacement, reset, and delayed initialization.

## Value Ownership

<Callout type="warning" title="Do not control every keystroke">
  Do not mirror `editor.children` into React state and pass it back on every
  change. That fights Slate selection/history and turns normal typing into a
  full-document replacement loop.
</Callout>

| Goal | API |
| --- | --- |
| Set initial content. | `value` in `usePlateEditor` or `createPlateEditor`. |
| Persist edits. | `<Plate onValueChange>` or `<Plate onChange>`. |
| Replace content from outside the editor. | `editor.tf.setValue(value)`. |
| Reset editor state. | `editor.tf.reset()`. |
| Delay initialization. | `skipInitialization: true` plus `editor.tf.init(...)`. |

<Steps>

### Set the Initial Value

Pass a `Value`, an HTML string, a function, or an async function to `value`.

```tsx title="components/editor.tsx" showLineNumbers
import type { Value } from 'platejs';
import { Plate, usePlateEditor } from 'platejs/react';

import { Editor, EditorContainer } from '@/components/ui/editor';

const initialValue: Value = [
  {
    children: [{ text: 'Initial value' }],
    type: 'p',
  },
];

export function MyEditor() {
  const editor = usePlateEditor({
    value: initialValue,
  });

  return (
    <Plate editor={editor}>
      <EditorContainer>
        <Editor />
      </EditorContainer>
    </Plate>
  );
}
```

### Persist Changes

Use `onValueChange` when you only need the document value.

```tsx title="components/editor.tsx" showLineNumbers {15-19,25}
import type { Value } from 'platejs';
import { Plate, usePlateEditor } from 'platejs/react';

import { Editor, EditorContainer } from '@/components/ui/editor';

const STORAGE_KEY = 'plate-value';

const initialValue: Value = [
  {
    children: [{ text: 'Autosaved value' }],
    type: 'p',
  },
];

function saveValue(value: Value) {
  localStorage.setItem(STORAGE_KEY, JSON.stringify(value));
}

export function MyEditor() {
  const editor = usePlateEditor({
    value: () => {
      const saved = localStorage.getItem(STORAGE_KEY);

      return saved ? JSON.parse(saved) : initialValue;
    },
  });

  return (
    <Plate editor={editor} onValueChange={({ value }) => saveValue(value)}>
      <EditorContainer>
        <Editor />
      </EditorContainer>
    </Plate>
  );
}
```

Use `onChange` when the callback needs the editor instance too.

```tsx title="components/editor.tsx"
<Plate
  editor={editor}
  onChange={({ editor, value }) => {
    console.info(editor.id, value);
  }}
/>
```

### Replace or Reset Content

Use transforms for external changes. `setValue` replaces the document and
`reset` returns the editor to its initialized state.

```tsx title="components/replace-controls.tsx" showLineNumbers
import type { Value } from 'platejs';
import { useEditorRef } from 'platejs/react';

import { Button } from '@/components/ui/button';

const replacementValue: Value = [
  {
    children: [{ text: 'Replaced value' }],
    type: 'p',
  },
];

export function ReplaceControls() {
  const editor = useEditorRef();

  return (
    <div className="flex gap-2">
      <Button onClick={() => editor.tf.setValue(replacementValue)}>
        Replace Value
      </Button>
      <Button onClick={() => editor.tf.reset()}>Reset Editor</Button>
    </div>
  );
}
```

<Callout type="info">
  `editor.tf.setValue` replaces nodes at the document root. Use it for explicit
  outside-editor changes, not for every `onValueChange`.
</Callout>

[controlled-demo registry content](https://platejs.org/r/controlled-demo)

### Load Async Initial Content

Use an async `value` function when the editor can initialize as soon as the data
resolves.

```tsx title="components/async-editor.tsx" showLineNumbers
import { Plate, usePlateEditor } from 'platejs/react';

import { Editor, EditorContainer } from '@/components/ui/editor';

export function AsyncEditor() {
  const editor = usePlateEditor({
    autoSelect: 'end',
    value: async () => {
      const response = await fetch('/api/document');
      const data = await response.json();

      return data.content;
    },
    onReady: ({ isAsync, value }) => {
      if (isAsync) console.info('Loaded value:', value);
    },
  });

  return (
    <Plate editor={editor}>
      <EditorContainer>
        <Editor />
      </EditorContainer>
    </Plate>
  );
}
```

### Initialize Manually

Use `skipInitialization` when another system owns the startup moment, such as
collaboration or a multi-step loader.

```tsx title="components/manual-init-editor.tsx" showLineNumbers {8,13-18}
import * as React from 'react';
import { Plate, usePlateEditor } from 'platejs/react';

import { Editor, EditorContainer } from '@/components/ui/editor';

export function ManualInitEditor() {
  const editor = usePlateEditor({
    skipInitialization: true,
  });

  React.useEffect(() => {
    void fetch('/api/document')
      .then((response) => response.json())
      .then((data) => {
        editor.tf.init({
          autoSelect: 'end',
          value: data.content,
        });
      });
  }, [editor]);

  return (
    <Plate editor={editor}>
      <EditorContainer>
        <Editor />
      </EditorContainer>
    </Plate>
  );
}
```

</Steps>

Done. Plate owns live editor state; your app controls the entry points around it.


# Debugging

Source: https://platejs.org/docs/debugging

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Debugging
description: Debugging in Plate.
---

## Using the DebugPlugin

The `DebugPlugin` is automatically included when you create a Plate editor. You can access its methods through the editor's API:

```ts
const editor = createPlateEditor({
  plugins: [/* your plugins */],
});

editor.api.debug.log('This is a log message');
editor.api.debug.info('This is an info message');
editor.api.debug.warn('This is a warning');
editor.api.debug.error('This is an error');
```

### Log Levels

The `DebugPlugin` supports four log levels:

1. `log`: For general logging
2. `info`: For informational messages
3. `warn`: For warnings
4. `error`: For errors

You can set the minimum log level to control which messages are displayed:

```ts
const editor = createPlateEditor({
  plugins: [
    DebugPlugin.configure({
      options: {
        logLevel: 'warn', // Only show warnings and errors
      },
    }),
  ],
});
```

### Configuration Options

The `DebugPlugin` can be configured with the following options:

- `isProduction`: Set to `true` to disable logging in production environments.
- `logLevel`: Set the minimum log level (`'error'`, `'warn'`, `'info'`, or `'log'`).
- `logger`: Provide custom logging functions for each log level.
- `throwErrors`: Set to `true` to throw errors instead of logging them (default: `true`).

Example configuration:

```ts
const editor = createPlateEditor({
  plugins: [
    DebugPlugin.configure({
      options: {
        isProduction: process.env.NODE_ENV === 'production',
        logLevel: 'info',
        logger: {
          error: (message, type, details) => {
            // Custom error logging
            console.error(`Custom Error: ${message}`, type, details);
          },
          // ... custom loggers for other levels
        },
        throwErrors: false,
      },
    }),
  ],
});
```

### Error Handling

By default, the `DebugPlugin` throws errors when `error` is called. You can catch these errors and handle them as needed:

```ts
try {
  editor.api.debug.error('An error occurred', 'CUSTOM_ERROR', { details: 'Additional information' });
} catch (error) {
  if (error instanceof PlateError) {
    console.debug(error.type); // 'CUSTOM_ERROR'
    console.debug(error.message); // '[CUSTOM_ERROR] An error occurred'
  }
}
```

To log errors instead of throwing them, set `throwErrors` to `false` in the configuration.

### Best Practices

1. Use appropriate log levels for different types of messages.
2. In production, set `isProduction` to `true` to disable non-essential logging.
3. Use custom loggers to integrate with your preferred logging service.
4. Include relevant details when logging to make debugging easier.
5. Use error types to categorize and handle different error scenarios.

## Additional Debugging Strategies

Besides using the DebugPlugin, there are other effective ways to debug your Plate editor:

### 1. Override Editor Methods with Logging

You can use the `extendEditor` option to override editor methods and add logging:

```ts
const LoggingPlugin = createPlatePlugin({
  key: 'logging',
}).overrideEditor(({ editor, tf: { apply } }) => ({
  transforms: {
    apply(operation) {
      console.debug('Operation:', operation);
      apply(operation);
    },
  },
}));

const editor = createPlateEditor({
  plugins: [LoggingPlugin],
});
```

This approach allows you to log operations, selections, or any other editor behavior you want to inspect.

### 2. Remove Suspected Plugins

If you're experiencing issues, try removing plugins one by one to isolate the problem:

```ts
const editor = createPlateEditor({
  plugins: [
    // Comment out or remove suspected plugins
    // HeadingPlugin,
    // BoldPlugin,
    // ...other plugins
  ],
});
```

Gradually add plugins back until you identify the one causing the issue.

### 3. Use React DevTools

React DevTools can be invaluable for debugging Plate components:

1. Install the React DevTools browser extension.
2. Open your app and the DevTools.
3. Navigate to the Components tab.
4. Inspect Plate components, their props, and state.

### 4. Use Browser DevTools Breakpoints

Set breakpoints in your code using browser DevTools:

1. Open your app in the browser and open DevTools.
2. Navigate to the Sources tab.
3. Find your source file and click on the line number where you want to set a breakpoint.
4. Interact with your editor to trigger the breakpoint.
5. Inspect variables and step through the code.

### 5. Create Minimal Reproducible Examples

If you're facing a complex issue:

1. Pick a [template](/docs/installation).
2. Add only the essential plugins and components to reproduce the issue.
3. If the issue persists, [open an issue on GitHub](https://github.com/udecode/plate/issues/new?assignees=&labels=bug&projects=&template=bug.yml) or share your example on [Discord](https://discord.gg/mAZRuBzGM3).

### 6. Use Redux DevTools for zustand stores

Zustand and thus zustand-x works with the Redux DevTools browser extension. It can be very useful to help track state changes in zustand stores.

Follow the [zustand documentation](https://zustand.docs.pmnd.rs/middlewares/devtools) to get going with Redux DevTools and zustand.


## Debug Error Types

Plate uses several predefined error types to help identify specific issues during development. Here's a list of these error types and their descriptions:

### DEFAULT

A general error that doesn't fit into other specific categories. Used when no other error type is applicable to the situation.

### OPTION_UNDEFINED

Thrown when an attempt is made to access an undefined plugin option. This occurs when trying to use a plugin option that hasn't been set or is undefined.

### OVERRIDE_MISSING

Indicates that an expected override is missing in a plugin configuration. This happens when a plugin expects certain overrides to be provided, but they are not present in the configuration.

### PLUGIN_DEPENDENCY_MISSING

Occurs when a required plugin dependency is not found. This error is thrown when a plugin depends on another plugin that hasn't been registered or included in the editor configuration.

### PLUGIN_MISSING

Indicates an attempt to use a plugin that hasn't been registered. This happens when trying to access or use a plugin that is not part of the current editor configuration.

### USE_CREATE_PLUGIN

Thrown when a plugin wasn't created using `createSlatePlugin` or `createPlatePlugin` function. This error occurs when a plugin is added to the editor without being properly created using the designated function.

### USE_ELEMENT_CONTEXT

Indicates that the `useElement` hook is being used outside of the appropriate element context. This occurs when trying to access element-specific data or functionality outside of the correct component context.

### PLUGIN_NODE_TYPE

Thrown when a plugin is incorrectly configured as both an element and a leaf. This error occurs when a plugin's configuration contradicts itself by setting both `isElement` and `isLeaf` to true.


# Editing Behavior

Source: https://platejs.org/docs/editing-behavior

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Editing Behavior
description: How Plate handles Enter, Backspace, merge, normalize, and selection behavior.
---

Editing behavior is the path from a key press or transform to the final document shape. Use [Plugin Rules](/docs/plugin-rules) for declarative node policy, and use [Editor Methods](/docs/editor-methods) when you need an imperative transform. This guide shows how break, delete, merge, normalize, and selection behavior fit together.

## On This Page

- [Choose the Right Surface](#choose-the-right-surface)
- [Runtime Pipeline](#runtime-pipeline)
- [Break Behavior](#break-behavior)
- [Delete Behavior](#delete-behavior)
- [Merge Behavior](#merge-behavior)
- [Normalize Behavior](#normalize-behavior)
- [Selection Behavior](#selection-behavior)
- [Recipes](#recipes)
- [API Reference](#api-reference)

## Choose the Right Surface

Most editing behavior belongs in `plugin.rules`. Reach for custom transforms only when the rule table cannot express the behavior.

| Need | Use |
| --- | --- |
| Change how `Enter` works in a node. | `rules.break` |
| Change how `Backspace` works at the start of a block. | `rules.delete` |
| Decide whether an empty sibling disappears during a merge. | `rules.merge` |
| Remove empty nodes during normalization. | `rules.normalize` |
| Control mark or inline boundaries while typing and moving. | `rules.selection` |
| Apply one plugin's rules to another node type. | `rules.match` |
| Run product-specific behavior that rules cannot express. | `.overrideEditor()` or an explicit `editor.tf.*` command |

Rules keep common editor policy close to the plugin that owns the node. Transforms are still the right tool for commands, toolbar actions, and behavior that depends on app state.

## Runtime Pipeline

Plate resolves plugins first, then core plugins wrap Slate APIs and transforms.

| Layer | Owner | Handles |
| --- | --- | --- |
| `OverridePlugin` | Core runtime | Node flags, break rules, delete rules, merge rules, normalize rules. |
| `AffinityPlugin` | Core runtime | `rules.selection` for mark and inline boundaries. |
| Feature plugins | Feature packages | Default rules for headings, callouts, lists, links, tables, marks, and other nodes. |
| App plugins | Your app | Local overrides, custom node policy, and custom transforms. |

The normal flow is:

```txt
key press or command
  -> optional input rule for typed patterns
  -> plugin rule lookup for the current node
  -> editor.tf transform
  -> merge guard when nodes are joined
  -> normalization
  -> selection affinity cleanup
```

Input rules are for text patterns such as markdown shortcuts and autolinks. Plugin rules are for node behavior such as "a heading resets to paragraph on Backspace" or "a callout inserts soft breaks on Enter."

## Break Behavior

`rules.break` controls `editor.tf.insertBreak()`, which is what `Enter` calls.

Plate checks the current block and handles these cases in order:

| Case | Rule | What happens |
| --- | --- | --- |
| Empty collapsed block | `break.empty` | Runs `reset`, `exit`, `lift`, `deleteExit`, or falls through. |
| Cursor after a trailing newline | `break.emptyLineEnd` | Runs `exit`, `deleteExit`, or falls through. |
| Normal Enter | `break.default` | Runs `lineBreak`, `exit`, `deleteExit`, or falls through. |
| Split created a new block | `break.splitReset` | Resets the new block to the default type. |

Use `splitReset` for blocks that should not keep their type after a normal split.

```tsx title="plugins.tsx" showLineNumbers
import { H1Plugin } from '@platejs/basic-nodes/react';

export const AppH1Plugin = H1Plugin.configure({
  rules: {
    break: {
      splitReset: true,
    },
  },
});
```

Use `lineBreak` and `deleteExit` for container-like blocks that need soft lines before they leave the block.

```tsx title="plugins.tsx" showLineNumbers
import { CalloutPlugin } from '@platejs/callout/react';

export const AppCalloutPlugin = CalloutPlugin.configure({
  rules: {
    break: {
      default: 'lineBreak',
      empty: 'reset',
      emptyLineEnd: 'deleteExit',
    },
  },
});
```

That callout keeps normal Enter inside the callout, resets empty callouts to paragraphs, and exits after a trailing empty line.

## Delete Behavior

`rules.delete` controls collapsed `Backspace` behavior. Expanded selections still delete through the normal fragment path unless the whole editor is selected.

Plate checks collapsed `deleteBackward` in this order:

| Case | Rule | What happens |
| --- | --- | --- |
| Cursor at the start of the current block | `delete.start` | Runs `reset`, `lift`, or falls through. |
| Current block is empty | `delete.empty` | Runs `reset` or falls through. |
| Cursor is at the start of the document | Core default | Resets the first block. |
| Nothing handled the case | Slate transform | Runs the original delete transform. |

Use `start: 'reset'` for formatted text blocks that should become paragraphs before they merge into the previous block.

```tsx title="plugins.tsx" showLineNumbers
import { H1Plugin } from '@platejs/basic-nodes/react';

export const AppH1Plugin = H1Plugin.configure({
  rules: {
    delete: {
      start: 'reset',
    },
  },
});
```

Use `start: 'lift'` for nested blocks that should move out one ancestor level.

```tsx title="plugins.tsx" showLineNumbers
import { createPlatePlugin } from 'platejs/react';

export const QuoteItemPlugin = createPlatePlugin({
  key: 'quote_item',
  node: {
    isElement: true,
  },
  rules: {
    delete: {
      start: 'lift',
    },
  },
});
```

When a selection spans multiple blocks, Plate deletes the selected content and then calls `editor.tf.mergeNodes()` at the end boundary. That means cross-block deletion can still enter the merge pipeline below.

## Merge Behavior

Merge behavior decides whether two nodes can join and whether empty nodes at the boundary disappear.

`editor.tf.mergeNodes()` calls `editor.api.shouldMergeNodes(prev, next, options)` before it applies the merge. Plate's merge rules add three important guards:

| Case | Behavior |
| --- | --- |
| Empty text node before the merge point | Remove it when it is not the first child. |
| Empty previous sibling | Remove it only when the owning plugin has `rules.merge.removeEmpty: true`. |
| Target node is void | Do not delete the void target by default; remove the current empty node instead when possible. |

Use `removeEmpty: true` for text-like blocks such as paragraphs and headings.

```tsx title="plugins.tsx" showLineNumbers
import { H1Plugin } from '@platejs/basic-nodes/react';

export const AppH1Plugin = H1Plugin.configure({
  rules: {
    merge: {
      removeEmpty: true,
    },
  },
});
```

Keep `removeEmpty: false` for structural nodes that own layout, children, or wrappers. Tables, rows, cells, columns, and callouts should not disappear just because a merge crosses their boundary.

```tsx title="plugins.tsx" showLineNumbers
import { CalloutPlugin } from '@platejs/callout/react';

export const StableCalloutPlugin = CalloutPlugin.configure({
  rules: {
    merge: {
      removeEmpty: false,
    },
  },
});
```

<Callout>
  Merge rules are not table cell merge commands. `rules.merge` protects
  document structure during node joins. Table cell merge and split commands live
  on `editor.tf.table.merge()` and `editor.tf.table.split()`.
</Callout>

## Normalize Behavior

`rules.normalize` runs during Slate normalization.

Use `normalize.removeEmpty` for elements that should not exist without text content. Links use this shape because an empty link has no useful editing surface.

```tsx title="plugins.tsx" showLineNumbers
import { LinkPlugin } from '@platejs/link/react';

export const AppLinkPlugin = LinkPlugin.configure({
  rules: {
    normalize: {
      removeEmpty: true,
    },
  },
});
```

Keep normalization rules boring. If a node needs a rich repair strategy, write a dedicated normalizer with `.overrideEditor()` so the behavior is explicit and testable.

## Selection Behavior

`rules.selection` controls how marks and inline-like boundaries behave while typing, deleting, and moving the cursor.

| Affinity | Use for |
| --- | --- |
| `default` | Normal Slate boundary behavior. |
| `directional` | Links and highlights where cursor direction decides whether typed text stays inside. |
| `outward` | Comment and suggestion marks where edge typing should leave the mark. |
| `hard` | Boundaries that should take an extra arrow-key step to cross. |

Node flags also affect editing behavior. `node.isInline`, `node.isVoid`, `node.isSelectable`, and `node.isMarkableVoid` are resolved by the core override layer before selection and transform logic runs.

## Recipes

| Behavior | Configure |
| --- | --- |
| Heading resets to paragraph on Backspace. | `rules.delete.start: 'reset'` |
| Heading splits into paragraph on Enter. | `rules.break.splitReset: true` |
| Callout keeps Enter inside the block. | `rules.break.default: 'lineBreak'` |
| Empty callout becomes a paragraph. | `rules.break.empty: 'reset'` or `rules.delete.start: 'reset'` |
| Nested item outdents on Backspace. | `rules.delete.start: 'lift'` |
| Empty text block disappears during merge. | `rules.merge.removeEmpty: true` |
| Structural wrapper survives merge. | `rules.merge.removeEmpty: false` |
| Empty inline element disappears. | `rules.normalize.removeEmpty: true` |
| Link boundary follows cursor direction. | `rules.selection.affinity: 'directional'` |

For list metadata and code-block children, use `rules.match` so the feature plugin can apply its rule to the child block that actually contains the selection.

## API Reference

| Surface | Owner | Reference |
| --- | --- | --- |
| `rules.break` | Core rule engine plus feature plugin config | [Plugin Rules](/docs/plugin-rules#rulesbreak) |
| `rules.delete` | Core rule engine plus feature plugin config | [Plugin Rules](/docs/plugin-rules#rulesdelete) |
| `rules.merge` | Core rule engine plus feature plugin config | [Plugin Rules](/docs/plugin-rules#rulesmerge) |
| `rules.normalize` | Core rule engine plus feature plugin config | [Plugin Rules](/docs/plugin-rules#rulesnormalize) |
| `rules.selection` | Affinity core plugin plus feature plugin config | [Plugin Rules](/docs/plugin-rules#rulesselection) |
| `rules.match` | Core rule lookup plus feature plugin config | [Plugin Rules](/docs/plugin-rules#rulesmatch) |
| `editor.tf.mergeNodes()` | Slate transform patched by Plate | [Editor Transforms](/docs/api/slate/editor-transforms#mergenodes) |
| `editor.api.shouldMergeNodes()` | Slate editor API patched by Plate | [Editor API](/docs/api/slate/editor-api#shouldmergenodes) |
| `editor.tf.table.merge()` | Table feature package | [Table](/docs/table#editing-behavior) |

Done. Rules describe the policy; transforms do the work.


# Editor Methods

Source: https://platejs.org/docs/editor-methods

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Editor Methods
description: Read, mutate, and configure a Plate editor instance.
---

The Plate editor exposes two main method surfaces: `editor.api` for reads and
helpers, and `editor.tf` for transforms that change editor state. In React, pick
the editor hook by how often the component should re-render.

## Access the Editor

| Need | Use |
| --- | --- |
| Read the editor inside callbacks without re-rendering. | `useEditorRef()` |
| Re-render from one derived value. | `useEditorSelector(selector, deps)` |
| Re-render on every editor change. | `useEditorState()` |
| Reach the active editor from outside a `<Plate>` subtree. | `<PlateController>` plus the same hooks. |

```tsx title="components/bold-button.tsx" showLineNumbers
import { useEditorRef, useEditorSelector } from 'platejs/react';

import { Button } from '@/components/ui/button';

export function BoldButton() {
  const editor = useEditorRef();
  const hasSelection = useEditorSelector(
    (editor) => Boolean(editor.selection),
    []
  );

  return (
    <Button
      disabled={!hasSelection}
      onClick={() => editor.tf.toggleMark('bold')}
    >
      Bold
    </Button>
  );
}
```

### `useEditorRef`

`useEditorRef` returns the stable editor object. Use it for event handlers,
effects, commands, and reads that should not cause a render.

```tsx title="components/insert-paragraph-button.tsx"
const editor = useEditorRef();

editor.tf.insertNodes({
  children: [{ text: 'Inserted paragraph' }],
  type: 'p',
});
```

### `useEditorSelector`

`useEditorSelector` subscribes to a derived value. Return a primitive or provide
`equalityFn` when the selected value needs custom comparison.

```tsx title="components/selection-state.tsx"
const isSelectionExpanded = useEditorSelector(
  (editor) => editor.api.isExpanded(),
  []
);
```

### `useEditorState`

`useEditorState` subscribes to the whole editor state. Use it only when the UI
really needs to update on every editor change.

```tsx title="components/selection-debug.tsx"
const editor = useEditorState();

return <pre>{JSON.stringify(editor.selection, null, 2)}</pre>;
```

## Outside Plate

Wrap shared UI in `PlateController` when a toolbar, side panel, or inspector
lives outside a single `<Plate>` tree.

```tsx title="components/editor-shell.tsx" showLineNumbers
import type React from 'react';

import { PlateController, useEditorMounted, useEditorRef } from 'platejs/react';

import { Button } from '@/components/ui/button';

export function EditorShell({ children }: { children: React.ReactNode }) {
  return (
    <PlateController>
      <ActiveEditorToolbar />
      {children}
    </PlateController>
  );
}

function ActiveEditorToolbar() {
  const editor = useEditorRef();
  const mounted = useEditorMounted();

  if (!mounted || editor.meta.isFallback) return null;

  return (
    <Button onClick={() => editor.tf.focus({ edge: 'end' })}>
      Focus editor
    </Button>
  );
}
```

`PlateController` resolves an editor by explicit `id`, focused editor, then
primary editors. If a controller exists but no editor store is ready, hooks
return a fallback editor; check `useEditorMounted()` or
`!editor.meta.isFallback` before running transforms.

## Editor API and Transforms

Use `editor.api` for queries and DOM/editor helpers. Use `editor.tf` for
operations that change the document, selection, history, focus, or plugin state.
`editor.transforms` is an alias for `editor.tf`.

```ts title="editor-methods.ts" showLineNumbers
const selectedText = editor.selection
  ? editor.api.string(editor.selection)
  : '';

const currentBlock = editor.api.block();

if (selectedText && !editor.api.hasMark('bold')) {
  editor.tf.toggleMark('bold');
}

editor.tf.insertNodes({
  children: [{ text: 'New paragraph' }],
  type: 'p',
});
```

| Surface | Examples | Use for |
| --- | --- | --- |
| `editor.api` | `string`, `block`, `findPath`, `hasMark`, `isExpanded` | Reading editor state, resolving paths, checking selection. |
| `editor.tf` | `insertNodes`, `setNodes`, `toggleMark`, `focus`, `reset` | Mutating document or editor state. |
| `editor.transforms` | Same as `editor.tf` | Compatibility alias. Prefer `editor.tf` in new code. |

## Plugin Methods

Plugin helpers let TypeScript infer APIs and transforms from the plugin you
pass in.

```ts title="table-methods.ts" showLineNumbers
import { TablePlugin } from '@platejs/table/react';

const api = editor.getApi(TablePlugin);
const tf = editor.getTransforms(TablePlugin);

const cell = api.create.tableCell();

tf.insert.tableRow();
```

| Method | Use for |
| --- | --- |
| `editor.getApi(plugin)` | Typed plugin APIs merged onto `editor.api`. |
| `editor.getTransforms(plugin)` | Typed plugin transforms merged onto `editor.tf`. |
| `editor.getPlugin(plugin)` | The resolved plugin instance for a key or plugin object. |
| `editor.getType(pluginKey)` | The node type registered for a plugin key. |
| `editor.getInjectProps(plugin)` | Resolved injected node props for a plugin. |

## Plugin Options

Use editor option methods when imperative code needs to read or write plugin
configuration. Use `usePluginOption` or `usePluginOptions` when React UI needs
to re-render from option state.

```tsx title="components/find-replace-control.tsx" showLineNumbers
import { FindReplacePlugin } from '@platejs/find-replace';
import { useEditorRef, usePluginOption } from 'platejs/react';

export function FindReplaceControl() {
  const editor = useEditorRef();
  const search = usePluginOption(FindReplacePlugin, 'search');

  return (
    <input
      value={search}
      onChange={(event) => {
        editor.setOption(FindReplacePlugin, 'search', event.target.value);
      }}
    />
  );
}
```

```ts title="plugin-options.ts"
const options = editor.getOptions(FindReplacePlugin);

editor.setOptions(FindReplacePlugin, {
  search: 'Plate',
});

editor.setOptions(FindReplacePlugin, (draft) => {
  draft.search = draft.search.trim();
});
```

| Method | Use for |
| --- | --- |
| `editor.getOption(plugin, key, ...args)` | One option or selector value. |
| `editor.getOptions(plugin)` | Current option state for a plugin. |
| `editor.setOption(plugin, key, value)` | One option update. |
| `editor.setOptions(plugin, partial)` | Merge multiple option fields. |
| `editor.setOptions(plugin, updater)` | Mutate option state through a draft updater. |
| `editor.getOptionsStore(plugin)` | Low-level access to the plugin options store. |

## Next Steps

| Task | Guide |
| --- | --- |
| Configure editor creation. | [Editor Configuration](/docs/editor) |
| Add plugin APIs and transforms. | [Plugin Methods](/docs/plugin-methods) |
| Read plugin context inside components. | [Plugin Context](/docs/plugin-context) |
| Browse editor query contracts. | [Editor API](/docs/api/slate/editor-api) |
| Browse editor transform contracts. | [Editor Transforms](/docs/api/slate/editor-transforms) |


# Editor Configuration

Source: https://platejs.org/docs/editor

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Editor Configuration
description: Learn how to configure and customize the Plate editor.
---

This guide covers the configuration options for the Plate editor, including basic setup, plugin management, and advanced configuration techniques.

## Basic Editor Configuration

To create a basic Plate editor, you can use the `createPlateEditor` function, or `usePlateEditor` in a React component:

```ts
import { createPlateEditor } from 'platejs/react';

const editor = createPlateEditor({
  plugins: [HeadingPlugin],
});
```

### Initial Value

Set the initial content of the editor:

```ts
const editor = createPlateEditor({
  value: [
    {
      type: 'p',
      children: [{ text: 'Hello, Plate!' }],
    },
  ],
});
```

You can also initialize the editor with an HTML string and the associated plugins:

```ts
const editor = createPlateEditor({
  plugins: [BoldPlugin, ItalicPlugin],
  value: '<p>This is <b>bold</b> and <i>italic</i> text!</p>',
});
```

For a comprehensive list of plugins that support HTML string deserialization, refer to the [Plugin Deserialization Rules](/docs/html#plugin-deserialization-rules) section.

### Async Initial Value

If you need to fetch the initial value asynchronously (e.g., from an API), you can pass an async function directly to the `value` option:

```tsx
function AsyncEditor() {
  const editor = usePlateEditor({
    value: async () => {
      // Simulate fetching data from an API
      const response = await fetch('/api/document');
      const data = await response.json();
      return data.content;
    },
    autoSelect: 'end',
    onReady: ({ editor, value }) => {
      console.info('Editor ready with loaded value:', value);
    },
  });

  if (!editor.children.length) return <div>Loading…</div>;

  return (
    <Plate editor={editor}>
      <EditorContainer>
        <Editor />
      </EditorContainer>
    </Plate>
  );
}
```

### Adding Plugins

You can add plugins to your editor by including them in the `plugins` array:

```ts
const editor = createPlateEditor({
  plugins: [HeadingPlugin, ListPlugin],
});
```

### Max Length

Set the maximum length of the editor:

```ts
const editor = createPlateEditor({
  maxLength: 100,
});
```

## Advanced Configuration

### Editor ID

Set a custom id for the editor:

```ts
const editor = createPlateEditor({
  id: 'my-custom-editor-id',
});
```

If defined, you should always pass the `id` as the first argument in any editor retrieval methods.

### Node ID

Plate includes a built-in system for automatically assigning unique IDs to nodes, which is crucial for certain plugins and for data persistence strategies that rely on stable identifiers.

This feature is enabled by default. You can customize its behavior or disable it entirely through the `nodeId` option.

#### Configuration

To configure Node ID behavior, pass an object to the `nodeId` property when creating your editor:

```ts
const editor = usePlateEditor({
  // ... other plugins and options
  nodeId: {
    // Function to generate IDs (default: nanoid(10))
    idCreator: () => uuidv4(),

    // Exclude inline elements from getting IDs (default: true)
    filterInline: true, 

    // Exclude text nodes from getting IDs (default: true)
    filterText: true,

    // Reuse IDs on undo/redo and copy/paste if not in document (default: false)
    // Set to true if IDs should be stable across such operations.
    reuseId: false,

    // Control initial-value ID assignment (default: 'if-needed')
    // Use 'always' to fill every missing ID in the initial value.
    initialValueIds: 'always',
    
    // Prevent overriding IDs when inserting nodes with an existing id (default: false)
    disableInsertOverrides: false,

    // Only allow specific node types to receive IDs (default: all)
    allow: ['p', 'h1'], 

    // Exclude specific node types from receiving IDs (default: [])
    exclude: ['code_block'],

    // Custom filter function to determine if a node should get an ID
    filter: ([node, path]) => {
      // Example: Only ID on top-level blocks
      return path.length === 1;
    },
  },
});
```

<Callout type="note">
  The `NodeIdPlugin` (which handles this) is part of the core plugins and is automatically included. You only need to specify the `nodeId` option if you want to customize its default behavior.
</Callout>

#### Disabling Node IDs

If you don't need automatic node IDs, you can disable the feature:

```ts
const editor = usePlateEditor({
  // ... other plugins and options
  nodeId: false, // This will disable the NodeIdPlugin
});
```

By disabling this, certain plugins that rely on node IDs will not function properly. The following plugins require block IDs to work:

- **[Block Selection](/docs/block-selection)** - Needs IDs to track which blocks are selected
- **[Block Menu](/docs/block-menu)** - Requires IDs to show context menus for specific blocks  
- **[Drag & Drop](/docs/dnd)** - Uses IDs to identify blocks during drag operations
- **[Table](/docs/table)** - Relies on IDs for cell selection
- **[Table of Contents](/docs/toc)** - Needs heading IDs for navigation and scrolling
- **[Toggle](/docs/toggle)** - Uses IDs to track which toggles are open/closed

### Navigation Feedback

Plate also includes a built-in navigation feedback plugin for "you landed here"
UX after TOC jumps, footnote navigation, search jumps, and custom outline
movement.

This feature is enabled by default. You only need to touch the
`navigationFeedback` option when you want to change the flash duration or turn
the plugin off.

#### Configuration

```ts
const editor = createPlateEditor({
  navigationFeedback: {
    duration: 1200,
  },
});
```

<Callout type="note">
  The `NavigationFeedbackPlugin` is part of the core plugins and is
  automatically included. Use `navigationFeedback` for normal configuration and
  keep `rootPlugin.configurePlugin(...)` for advanced escape-hatch work.
</Callout>

#### Disabling Navigation Feedback

```ts
const editor = createPlateEditor({
  navigationFeedback: false,
});
```

### Normalization

Control whether the editor should normalize its content on initialization:

```ts
const editor = createPlateEditor({
  shouldNormalizeEditor: true,
});
```

Note that normalization may take a few dozen milliseconds for large documents, such as the playground value.

### Auto-selection

Configure the editor to automatically select a range:

```ts
const editor = createPlateEditor({
  autoSelect: 'end', // or 'start', or true
});
```

This is not the same as auto-focus: you can select text without focusing the editor.

### Component Overrides

Override default components for plugins:

```ts
const editor = createPlateEditor({
  plugins: [HeadingPlugin],
  components: {
    [ParagraphPlugin.key]: CustomParagraphComponent,
    [HeadingPlugin.key]: CustomHeadingComponent,
  },
});
```

### Plugin Overrides

Override specific plugin configurations:

```ts
const editor = createPlateEditor({
  plugins: [HeadingPlugin],
  override: {
    plugins: {
      [ParagraphPlugin.key]: {
        options: {
          customOption: true,
        },
      },
    },
  },
});
```

### Disable Plugins

Disable specific plugins:

```ts
const editor = createPlateEditor({
  plugins: [HeadingPlugin, ListPlugin],
  override: {
    enabled: {
      [HistoryPlugin.key]: false,
    },
  },
});
```

### Overriding Plugins

You can override core plugins or previously defined plugins by adding a plugin with the same key. The last plugin with a given key wins:

```ts
const CustomParagraphPlugin = createPlatePlugin({
  key: 'p',
  // Custom implementation
});

const editor = createPlateEditor({
  plugins: [CustomParagraphPlugin],
});
```

### Root Plugin

From the root plugin, you can configure any plugin:

```ts
const editor = createPlateEditor({
  plugins: [HeadingPlugin],
  rootPlugin: (plugin) =>
    plugin.configurePlugin(LengthPlugin, {
    options: {
        maxLength: 100,
      },
    }),
});
```

## Typed Editor

`createPlateEditor` will automatically infer the types for your editor from the value and the plugins you pass in. For explicit type creation, use the generics:

### Plugins Type

```ts
const editor = createPlateEditor<Value, typeof TablePlugin | typeof LinkPlugin>({
  plugins: [TablePlugin, LinkPlugin],
});

// Usage
editor.tf.insert.tableRow()
```

### Value Type

For more complex editors, you can define your types in a separate file (e.g., `plate-types.ts`):

```ts
import type { TElement, TText } from 'platejs';
import type { TPlateEditor } from 'platejs/react';

// Define custom element types
interface ParagraphElement extends TElement {
  align?: 'left' | 'center' | 'right' | 'justify';
  children: RichText[];
  type: typeof ParagraphPlugin.key;
}

interface ImageElement extends TElement {
  children: [{ text: '' }]
  type: typeof ImagePlugin.key;
  url: string;
}

// Define custom text types
interface FormattedText extends TText {
  bold?: boolean;
  italic?: boolean;
}

export type MyRootBlock = ParagraphElement | ImageElement;

// Define the editor's value type
export type MyValue = MyRootBlock[];

// Define the custom editor type
export type MyEditor = TPlateEditor<MyValue, typeof TablePlugin | typeof LinkPlugin>;

export const useMyEditorRef = () => useEditorRef<MyEditor>();

// Usage
const value: MyValue = [{
  type: 'p',
  children: [{ text: 'Hello, Plate!' }],
}]

const editorInferred = createPlateEditor({
  plugins: [TablePlugin, LinkPlugin],
  value,
});

// or 
const editorExplicit = createPlateEditor<MyValue, typeof TablePlugin | typeof LinkPlugin>({
  plugins: [TablePlugin, LinkPlugin],
  value,
});
```


# Feature Kits

Source: https://platejs.org/docs/feature-kits

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Feature Kits
description: Use registry kits to add groups of Plate plugins and UI wiring.
---

Feature kits are app-owned registry files that group related Plate plugins, components, shortcuts, input rules, and helper UI.
Use them to start from working Plate UI wiring, then edit the installed kit when your app needs different behavior.

## Kit Types

| Kit type | Example | Use for |
| --- | --- | --- |
| Client/UI kit | `basic-nodes-kit`, `table-kit`, `media-kit` | Editable React editors with Plate UI components. |
| Base kit | `basic-blocks-base-kit`, `table-base-kit` | Static rendering and server-safe editor setup. |
| Full editor kit | `editor-kit` | A complete client editor feature stack. |
| Full base kit | `editor-base-kit` | A broad static/base plugin stack. |

Feature kits live under `components/editor/plugins` after installation. Full
editor kits like `editor-kit` and `editor-base-kit` live under
`components/editor`. They are normal TypeScript files in your app, not package
exports locked inside `node_modules`.

## Use a Kit

Install the kit through the Plate registry, then import it from your app.

```tsx title="components/editor.tsx" showLineNumbers
import { Plate, usePlateEditor } from 'platejs/react';

import { BasicNodesKit } from '@/components/editor/plugins/basic-nodes-kit';
import { TableKit } from '@/components/editor/plugins/table-kit';
import { Editor, EditorContainer } from '@/components/ui/editor';

export function MyEditor() {
  const editor = usePlateEditor({
    plugins: [...BasicNodesKit, ...TableKit],
  });

  return (
    <Plate editor={editor}>
      <EditorContainer>
        <Editor />
      </EditorContainer>
    </Plate>
  );
}
```

`BasicNodesKit` composes `BasicBlocksKit` and `BasicMarksKit`. For example,
`BasicBlocksKit` wires paragraph, headings, blockquote, and horizontal rule
plugins to their Plate UI components; `BasicMarksKit` wires marks, input rules,
shortcuts, and mark leaf components.

## Choose the Right Kit

| Need | Start with |
| --- | --- |
| Paragraphs, headings, blockquotes, marks. | `basic-nodes-kit` |
| Tables with table UI components. | `table-kit` |
| Images, video, audio, files, embeds, captions. | `media-kit` |
| Comments and discussions. | `comment-kit` plus `discussion-kit` |
| AI menu, AI nodes, cursor overlay, and Markdown support. | `ai-kit` |
| Full editable editor stack. | `editor-kit` |
| Static or server-rendered output. | `editor-base-kit` or focused `*-base-kit` files |

Plugin pages show the recommended kit in their installation section. Use the kit
source when you need the exact plugin list, imported UI components, shortcuts,
or registry dependencies.

## Base Kits

Base kits use base plugins and static components. They are the right starting
point for [Static Rendering](/docs/static), [Node.js](/docs/installation/node),
and other non-editable pipelines.

```ts title="static-editor.ts"
import { BaseEditorKit } from '@/components/editor/editor-base-kit';
import { createStaticEditor } from 'platejs/static';

const editor = createStaticEditor({
  plugins: BaseEditorKit,
});
```

Use client kits in editable React editors. Use base kits when React editor hooks,
editable components, floating UI, or browser-only behavior should stay out of
the runtime.

## Customize a Kit

Because kits are copied into your app, the cleanest customization is usually to
edit the installed kit file.

```tsx title="components/editor/plugins/my-basic-kit.tsx"
import { H1Plugin } from '@platejs/basic-nodes/react';
import { ParagraphPlugin } from 'platejs/react';

import { H1Element } from '@/components/ui/heading-node';
import { ParagraphElement } from '@/components/ui/paragraph-node';

export const MyBasicKit = [
  ParagraphPlugin.withComponent(ParagraphElement),
  H1Plugin.configure({
    node: {
      component: H1Element,
    },
    shortcuts: {
      toggle: { keys: 'mod+alt+1' },
    },
  }),
];
```

Use manual plugin setup when you only need a small part of a kit, when the app
does not use Plate UI components, or when a feature needs a different dependency
boundary.

## Registry Names

Kits are registry items. These names map to files in
`components/editor/plugins` or `components/editor`.

| Registry item | Installs |
| --- | --- |
| `basic-nodes-kit` | `BasicNodesKit`, `BasicBlocksKit`, and `BasicMarksKit` dependencies. |
| `table-kit` | `TableKit` and table UI components. |
| `media-kit` | `MediaKit` without a media upload API route. |
| `media-uploadthing-kit` | `media-kit` plus the UploadThing API route. |
| `editor-kit` | The full editable editor kit. |
| `editor-base-kit` | The full static/base kit. |

## Next Steps

| Task | Guide |
| --- | --- |
| Install registry items. | [Plate UI](/docs/installation/plate-ui) |
| Configure editor creation. | [Editor Configuration](/docs/editor) |
| Compose plugin APIs and options. | [Plugin Methods](/docs/plugin-methods) |
| Render without an editable React editor. | [Static Rendering](/docs/static) |


# Form

Source: https://platejs.org/docs/form

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Form
description: How to integrate Plate editor with react-hook-form.
---

While Plate is typically used as an **uncontrolled** input, there are valid scenarios where you want to integrate the editor within a form library like [**react-hook-form**](https://www.react-hook-form.com) or the [**Form**](https://ui.shadcn.com/docs/components/form) component from **shadcn/ui**. This guide walks through best practices and common pitfalls.

## When to Integrate Plate with a Form

- **Form Submission**: You want the editor's content to be included along with other fields (e.g., `<input>`, `<select>`) when the user submits the form.
- **Validation**: You want to validate the editor's content (e.g., checking if it's empty) at the same time as other form fields.
- **Form Data Management**: You want to store the editor content in the same store (like `react-hook-form`'s state) as other fields.

However, keep in mind the warning about **fully controlling** the editor value. Plate strongly prefer an uncontrolled model. If you attempt to replace the editor's internal state too frequently, you can break **selection**, **history**, or cause performance issues. The recommended pattern is to treat the editor as uncontrolled, but still **sync** form data on certain events.

## Approach 1: Sync on `onChange`

This is the most straightforward approach: each time the editor changes, update your form field's value. For small documents or infrequent changes, this is usually acceptable.

### React Hook Form Example

```tsx
import { useForm } from 'react-hook-form';
import type { Value } from 'platejs';
import { Plate, PlateContent, usePlateEditor } from 'platejs/react';

type FormData = {
  content: Value;
};

export function RHFEditorForm() {
  const initialValue = [
    { type: 'p', children: [{ text: 'Hello from react-hook-form!' }] },
  ]

  // Setup react-hook-form
  const { register, handleSubmit, setValue } = useForm<FormData>({
    defaultValues: {
      content: initialValue,
    },
  });

  // Create/configure the Plate editor
  const editor = usePlateEditor({ value: initialValue });

  // Register the field for react-hook-form
  register('content', { /* validation rules... */ });

  const onSubmit = (data: FormData) => {
    // data.content will have final editor content
    console.info('Submitted:', data.content);
  };

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <Plate
        editor={editor}
        onChange={({ value }) => {
          // Sync editor changes to the form
          setValue('content', value);
        }}
      >
        <PlateContent placeholder="Type here..." />
      </Plate>

      <button type="submit">Submit</button>
    </form>
  );
}
```

**Notes**:
1. **`defaultValues.content`**: your initial editor content.
2. **`register('content')`**: signals to RHF that the field is tracked.  
3. **`onChange({ value })`**: calls `setValue('content', value)` each time.

If you expect large documents or fast typing, consider debouncing or switching to an `onBlur` approach to reduce form updates.

### shadcn/ui Form Example

[shadcn/ui](https://ui.shadcn.com/docs/components/form) provides a `<Form>` that integrates with react-hook-form. We'll use `<FormField>` to handle the field logic:

```tsx
import {
  Form,
  FormControl,
  FormField,
  FormItem,
  FormLabel,
  FormMessage,
} from '@/components/ui/form';
import { useForm } from 'react-hook-form';
import { Plate, PlateContent, usePlateEditor } from 'platejs/react';

type FormValues = {
  content: any;
};

export function EditorForm() {
  // 1. Create the form
  const form = useForm<FormValues>({
    defaultValues: {
      content: [
        { type: 'p', children: [{ text: 'Hello from shadcn/ui Form!' }] },
      ],
    },
  });

  // 2. Create the Plate editor
  const editor = usePlateEditor();

  const onSubmit = (data: FormValues) => {
    console.info('Submitted data:', data.content);
  };

  return (
    <Form {...form}>
      <form onSubmit={form.handleSubmit(onSubmit)}>
        <FormField
          control={form.control}
          name="content"
          render={({ field }) => (
            <FormItem>
              <FormLabel>Content</FormLabel>
              <FormControl>
                <Plate
                  editor={editor}
                  onChange={({ value }) => {
                    // Sync to the form
                    field.onChange(value);
                  }}
                >
                  <PlateContent placeholder="Type..." />
                </Plate>
              </FormControl>
              <FormMessage />
            </FormItem>
          )}
        />

        <button type="submit">Submit</button>
      </form>
    </Form>
  );
}
```

This approach makes your editor content behave like any other field in the shadcn/ui form.

## Approach 2: Sync on Blur (or Another Trigger)

Instead of syncing on every keystroke, you might only need the final value when the user:
- Leaves the editor (`onBlur`),
- Clicks a “Save” button, or
- Reaches certain form submission logic.

```tsx
<Plate editor={editor}>
  <PlateContent
    onBlur={() => {
      // Only sync on blur
      setValue('content', editor.children);
    }}
  />
</Plate>
```

This reduces overhead but your form state won't reflect partial updates while the user is typing.

## Approach 3: Controlled Replacement (Advanced)

If you want the form to be the single source of truth (completely [controlled](/docs/controlled)):
```ts
editor.tf.setValue(formStateValue);
```
But this has known drawbacks:
- Potentially breaks cursor position and undo/redo.
- Can cause frequent full re-renders for large docs.

**Recommendation**: Stick to a partially uncontrolled model if you can.

## Example: Save & Reset

Here's a more complete form demonstrating both saving and resetting the editor/form:

```tsx
import { useForm } from 'react-hook-form';
import { Plate, PlateContent, usePlateEditor } from 'platejs/react';

function MyForm() {
  const form = useForm({
    defaultValues: {
      content: [
        { type: 'p', children: [{ text: 'Initial content...' }] },
      ],
    },
  });

  const editor = usePlateEditor();

  const onSubmit = (data) => {
    alert(JSON.stringify(data, null, 2));
  };

  return (
    <form onSubmit={form.handleSubmit(onSubmit)}>
      <Plate
        editor={editor}
        onChange={({ value }) => form.setValue('content', value)}
      >
        <PlateContent />
      </Plate>

      <button type="submit">Save</button>

      <button
        type="button"
        onClick={() => {
          // Reset the editor
          editor.tf.reset();
          // Reset the form
          form.reset();
        }}
      >
        Reset
      </button>
    </form>
  );
}
```

- **`onChange`** -> updates form state.
- **Reset** -> calls both `editor.tf.reset()` and `form.reset()` for consistency.

## Migrating from a shadcn Textarea to Plate

If you have a standard [TextareaForm from shadcn/ui docs](https://ui.shadcn.com/docs/components/textarea#form) and want to replace `<Textarea>` with a Plate editor, you can follow these steps:

```tsx
// 1. Original code (TextareaForm)
<FormField
  control={form.control}
  name="bio"
  render={({ field }) => (
    <FormItem>
      <FormLabel>Bio</FormLabel>
      <FormControl>
        <Textarea
          placeholder="Tell us a bit about yourself"
          className="resize-none"
          {...field}
        />
      </FormControl>
      <FormDescription>
        You can <span>@mention</span> other users and organizations.
      </FormDescription>
      <FormMessage />
    </FormItem>
  )}
/>
```

Create a new `EditorField` component:

```tsx
// EditorField.tsx
"use client";

import * as React from "react";
import type { Value } from "platejs";
import { Plate, PlateContent, usePlateEditor } from "platejs/react";

/**
 * A reusable editor component that works like a standard <Textarea>,
 * accepting `value`, `onChange`, and optional placeholder.
 *
 * Usage:
 *
 * <FormField
 *   control={form.control}
 *   name="bio"
 *   render={({ field }) => (
 *     <FormItem>
 *       <FormLabel>Bio</FormLabel>
 *       <FormControl>
 *         <EditorField
 *           {...field}
 *           placeholder="Tell us a bit about yourself"
 *         />
 *       </FormControl>
 *       <FormDescription>Some helpful description...</FormDescription>
 *       <FormMessage />
 *     </FormItem>
 *   )}
 * />
 */
export interface EditorFieldProps
  extends React.HTMLAttributes<HTMLDivElement> {
  /**
   * The current Plate Value. Should be an array of Plate nodes.
   */
  value?: Value;

  /**
   * Called when the editor value changes.
   */
  onChange?: (value: Value) => void;

  /**
   * Placeholder text to display when editor is empty.
   */
  placeholder?: string;
}

export function EditorField({
  value,
  onChange,
  placeholder = "Type here...",
  ...props
}: EditorFieldProps) {
  // We create our editor instance with the provided initial `value`.
  const editor = usePlateEditor({
    value: value ?? [
      { type: "p", children: [{ text: "" }] }, // Default empty paragraph
    ],
  });

  return (
    <Plate
      editor={editor}
      onChange={({ value }) => {
        // Sync changes back to the caller via onChange prop
        onChange?.(value);
      }}
      {...props}
    >
      <PlateContent placeholder={placeholder} />
    </Plate>
  );
}
```

3. Replace the `<Textarea>` with a `<EditorField>` block:

```tsx
"use client";

import { z } from "zod";
import { useForm } from "react-hook-form";
import { zodResolver } from "@hookform/resolvers/zod";

import {
  Form,
  FormControl,
  FormDescription,
  FormField,
  FormItem,
  FormLabel,
  FormMessage,
} from "@/components/ui/form";
import { EditorField } from "./EditorField"; // Import the component above

// 1. Define our validation schema with zod
const FormSchema = z.object({
  bio: z
    .string()
    .min(10, { message: "Bio must be at least 10 characters." })
    .max(160, { message: "Bio must not exceed 160 characters." }),
});

// 2. Build our main form component
export function EditorForm() {
  // 3. Setup the form
  const form = useForm<z.infer<typeof FormSchema>>({
    resolver: zodResolver(FormSchema),
    defaultValues: {
      // Here "bio" is just a string, but our editor
      // will interpret it as initial content if you parse it as JSON
      bio: "",
    },
  });

  // 4. Submission handler
  function onSubmit(data: z.infer<typeof FormSchema>) {
    alert("Submitted: " + JSON.stringify(data, null, 2));
  }

  return (
    <Form {...form}>
      <form onSubmit={form.handleSubmit(onSubmit)} className="space-y-8">
        <FormField
          control={form.control}
          name="bio"
          render={({ field }) => (
            <FormItem>
              <FormLabel>Bio</FormLabel>
              <FormControl>
                <EditorField
                  {...field}
                  placeholder="Tell us a bit about yourself..."
                />
              </FormControl>
              <FormDescription>
                You can <span>@mention</span> other users and organizations.
              </FormDescription>
              <FormMessage />
            </FormItem>
          )}
        />
        <button type="submit" className="py-2 px-4 bg-primary text-white">
          Submit
        </button>
      </form>
    </Form>
  );
}
```

- Any existing form validations or error messages remain the same.
- For default values, ensure `form.defaultValues.bio` is a valid Plate value (array of nodes) instead of a string.
- For controlled values, use `editor.tf.setValue(formStateValue)` with moderation.

## Best Practices

1. **Use an Uncontrolled Editor**: Let Plate manage its own state, updating the form only when necessary.  
2. **Minimize Replacements**: Avoid calling `editor.tf.setValue` too often; it can break selection, history, or degrade performance.  
3. **Validate at the Right Time**: Decide if you need instant validation (typing) or upon blur/submit.  
4. **Reset Both**: If you reset the form, call `editor.tf.reset()` to keep them in sync.


# Performance

Source: https://platejs.org/docs/performance

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Performance
description: Latest Plate vs Slate large-document benchmark snapshot and how to rerun it locally.
---

Performance is about whether the editor stays usable when the document gets
large. This page shows the latest 10k Plate vs Slate snapshot from the docs
benchmark route and the command that reproduces it locally.

## Latest Snapshot

This snapshot was captured on June 2, 2026 from the docs benchmark route in
headless Chrome. The benchmark uses a 10,000-block document with chunked
rendering enabled.

| Workload | Slate | Plate core | Plate with basic plugins |
| --- | ---: | ---: | ---: |
| Open a mixed document | `524 ms` | `866 ms` | `881 ms` |
| Type in a mixed document | `26 ms` | `43 ms` | `35 ms` |
| Open a code-heavy document | `526 ms` | `837 ms` | `1101 ms` |

Read this as a workload snapshot, not as a universal editor score. Mount time,
typing latency, plugin cost, and document shape are different performance
questions.

## Run The Benchmark

Start the docs app:

<CodeBlockCommand
  __bunCommand__="bun run --filter www dev"
  __npmCommand__="npm run dev --workspace www"
  __pnpmCommand__="pnpm --filter www dev"
  __yarnCommand__="yarn workspace www dev"
/>

Then run the public editor benchmark in another terminal:

<CodeBlockCommand
  __bunCommand__="bun run --filter www perf:editor:public"
  __npmCommand__="npm run perf:editor:public --workspace www"
  __pnpmCommand__="pnpm --filter www perf:editor:public"
  __yarnCommand__="yarn workspace www perf:editor:public"
/>

The runner writes a compact JSON summary to
`apps/www/.tmp/editor-perf-public-summary.json`.

## What It Measures

The benchmark keeps the public comparison small on purpose:

| Measurement | What it tells you |
| --- | --- |
| Opening a mixed document | The cost of mounting a large editor with normal rich-text variety. |
| Typing in a mixed document | Whether the editor still responds under a large loaded document. |
| Opening a code-heavy document | The cost of a harder mark-heavy rendering profile. |

Plate core isolates the editor wrapper cost. Plate with basic plugins adds the
common block and mark plugins many editors start with.

## Read The Numbers

Compare like with like:

- use mount numbers for startup cost
- use typing numbers for interaction cost
- use the basic plugin column when you care about a real Plate setup
- rerun the benchmark on your machine before publishing a performance claim

The raw output also includes lower-level Plate diagnostics, such as node-id
cost. Those are useful for debugging Plate itself, but they are not the public
story.

## Source

Use the [Huge Document](/docs/examples/huge-document) demo for manual
inspection. The benchmark route lives at `/dev/editor-perf`, and the runner
lives in `apps/www/scripts/run-editor-perf.mts`.


# Playwright Testing

Source: https://platejs.org/docs/playwright

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Playwright Testing
description: Learn how to write Playwright tests that integrate with Plate.
---

[Playwright](https://playwright.dev/) enables end-to-end testing in headless browsers. This guide covers integrating Playwright with Plate using `@platejs/playwright`.

## Setup

<Steps>

### Install Dependencies

Follow [Playwright's guide](https://playwright.dev/docs/intro) to install Playwright in your app and ensure that you can write basic end-to-end tests.

```bash
npm install @platejs/playwright playwright
```

### Add PlaywrightPlugin

In order for your Playwright tests to access and interact with the editor, you'll need to add `PlaywrightPlugin` to your editor:

```tsx
const editor = createPlateEditor({
  plugins: [
    // other plugins...
    PlaywrightPlugin.configure({ enabled: process.env.NODE_ENV !== 'production' }),
  ]
})
```

This exposes various utilities on `window.platePlaywrightAdapter`.

### Get Editor Handle

<Callout type="info" title="What is an editor handle?">
  Most Playwright test code runs in a non-browser environment. Interacting with a Plate editor requires running JavaScript inside the browser context using Playwright's `evaluate` and `evaluateHandle` [APIs](https://playwright.dev/docs/evaluating).

  A [handle](https://playwright.dev/docs/handles) references a JavaScript object within the browser. The editor handle refers to the `editor` instance of your Plate editor (`JSHandle<PlateEditor>`).
</Callout>

In your Playwright test, get the editor handle before interacting with Plate:

```ts
const editorHandle = await getEditorHandle(page);
```

For multiple editors, specify the editable element:

```ts
const editable = getEditable(page.getByTestId('my-editor-container'));
const editorHandle = await getEditorHandle(page, editable);
```

The locator must match exactly one `[data-slate-editor]` element.

### Start Writing Tests

With the `editorHandle`, you can now write Playwright tests for your editor.

</Steps>

## Examples

### Get a node handle by its path

Use `getNodeByPath` to get a handle referencing the node at a specific path. To make assertions about the value of the node, convert it to JSON using `.jsonValue()`.

```ts
const nodeHandle = await getNodeByPath(page, editorHandle, [0]);

expect(await nodeHandle.jsonValue()).toBe({
  type: 'p',
  children: [{ text: 'My paragraph' }],
});
```

### Get the type of a node

```ts
const firstNodeType = await getTypeAtPath(page, editorHandle, [0]);
expect(firstNodeType).toBe('h1');
```

### Get the DOM node for a node

Often in Playwright, you'll want to reference a specific DOM element in order to make assertions about its state or perform operations involving it.

`getDOMNodeByPath` returns an [ElementHandle](https://playwright.dev/docs/api/class-elementhandle) for the DOM node corresponding to the Plate node at a given path.

```ts
const firstNodeEl = await getDOMNodeByPath(page, elementHandle, [0]);
await firstNodeEl.hover();
```

### Click a node

```ts
await clickAtPath(page, elementHandle, [0]);
```

### Get the selection

```ts
const selection = await getSelection(page, editorHandle);

expect(selection).toBe({
  anchor: { path: [0, 0], offset: 0 },
  focus: { path: [0, 0], offset: 7 },
});
```

### Select a point or range

In order to type at a specific point in the editor, you'll need to select that point using `setSelection`.

If you select a single point (consisting of a `path` and an `offset`), the cursor will be placed at that point. If you select a range (consisting of an `anchor` and a `focus`), that range will be selected. If you select a path, the entire node at that path will be selected.

Make sure you focus the editor before setting the selection. Focusing the editor using `editable.focus()` may not work correctly in WebKit, so the best way of doing this is with `clickAtPath`.

```ts
// Click the first paragraph to focus the editor 
await clickAtPath(page, editorHandle, [0]);

await setSelection(page, editorHandle, {
  path: [0, 0],
  offset: 2,
});

await page.keyboard.type('Hello world!');
```

## Imported queries and transforms

You may want to import a query or a transform such as `getBlockAbove` or `insertNodes` into your Playwright test and use it.

Unfortunately, this is not possible. You can only interact directly with the `editor` instance inside the browser context (using `evaluate` or `evaluateHandle`), and it isn't possible to pass imported functions from Playwright's scope into the browser. This is because neither the `editor` object nor JavaScript functions can be adequately serialized.

The best workaround is to interact with the editor in the same way that a user would, without using any imported queries or transforms. This will make your Playwright tests more likely to catch bugs in your application.

If this isn't practical, you can instead call a method on the `editor` object inside an `evaluate` or `evaluateHandle`. (Use `evaluateHandle` if you need to return a reference to a DOM node or a JavaScript object from the browser. Use `evaluate` if you need to return a serialized copy of a JavaScript object, or if you don't need to return any value.)

Note that while these queries and transforms can't be directly used in Playwright tests, they are available when working with the editor instance in your application code. For more information on how to use these methods in your application, refer to the [Editor Methods](/docs/editor-methods) documentation.

See [Playwright's docs](https://playwright.dev/docs/evaluating) for more information about `evaluate` and `evaluateHandle`.

```ts
await editorHandle.evaluate((editor) => {
  editor.tf.insertNodes(/* ... */);
});
```

See [Playwright's docs](https://playwright.dev/docs/evaluating) for more about `evaluate` and `evaluateHandle`.

## API

### `getEditorHandle`

Gets a handle to the Plate editor instance.

<API name="getEditorHandle">
<APIParameters>
  <APIItem name="page" type="Page">
    Playwright page object.
  </APIItem>
  <APIItem name="editable" type="Locator" optional>
    Locator for editable element. Defaults to first [data-slate-editor].
  </APIItem>
</APIParameters>

<APIReturns type="EditorHandle">
  Handle to Plate editor instance.
</APIReturns>
</API>

### `getNodeByPath`

Retrieves a node at the specified path.

<API name="getNodeByPath">
<APIParameters>
  <APIItem name="page" type="Page">
    Playwright page object.
  </APIItem>
  <APIItem name="editorHandle" type="EditorHandle">
    Handle to editor instance.
  </APIItem>
  <APIItem name="path" type="Path">
    Path to node.
  </APIItem>
</APIParameters>

<APIReturns type="JSHandle<TNode>">
  Handle to node at path.
</APIReturns>
</API>

### `getDOMNodeByPath`

Gets the DOM node for a Plate node at the given path.

<API name="getDOMNodeByPath">
<APIParameters>
  <APIItem name="page" type="Page">
    Playwright page object.
  </APIItem>
  <APIItem name="editorHandle" type="EditorHandle">
    Handle to editor instance.
  </APIItem>
  <APIItem name="path" type="Path">
    Path to node.
  </APIItem>
</APIParameters>

<APIReturns type="ElementHandle">
  ElementHandle for corresponding DOM node.
</APIReturns>
</API>

### `clickAtPath`

Simulates a click on the node at the specified path.

<API name="clickAtPath">
<APIParameters>
  <APIItem name="page" type="Page">
    Playwright page object.
  </APIItem>
  <APIItem name="editorHandle" type="EditorHandle">
    Handle to editor instance.
  </APIItem>
  <APIItem name="path" type="Path">
    Path to node to click.
  </APIItem>
</APIParameters>
</API>

### `getSelection`

Retrieves the current editor selection.

<API name="getSelection">
<APIParameters>
  <APIItem name="page" type="Page">
    Playwright page object.
  </APIItem>
  <APIItem name="editorHandle" type="EditorHandle">
    Handle to editor instance.
  </APIItem>
</APIParameters>

<APIReturns type="Selection">
  Current editor selection.
</APIReturns>
</API>

### `setSelection`

Sets the editor selection to the specified range.

<API name="setSelection">
<APIParameters>
  <APIItem name="page" type="Page">
    Playwright page object.
  </APIItem>
  <APIItem name="editorHandle" type="EditorHandle">
    Handle to editor instance.
  </APIItem>
  <APIItem name="at" type="Location">
    Location to set selection.
  </APIItem>
</APIParameters>
</API>

### `getTypeAtPath`

Gets the type of the node at the specified path.

<API name="getTypeAtPath">
<APIParameters>
  <APIItem name="page" type="Page">
    Playwright page object.
  </APIItem>
  <APIItem name="editorHandle" type="EditorHandle">
    Handle to editor instance.
  </APIItem>
  <APIItem name="path" type="Path">
    Path to node.
  </APIItem>
</APIParameters>

<APIReturns type="string">
  Type of node at path.
</APIReturns>
</API>


# Plugin Components

Source: https://platejs.org/docs/plugin-components

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Plugin Components
description: Render Plate plugin nodes with React components.
---

Plugin components are the React rendering layer for Plate node plugins. Use
Plate UI components first when the registry already has the node you need, then
customize with `PlateElement`, `PlateLeaf`, `.withComponent`, or the editor
`components` map. This page shows which registration path to use.

## Start with Plate UI

Plate UI components are copied into your app. That makes them the fastest path
for production styling and the safest starting point for customization.

| Start here | Use when |
| --- | --- |
| [Plate UI](/docs/installation/plate-ui) | You want registry components copied into your app. |
| [Feature Kits](/docs/feature-kits) | You want plugin groups that already wire components, shortcuts, and options. |
| This page | You are writing or replacing a component by hand. |

The package owns plugin behavior. Your app owns copied component files and their
styles.

## Component Primitives

Use `PlateElement` for element nodes and `PlateLeaf` for mark or leaf nodes.
Both components merge Slate attributes, Plate node props, `className`, and
`style` onto the rendered DOM element.

<Callout type="info" title="Render children">
  Always render `children`. Slate needs the children in the DOM even when the
  element is void or the visible UI comes from surrounding controls.
</Callout>

### PlateElement

Element components render block, inline, and void element nodes.

```tsx title="components/ui/blockquote-node.tsx" showLineNumbers
'use client';

import { type PlateElementProps, PlateElement } from 'platejs/react';

export function BlockquoteElement({
  children,
  ...props
}: PlateElementProps) {
  return (
    <PlateElement
      as="blockquote"
      className="my-1 border-l-2 pl-6 italic"
      {...props}
    >
      {children}
    </PlateElement>
  );
}
```

`PlateElement` renders a `div` by default. Pass `as` when the node should render
as a specific HTML element.

### PlateLeaf

Leaf components render marks and decorated text ranges.

```tsx title="components/ui/code-node.tsx" showLineNumbers
'use client';

import { type PlateLeafProps, PlateLeaf } from 'platejs/react';

export function CodeLeaf({ children, ...props }: PlateLeafProps) {
  return (
    <PlateLeaf
      as="code"
      className="whitespace-pre-wrap rounded-md bg-muted px-[0.3em] py-[0.2em] font-mono text-sm"
      {...props}
    >
      {children}
    </PlateLeaf>
  );
}
```

`PlateLeaf` renders a `span` by default. Use it for plugins with
`node.isLeaf: true`.

## Register Components

Use the narrowest registration path that fits the job.

### withComponent

Use `.withComponent()` when you only need to attach a React component to a
plugin.

```tsx title="components/editor/plugins.tsx" showLineNumbers
import {
  BlockquotePlugin,
  CodePlugin,
} from '@platejs/basic-nodes/react';

import { BlockquoteElement } from '@/components/ui/blockquote-node';
import { CodeLeaf } from '@/components/ui/code-node';

export const plugins = [
  BlockquotePlugin.withComponent(BlockquoteElement),
  CodePlugin.withComponent(CodeLeaf),
];
```

`.withComponent(Component)` sets both `node.component` and `render.node` for the
plugin.

### node.component

Use `node.component` inside `.configure()` when the same plugin call also owns
rules, shortcuts, options, or parser behavior.

```tsx title="components/editor/plugins.tsx" showLineNumbers
import { CodeRules } from '@platejs/basic-nodes';
import { CodePlugin } from '@platejs/basic-nodes/react';

import { CodeLeaf } from '@/components/ui/code-node';

export const plugins = [
  CodePlugin.configure({
    inputRules: [CodeRules.markdown()],
    node: { component: CodeLeaf },
    shortcuts: { toggle: { keys: 'mod+e' } },
  }),
];
```

During plugin resolution, Plate keeps `node.component` and `render.node` in sync.

### Editor components

Use the editor `components` option when a single editor owns the component map.
This is useful for replacing several components in one place.

```tsx title="components/editor.tsx" showLineNumbers
import {
  BlockquotePlugin,
  CodePlugin,
} from '@platejs/basic-nodes/react';
import { Plate, usePlateEditor } from 'platejs/react';

import { BlockquoteElement } from '@/components/ui/blockquote-node';
import { CodeLeaf } from '@/components/ui/code-node';
import { Editor, EditorContainer } from '@/components/ui/editor';

export function AppEditor() {
  const editor = usePlateEditor({
    components: {
      [BlockquotePlugin.key]: BlockquoteElement,
      [CodePlugin.key]: CodeLeaf,
    },
    plugins: [BlockquotePlugin, CodePlugin],
  });

  return (
    <Plate editor={editor}>
      <EditorContainer>
        <Editor />
      </EditorContainer>
    </Plate>
  );
}
```

The keys are plugin keys, not file names or component names.

## Render Without a Custom Component

Use `render.as` when the default `PlateElement` or `PlateLeaf` wrapper is enough
and you only need a different HTML tag.

```ts title="quote-plugin.ts" showLineNumbers
import { createPlatePlugin } from 'platejs/react';

export const QuotePlugin = createPlatePlugin({
  key: 'quote',
  node: {
    isElement: true,
    type: 'quote',
  },
  render: {
    as: 'blockquote',
  },
});
```

Reach for a custom component once you need classes, nested controls, popovers,
toolbars, resize handles, or plugin options inside the render tree.

## Styling

Prefer component-local styles. Plate also adds a `slate-<node-type>` class while
rendering plugin nodes, so global CSS can target stable node types when you need
editor-wide styling.

```css title="app/globals.css"
.slate-p {
  margin-block: 0.25rem;
}

.slate-code {
  border-radius: 0.375rem;
  font-family: var(--font-mono);
}
```

Use global selectors sparingly. Component files are easier to copy, inspect, and
replace from the registry.

## API Reference

| API | Use for | Notes |
| --- | --- | --- |
| `PlateElement` | Element nodes. | Defaults to `div`; accepts `as`, `className`, `style`, and Plate render props. |
| `PlateLeaf` | Leaf and mark nodes. | Defaults to `span`; use with plugins where `node.isLeaf` is true. |
| `plugin.withComponent(Component)` | Simple component attachment. | Sets `node.component` and `render.node`. |
| `plugin.configure({ node: { component } })` | Component plus plugin config. | Plate syncs `node.component` to `render.node` during resolution. |
| `render.as` | Default wrapper with a different tag. | Works when no custom `render.node` component is set. |
| `components` | Editor-wide component overrides. | Merged into the root plugin's component overrides. |
| `override.components` | Advanced plugin-level component overrides. | Higher-priority plugins win when a target already has a component. |

For plugin method details, see [Plugin Methods](/docs/plugin-methods). For static
rendering components, see [Static Rendering](/docs/static).


# Plugin Context

Source: https://platejs.org/docs/plugin-context

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Plugin Context
description: Use editor, plugin, option, API, and transform context inside Plate plugins.
---

Plugin context is the object Plate passes to plugin configuration callbacks,
handlers, extensions, transforms, and render components. It gives you the
resolved editor, current plugin, node type, `api`, `tf`, and option helpers
without reaching through global state. Use it inside plugin-owned code; use
editor methods or React hooks when code runs outside a plugin callback.

## Context Shape

`PlatePluginContext` extends the shared plugin context with a React
`PlateEditor`. The same helper names are available in headless Slate plugins,
but the editor type is `SlateEditor`.

| Property | Use for |
| --- | --- |
| `editor` | The resolved editor instance. |
| `plugin` | The resolved plugin configuration for the current plugin. |
| `type` | The plugin node type, usually `plugin.node.type`. |
| `api` | Editor API plus plugin-specific API methods. |
| `tf` | Editor transforms plus plugin-specific transforms. |
| `getOption(key, ...args)` | Read an option, selector, or `'state'` from the current plugin. |
| `getOptions()` | Read the full option state for the current plugin. |
| `setOption(key, value)` | Update one option in the current plugin store. |
| `setOptions(optionsOrDraft)` | Update multiple options or mutate a draft. |

## Plugin Methods

Handlers receive context plus the event or payload for that handler. Use the
context helpers instead of closing over editor state.

```ts title="counter-plugin.ts" showLineNumbers
import { createPlatePlugin } from 'platejs/react';

export const CounterPlugin = createPlatePlugin({
  key: 'counter',
  options: {
    count: 0,
    enabled: true,
  },
  handlers: {
    onKeyDown: ({ event, getOption, setOption, type }) => {
      if (!getOption('enabled')) return;

      if (event.key === '+') {
        setOption('count', getOption('count') + 1);
        console.info(`${type} count incremented`);
      }
    },
  },
});
```

`getOption` and `setOption` are scoped to `CounterPlugin` in this example.

## Extension Callbacks

Configuration, extension, selector, API, transform, and editor override callbacks
also receive plugin context.

```ts title="counter-plugin.ts" showLineNumbers
import { createPlatePlugin } from 'platejs/react';

export const CounterPlugin = createPlatePlugin({
  key: 'counter',
  options: {
    count: 0,
  },
})
  .extendSelectors(({ getOptions }) => ({
    label: () => `Count: ${getOptions().count}`,
  }))
  .extendApi(({ getOption }) => ({
    isEmpty: () => getOption('count') === 0,
  }));
```

Selectors are readable through `getOption` and subscribable through
`usePluginOption`.

## Another Plugin

Use `getEditorPlugin(editor, Plugin)` when plugin-owned code needs another
plugin's context. The editor argument is required.

```ts title="link-aware-plugin.ts" showLineNumbers
import { LinkPlugin } from '@platejs/link/react';
import { createPlatePlugin, getEditorPlugin } from 'platejs/react';

export const LinkAwarePlugin = createPlatePlugin({
  key: 'linkAware',
  handlers: {
    onKeyDown: ({ editor, event }) => {
      if (event.key !== 'Enter') return;

      const link = getEditorPlugin(editor, LinkPlugin);

      console.info(`Link node type: ${link.type}`);
    },
  },
});
```

Use this for cross-plugin reads. Keep cross-plugin writes rare; they couple two
plugins tightly.

## React Components

Use `useEditorPlugin` inside a component rendered under `<Plate>`. It returns
the same context plus the editor store.

```tsx title="counter-badge.tsx" showLineNumbers
import { useEditorPlugin, usePluginOption } from 'platejs/react';

import { CounterPlugin } from './counter-plugin';

export function CounterBadge() {
  const { type } = useEditorPlugin(CounterPlugin);
  const count = usePluginOption(CounterPlugin, 'count');
  const label = usePluginOption(CounterPlugin, 'label');

  return (
    <span data-plugin-type={type}>
      {label} ({count})
    </span>
  );
}
```

Use `usePluginOptions` when a component needs a derived value from several
options.

```tsx title="counter-badge.tsx" showLineNumbers
import { usePluginOptions } from 'platejs/react';

import { CounterPlugin } from './counter-plugin';

export function CounterStatus() {
  const status = usePluginOptions(CounterPlugin, (state) =>
    state.count === 0 ? 'empty' : 'active'
  );

  return <span>{status}</span>;
}
```

For code outside the nearest `<Plate>` provider, pass an editor explicitly with
`useEditorPluginOption` or `useEditorPluginOptions`.

## Option State

Plugin options are stored per editor. Updating one editor's plugin options does
not update another editor.

```ts title="counter-plugin.ts" showLineNumbers
export const CounterPluginWithInitialCount = CounterPlugin.configure(
  ({ getOptions }) => ({
    options: {
      count: getOptions().count + 1,
    },
  })
);
```

`setOptions` accepts either a partial object or a draft callback.

```ts title="counter-actions.ts" showLineNumbers
import { getEditorPlugin, type PlateEditor } from 'platejs/react';

import { CounterPlugin } from './counter-plugin';

export function resetCounter(editor: PlateEditor) {
  const { setOptions } = getEditorPlugin(editor, CounterPlugin);

  setOptions({
    count: 1,
  });

  setOptions((draft) => {
    draft.count += 1;
  });
}
```

Plate reports `OPTION_UNDEFINED` through the debug API when `getOption`,
`setOption`, or `usePluginOption` targets a missing option or selector.

## API Reference

| Helper | Scope | Notes |
| --- | --- | --- |
| `getEditorPlugin(editor, plugin)` | Any editor code. | Returns plugin context for the given editor and plugin. |
| `useEditorPlugin(plugin, id?)` | React under `<Plate>`. | Returns plugin context plus `store`. |
| `usePluginOption(plugin, key, ...args)` | React under `<Plate>`. | Subscribes to one option, selector, or `'state'`. |
| `usePluginOptions(plugin, selector, options?)` | React under `<Plate>`. | Subscribes to a selected value from the option state. |
| `useEditorPluginOption(editor, plugin, key, ...args)` | React with explicit editor. | Use outside the closest editor provider. |
| `useEditorPluginOptions(editor, plugin, selector, options?)` | React with explicit editor. | Explicit-editor variant of `usePluginOptions`. |

For plugin extension methods, see [Plugin Methods](/docs/plugin-methods). For
plugin configuration, see [Plugin](/docs/plugin).


# Plugin Input Rules

Source: https://platejs.org/docs/plugin-input-rules

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Plugin Input Rules
description: Typed editor rules for markdown shortcuts, block fences, autolinks, and text substitutions.
---

Plugin Input Rules convert typed editor patterns: markdown prefixes become headings, fences become code blocks, URLs become links, and `->` becomes `→`.
Use [Plugin Rules](/docs/plugin-rules) for node behavior policy such as how `Enter` or `Backspace` works inside a block.
This page covers shipped markdown rules, local substitutions, custom authoring, execution order, and helper reference.

## On This Page

- [What Plugin Input Rules Are](#what-plugin-input-rules-are)
- [Quick Start](#quick-start)
- [Feature-Owned Markdown Rules](#feature-owned-markdown-rules)
- [Local Copied Shortcuts](#local-copied-shortcuts)
- [Custom Rules](#custom-rules)
- [How Rule Execution Works](#how-rule-execution-works)
- [API Reference](#api-reference)

## What Plugin Input Rules Are

When you type a character, press Enter, or paste data, Plate asks every
registered input rule "does this fire?" before running the default transform.
Each rule declares a target (`insertText`, `insertBreak`, or `insertData`), an
optional `enabled` gate, a `resolve` function that looks at the current
selection and returns a match payload, and an `apply` function that performs the
transform. The first rule whose `resolve` returns a non-undefined payload gets
to run; if nothing matches, the default transform runs as usual.

Ownership splits cleanly into three lanes:

- **Core.** Owns dispatch, selection helpers, and the low-level authoring
  surfaces: `createMarkInputRule`, `createBlockStartInputRule`,
  `createBlockFenceInputRule`, `createTextSubstitutionInputRule`,
  `createRuleFactory`, and `defineInputRule`.
- **Feature packages.** Own semantic rule families like `HeadingRules`,
  `BlockquoteRules`, `CodeBlockRules`, `BulletedListRules`, `MathRules`,
  `LinkRules`. Each family exports factory functions that return concrete rule
  instances.
- **Kits and apps.** Own activation. Nothing is turned on just because a plugin exists — you pass rule instances to `inputRules: [...]` when you configure a plugin.

| Lane | Owner | Example |
| ---- | ----- | ------- |
| Feature markdown rule | Package | `HeadingRules.markdown()` |
| Feature interaction rule | Package | `LinkRules.autolink({ variant: 'space' })` |
| Local text substitution | App / local kit | `createTextSubstitutionInputRule({ patterns })` |
| Raw custom rule | App or package | `defineInputRule({ target, trigger, resolve, apply })` |

<Callout>
**Input rules are always explicit.** Registering a plugin does not activate any
rules; you must pass them to `inputRules`. There is no hidden default set and no
string-keyed activation layer.
</Callout>

## Quick Start

Input rules ship as concrete instances you pass into a plugin's `inputRules` array. The two fastest setup paths are:

1. Drop in feature kits that register feature-owned markdown rules — headings, marks, code blocks, lists, math, links.
2. Drop in a local `AutoformatKit` to get common text substitutions like `->` → `→` or `(c)` → `©`.

You can use one, both, or neither.

### Add Feature-Owned Markdown Rules

Use the same kits you already use for nodes and marks. Each kit registers its own markdown rules on the right plugins, so you don't wire anything by hand:

```tsx showLineNumbers
import { createPlateEditor } from 'platejs/react';

import { BasicBlocksKit } from '@/components/editor/plugins/basic-blocks-kit';
import { BasicMarksKit } from '@/components/editor/plugins/basic-marks-kit';
import { CodeBlockKit } from '@/components/editor/plugins/code-block-kit';
import { LinkKit } from '@/components/editor/plugins/link-kit';
import { ListKit } from '@/components/editor/plugins/list-kit';
import { MathKit } from '@/components/editor/plugins/math-kit';

const editor = createPlateEditor({
  plugins: [
    ...BasicBlocksKit,
    ...BasicMarksKit,
    ...CodeBlockKit,
    ...ListKit,
    ...LinkKit,
    ...MathKit,
  ],
});
```

Typing `# ` creates an H1, `**bold**` turns on the bold mark, a triple-backtick
fence creates a code block, `- ` starts a bulleted list, `[label](url)` creates
a link, and so on. Each kit owns its rule wiring — the kit source shows exactly
which rules it registers and on which plugins.

### Add Local Text Substitutions

`AutoformatKit` is copied registry code that lives in your app and uses
`createTextSubstitutionInputRule` under the hood. You own the code and can edit
the patterns.

```tsx showLineNumbers
import { createPlateEditor } from 'platejs/react';

import { AutoformatKit } from '@/components/editor/plugins/autoformat-kit';

const editor = createPlateEditor({
  plugins: [...AutoformatKit],
});
```

Type `->` and get `→`. Type `(c)` and get `©`. The full pattern list is visible in the kit source — change it however you like.

<Callout>
**Feature-owned rules and text substitutions are different lanes.** Markdown
shortcuts live in the feature packages that own the semantics
(`@platejs/basic-nodes`, `@platejs/link`, `@platejs/math`, ...). Text
substitutions are glyph-for-glyph replacements that live in your app.
</Callout>

Kits are the quick path. If you'd rather wire rules by hand — pick which
markdown variants are active, override priorities, or gate a rule per-app — jump
to [Feature-Owned Markdown Rules](#feature-owned-markdown-rules) for the manual
path.

That's the whole surface in under a minute. Type `# `, type `->`, watch them land.

## Feature-Owned Markdown Rules

Feature packages export semantic rule families. Each family exposes one or more
factory functions that return a concrete rule you pass into the matching
plugin's `inputRules`.

### Basic Blocks

Basic block rules ship with `@platejs/basic-nodes`. Register them per plugin.

**Headings.** `HeadingRules.markdown()` is the same factory for H1 through H6.
It derives the markdown prefix from the plugin key (`#`, `##`, `###`, ...), so
you pass it once on each heading plugin.

```tsx showLineNumbers
import { HeadingRules } from '@platejs/basic-nodes';
import {
  H1Plugin,
  H2Plugin,
  H3Plugin,
  H4Plugin,
  H5Plugin,
  H6Plugin,
} from '@platejs/basic-nodes/react';

H1Plugin.configure({
  inputRules: [HeadingRules.markdown()],
}),
H2Plugin.configure({
  inputRules: [HeadingRules.markdown()],
}),
H3Plugin.configure({
  inputRules: [HeadingRules.markdown()],
}),
H4Plugin.configure({
  inputRules: [HeadingRules.markdown()],
}),
H5Plugin.configure({
  inputRules: [HeadingRules.markdown()],
}),
H6Plugin.configure({
  inputRules: [HeadingRules.markdown()],
}),
```

**Blockquote.** `BlockquoteRules.markdown()` fires on `>` followed by space and
wraps the current block. Because blockquote is a wrapper/container node, the
rule nests cleanly inside an existing quote instead of trying to retag the
paragraph in place. The rule is gated with `enabled` so it won't fire inside a
code block.

```tsx showLineNumbers
import { BlockquoteRules } from '@platejs/basic-nodes';
import { BlockquotePlugin } from '@platejs/basic-nodes/react';

BlockquotePlugin.configure({
  inputRules: [BlockquoteRules.markdown()],
}),
```

**Horizontal rule.** `HorizontalRuleRules.markdown()` takes a `variant` so you can register more than one trigger.

```tsx showLineNumbers
import { HorizontalRuleRules } from '@platejs/basic-nodes';
import { HorizontalRulePlugin } from '@platejs/basic-nodes/react';

HorizontalRulePlugin.configure({
  inputRules: [
    HorizontalRuleRules.markdown({ variant: '-' }),
    HorizontalRuleRules.markdown({ variant: '_' }),
  ],
}),
```

`---` and `___` both create a horizontal rule. Register only the variants you want to support.

### Basic Marks

Mark rules live in the same package. Each factory returns a single rule, so register one per trigger you want to support.

**Bold, italic, underline.**

```tsx showLineNumbers
import {
  BoldRules,
  ItalicRules,
  UnderlineRules,
} from '@platejs/basic-nodes';
import {
  BoldPlugin,
  ItalicPlugin,
  UnderlinePlugin,
} from '@platejs/basic-nodes/react';

BoldPlugin.configure({
  inputRules: [
    BoldRules.markdown({ variant: '*' }),
    BoldRules.markdown({ variant: '_' }),
  ],
}),
ItalicPlugin.configure({
  inputRules: [
    ItalicRules.markdown({ variant: '*' }),
    ItalicRules.markdown({ variant: '_' }),
  ],
}),
UnderlinePlugin.configure({
  inputRules: [UnderlineRules.markdown()],
}),
```

Register both `*` and `_` variants to accept `**bold**` and `__bold__`. Underline uses a fixed `__x__` form, so its factory takes no options.

**Combos.** `MarkComboRules.markdown()` is a single factory that covers
multi-delimiter patterns like `***bold italic***`. Register combos alongside the
single-mark rules on the plugin that owns the dominant mark.

```tsx showLineNumbers
import { BoldRules, MarkComboRules } from '@platejs/basic-nodes';
import { BoldPlugin } from '@platejs/basic-nodes/react';

BoldPlugin.configure({
  inputRules: [
    BoldRules.markdown({ variant: '*' }),
    BoldRules.markdown({ variant: '_' }),
    MarkComboRules.markdown({ variant: 'boldItalic' }),
    MarkComboRules.markdown({ variant: 'boldUnderline' }),
    MarkComboRules.markdown({ variant: 'boldItalicUnderline' }),
    MarkComboRules.markdown({ variant: 'italicUnderline' }),
  ],
}),
```

Combo variants: `'boldItalic' | 'boldUnderline' | 'boldItalicUnderline' | 'italicUnderline'`.

**Inline code, strikethrough, subscript, superscript, highlight.**

```tsx showLineNumbers
import {
  CodeRules,
  HighlightRules,
  StrikethroughRules,
  SubscriptRules,
  SuperscriptRules,
} from '@platejs/basic-nodes';
import {
  CodePlugin,
  HighlightPlugin,
  StrikethroughPlugin,
  SubscriptPlugin,
  SuperscriptPlugin,
} from '@platejs/basic-nodes/react';

CodePlugin.configure({
  inputRules: [CodeRules.markdown()],
}),
StrikethroughPlugin.configure({
  inputRules: [StrikethroughRules.markdown()],
}),
SubscriptPlugin.configure({
  inputRules: [SubscriptRules.markdown()],
}),
SuperscriptPlugin.configure({
  inputRules: [SuperscriptRules.markdown()],
}),
HighlightPlugin.configure({
  inputRules: [
    HighlightRules.markdown({ variant: '==' }),
    HighlightRules.markdown({ variant: '≡' }),
  ],
}),
```

Inline code uses `` `x` ``. Strikethrough uses `~~x~~`. Subscript is `~x~`.
Superscript is `^x^`. Highlight accepts `==x==` or `≡x≡` — pick either, both,
or pass a different variant.

### Code Blocks

Code blocks are fenced, which makes them different from simple marks or block prefixes. They ship as a **block fence rule**, and you must pass `on` to pick when the fence commits.

```tsx showLineNumbers
import { CodeBlockRules } from '@platejs/code-block';
import { CodeBlockPlugin } from '@platejs/code-block/react';

CodeBlockPlugin.configure({
  inputRules: [CodeBlockRules.markdown({ on: 'match' })],
}),
```

`on: 'match'` commits the moment the fence text becomes complete — typing the third backtick of the opening fence converts the paragraph to a code block immediately.

```tsx showLineNumbers
CodeBlockPlugin.configure({
  inputRules: [CodeBlockRules.markdown({ on: 'break' })],
}),
```

`on: 'break'` waits for you to press Enter after the fence is complete. Same matcher, different commit point.

<Callout>
**Why `on` is required.** `match` and `break` are meaningfully different UX choices — instant vs deferred. The factory refuses to guess which one you want.
</Callout>

If you need to suppress code blocks inside a specific context, pass `enabled`:

```tsx
CodeBlockRules.markdown({
  on: 'match',
  enabled: ({ editor }) => !isInsideSomeCustomContainer(editor),
}),
```

### Lists

List rules live in `@platejs/list` and register on the single `ListPlugin`. Each factory targets one shape.

```tsx showLineNumbers
import {
  BulletedListRules,
  OrderedListRules,
  TaskListRules,
} from '@platejs/list';
import { ListPlugin } from '@platejs/list/react';

ListPlugin.configure({
  inputRules: [
    BulletedListRules.markdown({ variant: '-' }),
    BulletedListRules.markdown({ variant: '*' }),
    OrderedListRules.markdown({ variant: '.' }),
    OrderedListRules.markdown({ variant: ')' }),
    TaskListRules.markdown({ checked: false }),
    TaskListRules.markdown({ checked: true }),
  ],
}),
```

- `BulletedListRules.markdown({ variant })` accepts `'-'` or `'*'`.
- `OrderedListRules.markdown({ variant })` accepts `'.'` or `')'`. The rule parses the leading number and starts the list from it, so `3. ` creates a list that begins at 3.
- `TaskListRules.markdown({ checked })` maps `[]` to an unchecked task and `[x]` to a checked task.

All list rules use `enabled` to opt out inside code blocks.

### Math

Math has two shapes: inline `$x$` and block `$$x$$`. They're intentionally split so apps can enable one without the other.

```tsx showLineNumbers
import { MathRules } from '@platejs/math';
import { EquationPlugin, InlineEquationPlugin } from '@platejs/math/react';

InlineEquationPlugin.configure({
  inputRules: [MathRules.markdown({ variant: '$' })],
}),
EquationPlugin.configure({
  inputRules: [MathRules.markdown({ variant: '$$', on: 'break' })],
}),
```

`variant: '$'` is inline — a delimited mark rule. `variant: '$$'` is a block
fence, so — like `CodeBlockRules` — it takes `on: 'match' | 'break'`. The
example uses `on: 'break'`, which commits the block equation when you press
Enter after the fence.

### Links

Link rules are not just substitutions — they validate URLs and wrap text with a full link node.

```tsx showLineNumbers
import { LinkRules } from '@platejs/link';
import { LinkPlugin } from '@platejs/link/react';

LinkPlugin.configure({
  inputRules: [
    LinkRules.markdown(),
    LinkRules.autolink({ variant: 'paste' }),
    LinkRules.autolink({ variant: 'space' }),
    LinkRules.autolink({ variant: 'break' }),
  ],
}),
```

- `LinkRules.markdown()` handles `[label](https://...)`.
- `LinkRules.autolink({ variant: 'paste' })` turns a pasted URL into a link.
- `LinkRules.autolink({ variant: 'space' })` detects a URL when you type a trailing space.
- `LinkRules.autolink({ variant: 'break' })` detects a URL when you press Enter.

Register whichever variants you want — you can pick one, two, or all four.

That's the full feature-owned catalog. Every package you add contributes its own rules; the editor picks them up the moment you register them.

## Local Copied Shortcuts

Sometimes you want small text substitutions — smart quotes, arrows, fractions,
trademarks — that don't belong to any feature package. Use
`createTextSubstitutionInputRule` for this.

### createTextSubstitutionInputRule

The helper takes a `patterns` array and builds a single `insertText` rule. Each pattern has a `match` (what you type) and a `format` (what you end up with).

```tsx showLineNumbers
import {
  createSlatePlugin,
  createTextSubstitutionInputRule,
  KEYS,
  type SlateEditor,
} from 'platejs';

const isInCodeBlock = (editor: SlateEditor) =>
  editor.api.some({
    match: { type: [editor.getType(KEYS.codeBlock)] },
  });

const arrowsRule = createTextSubstitutionInputRule({
  enabled: ({ editor }) => !isInCodeBlock(editor),
  patterns: [
    { format: '→', match: '->' },
    { format: '←', match: '<-' },
    { format: '⇒', match: '=>' },
    { format: '⇐', match: ['<=', '≤='] },
  ],
});

export const ArrowsShortcutsPlugin = createSlatePlugin({
  key: 'arrowsShortcuts',
  inputRules: [arrowsRule],
});
```

A few details worth knowing:

- `match` can be a string or an array of strings — all entries are checked before formatting.
- `format` can be a single string or a `[open, close]` tuple. A tuple wraps the typed text as `open + content + close`, useful for smart quotes and brackets.
- `trigger` defaults to the last character of each match, which is almost always what you want. Override it only if you need a distinct commit char.
- `enabled` gates the whole rule, so you don't have to guard each pattern individually.

### Use AutoformatKit As A Starting Point

The `autoformat-kit.tsx` file in Plate's registry wires up a full set of
substitutions — arrows, comparisons, equalities, fractions, legal symbols, smart
quotes, sub/superscript numerals — all gated against code blocks. Copy it into
your app and edit the patterns.

```tsx showLineNumbers title="autoformat-kit.tsx"
import {
  createSlatePlugin,
  createTextSubstitutionInputRule,
  KEYS,
  type SlateEditor,
} from 'platejs';

const isTextSubstitutionBlocked = (editor: SlateEditor) =>
  editor.api.some({
    match: { type: [editor.getType(KEYS.codeBlock)] },
  });

const createAutoformatTextSubstitutionRule = ({
  patterns,
}: {
  patterns: Parameters<typeof createTextSubstitutionInputRule>[0]['patterns'];
}) =>
  createTextSubstitutionInputRule({
    enabled: ({ editor }) => !isTextSubstitutionBlocked(editor),
    patterns,
  });

const legalRule = createAutoformatTextSubstitutionRule({
  patterns: [
    { format: '™', match: ['(tm)', '(TM)'] },
    { format: '®', match: ['(r)', '(R)'] },
    { format: '©', match: ['(c)', '(C)'] },
  ],
});

const smartQuotesRule = createAutoformatTextSubstitutionRule({
  patterns: [
    { format: ['“', '”'], match: '"' },
    { format: ['‘', '’'], match: "'" },
  ],
});

const AutoformatShortcutsPlugin = createSlatePlugin({
  key: 'autoformatShortcuts',
  inputRules: [legalRule, smartQuotesRule],
});

export const AutoformatKit = [AutoformatShortcutsPlugin];
```

<Callout>
**Use copied code for local substitutions.** `@platejs/autoformat` still ships
as a compatibility package for autoformat imports. Author project-specific
substitutions in copied registry code or your own local kit so the rules stay
visible and editable.
</Callout>

### When To Reach For defineInputRule

Text substitution covers the glyph-for-glyph case. When you need more — reading
the current block, dispatching a richer transform, or detecting a pattern that
isn't a simple character match — drop down to `defineInputRule` or one of the
low-level builders.

## Custom Rules

Everything above is sugar on top of three low-level authoring surfaces:

- `defineInputRule`, an identity function that types a raw rule inline.
- The specialized builders: `createMarkInputRule`, `createBlockStartInputRule`,
  `createBlockFenceInputRule`, `createTextSubstitutionInputRule`.
- `createRuleFactory`, the package-authoring helper used to expose semantic
  families like `MathRules.markdown(...)` or `LinkRules.autolink(...)` without
  re-declaring shared runtime fields.

Use this section when none of the shipped families fit your need or when you're authoring your own reusable rule family.

### Register Explicit Rule Instances

Rules are concrete objects. You pass them into `inputRules` exactly as-is. To
override a field like `priority` or `enabled` on a finished instance, spread the
rule and replace the field:

```tsx showLineNumbers
import { HeadingRules } from '@platejs/basic-nodes';
import { LinkRules } from '@platejs/link';
import { H1Plugin } from '@platejs/basic-nodes/react';
import { LinkPlugin } from '@platejs/link/react';

H1Plugin.configure({
  inputRules: [HeadingRules.markdown()],
}),
LinkPlugin.configure({
  inputRules: [
    LinkRules.markdown(),
    { ...LinkRules.autolink({ variant: 'paste' }), priority: 200 },
  ],
}),
```

Why the spread? Package factories are intentionally narrow — most don't take a
`priority` option. Overriding is the caller's job, and spreading the returned
rule keeps it obvious that you're changing one field on an already-built
instance.

The same pattern works for `enabled`. If a family ships with a sensible default but you need stricter gating in one app, spread the rule and override:

```tsx
{
  ...BlockquoteRules.markdown(),
  enabled: ({ editor }) => !isInsideCallout(editor),
},
```

### Plugin-Side Factories

For plugin authors, the `inputRules` option also accepts a function that
receives a `rule` builder. Use this form when your rules depend on plugin-local
state or when you want your rule wiring to live next to the plugin's types.

```tsx showLineNumbers
import { createSlatePlugin, KEYS } from 'platejs';

const CustomPlugin = createSlatePlugin({
  key: 'custom',
  inputRules: ({ rule }) => [
    rule.mark({
      trigger: '*',
      start: '*',
    }),
    rule.blockStart({
      trigger: ' ',
      match: '>',
      mode: 'wrap',
      node: 'blockquote',
    }),
    rule.blockFence({
      fence: '```',
      on: 'match',
      apply: (context, match) => {
        context.editor.tf.delete({ at: match.range });
        context.editor.tf.setNodes(
          { type: context.editor.getType(KEYS.codeBlock) },
          { at: match.path }
        );
      },
    }),
  ],
});
```

The `rule` builder exposes six primitives:

| Method | Wraps |
| ------ | ----- |
| `rule.mark(config)` | `createMarkInputRule` |
| `rule.blockStart(config)` | `createBlockStartInputRule` |
| `rule.blockFence(config)` | `createBlockFenceInputRule` |
| `rule.insertText(rule)` | typed `defineInputRule` for `insertText` |
| `rule.insertBreak(rule)` | typed `defineInputRule` for `insertBreak` |
| `rule.insertData(rule)` | typed `defineInputRule` for `insertData` |

Use the factory form when you need that co-location; use the array form when you just want to register a handful of concrete instances.

### Author A Rule Family

When you're shipping a package, you usually want a public factory like
`MyNodeRules.markdown(...)` that takes a narrow options object and hides the
low-level rule plumbing. Reach for `createRuleFactory`.

```tsx showLineNumbers
import { createRuleFactory, KEYS } from 'platejs';

export const BlockquoteRules = {
  markdown: createRuleFactory<{}, { marker: string }>({
    type: 'blockStart',
    marker: '>',
    trigger: ' ',
    mode: 'wrap',
    match: ({ marker }) => marker,
    enabled: ({ editor }) =>
      !editor.api.some({ match: { type: [editor.getType(KEYS.codeBlock)] } }),
  }),
};
```

A few things to notice:

- `type` picks the underlying builder. Use `'mark'`, `'blockStart'`, `'blockFence'`, or `'textSubstitution'`.
- The two generic parameters model your public API: `TRequired` (the first) are
  options callers must pass; `TDefaults` (the second) are options you supply a
  default for — here, `marker: '>'`.
- Factory values can be plain values (`'>'`) or functions of the input
  (`({ marker }) => marker`). The input includes the runtime context, your
  defaults, and any required options the caller passes.
- For `blockStart`, core already owns the base match payload: `{ range, text }`.
  If you provide `resolveMatch`, return only your extra fields — core merges
  them onto the base payload before `apply` runs.
- `enabled` and `priority` stay available as runtime overrides on the returned rule instance — callers can override them even when your factory sets a default.

That's the pattern every `*Rules.markdown(...)` family in Plate uses. Clone it when you need your own.

Done. Between `defineInputRule`, the four specialized builders, the plugin-side
`rule` builder, and `createRuleFactory`, every rule in Plate — yours included —
comes from the same small core.

## How Rule Execution Works

Input rules run inside the `insertText`, `insertBreak`, and `insertData`
transforms. For each call, the runtime walks every registered rule for that
target in priority order, and the first rule that passes `enabled` and produces
a non-undefined `resolve` gets to call `apply`.

### Targets

A rule's `target` field picks which lane it runs in.

| Target | Fires on |
| ------ | -------- |
| `insertText` | Each character typed into the editor |
| `insertBreak` | Each time the user presses `Enter` |
| `insertData` | Each time data is pasted or dropped |

The high-level factories set `target` for you:

- `createMarkInputRule` and `createBlockStartInputRule` always produce `insertText` rules.
- `createBlockFenceInputRule` produces an `insertText` rule when `on: 'match'` and an `insertBreak` rule when `on: 'break'`.
- `createTextSubstitutionInputRule` always produces an `insertText` rule.

`defineInputRule` lets you pick any target by setting the `target` field directly.

### Selection Context

Every `enabled`, `resolve`, and `apply` call receives a context object with the live editor, the selection state, and a handful of lazy helpers.

| Field | Returns |
| ----- | ------- |
| `editor` | The current `SlateEditor` |
| `isCollapsed` | Whether the selection is collapsed |
| `pluginKey` | The key of the plugin the rule is attached to |
| `getBlockEntry()` | The current block's `NodeEntry`, or `undefined` |
| `getBlockStartRange()` | The range from block start to current selection |
| `getBlockStartText()` | The text from block start to current selection |
| `getBlockTextBeforeSelection()` | The text in the current block before the cursor |
| `getCharBefore()` | The character immediately before the cursor |
| `getCharAfter()` | The character immediately after the cursor |

The `get*` helpers are memoized — calling them twice inside the same rule evaluation doesn't recompute. That matters because multiple rules can share the same evaluation pass.

Target-specific context fields:

- `insertText` rules additionally receive `text`, `cause: 'insertText'`, and an `insertText` callback for default fallthrough.
- `insertBreak` rules receive `cause: 'insertBreak'` and an `insertBreak` callback.
- `insertData` rules receive `data: DataTransfer`, `text`, `cause: 'insertData'`, and an `insertData` callback.

### Lifecycle

For each transform call, the runtime walks rules in priority order (highest first). For each rule, it runs the following steps:

1. **`enabled`.** A boolean gate. If it returns `false`, skip to the next rule.
2. **`resolve`.** Computes a match payload. If it returns `undefined`, skip to the next rule.
3. **`apply`.** Performs the transform. If it returns `false`, the runtime
   treats the rule as not consumed and continues; any other return value
   consumes the input and short-circuits the rest of the walk.

If no rule consumes the input, the default Slate transform runs as normal.

| Field | Purpose |
| ----- | ------- |
| `trigger` | Restricts an `insertText` rule to fire only when the typed character matches (string or array) |
| `enabled` | Policy gate, evaluated first |
| `resolve` | Computes the match payload passed to `apply` |
| `apply` | Performs the transform |
| `priority` | Sort order for rules on the same target |
| `on` | Block-fence commit mode: `'match'` or `'break'` |
| `mimeTypes` | Narrows an `insertData` rule to specific MIME types |

<Callout>
**Use `enabled` for policy, not `match`.** The matcher should own the *syntax*
of a rule (what pattern counts as a hit). Gating — "don't fire in code blocks",
"only fire when this plugin is active" — belongs in `enabled`. Returning
`undefined` from `resolve` just to suppress a rule works, but it hides intent
and makes rules harder to compose.
</Callout>

## API Reference

Low-level surface. Reach for this when the high-level factories don't cover your case. Everything below is exported from `platejs`.

### Rule Targets

```ts
type InputRuleTarget = 'insertText' | 'insertBreak' | 'insertData';
```

### defineInputRule

Identity function that types a rule inline.

```ts
function defineInputRule<TRule extends AnyInputRule>(rule: TRule): TRule;
```

```ts
import { defineInputRule } from 'platejs';

const copyrightRule = defineInputRule({
  target: 'insertText',
  trigger: ')',
  resolve: (context) => {
    if (context.text !== ')') return;
    if (!context.getBlockTextBeforeSelection().endsWith('(c')) return;

    return { replacement: '©' };
  },
  apply: ({ editor }, match) => {
    editor.tf.delete({ distance: 2, reverse: true, unit: 'character' });
    editor.tf.insertText(match.replacement);
  },
});
```

Use it when you want a raw rule object typed against `InsertTextInputRule`, `InsertBreakInputRule`, or `InsertDataInputRule` without going through a builder.

### createRuleFactory

Package-facing helper for semantic rule families. Use it when you want to expose
a narrow public factory like `BlockquoteRules.markdown(...)`, keep shared
runtime fields like `enabled` and `priority`, and hide the low-level rule
construction details.

```ts
import { createRuleFactory, KEYS } from 'platejs';

export const BlockquoteRules = {
  markdown: createRuleFactory<{}, { marker: string }>({
    type: 'blockStart',
    marker: '>',
    trigger: ' ',
    match: ({ marker }) => marker,
    mode: 'wrap',
    enabled: ({ editor }) =>
      !editor.api.some({
        match: { type: [editor.getType(KEYS.codeBlock)] },
      }),
  }),
};
```

The returned function is your public rule family. Concrete values in the config
become default public options (`marker: '>'`), while the generic type parameters
let you model required options and defaults for the family. The created rule
instance still supports the shared runtime overrides: `enabled` and `priority`.

### createMarkInputRule

Delimited inline marks (`**bold**`, `` `code` ``, `~~strike~~`).

```ts
function createMarkInputRule(config: {
  start: string;
  end?: string;
  trigger: string;
  mark?: string;
  marks?: string[];
  trim?: 'allow' | 'reject';
  enabled?: (context: InsertTextInputRuleContext) => boolean;
  priority?: number;
}): InsertTextInputRule;
```

```ts
import { createMarkInputRule } from 'platejs';

createMarkInputRule({
  start: '**',
  end: '*',
  trigger: '*',
});
```

`start` is the opening delimiter. `end` is an optional closing delimiter; when
omitted, the rule does not look for a separate closing delimiter before the
trigger. `trigger` is the character that commits the match. `trim: 'reject'`
refuses spans with leading or trailing whitespace. `mark` and `marks` restrict
which mark(s) the rule applies.

### createBlockStartInputRule

Block-start patterns typed at the beginning of a block (`# `, `> `, `- `, `1. `).

```ts
function createBlockStartInputRule<TMatch extends object = {}>(config: {
  trigger: string;
  match:
    | RegExp
    | string
    | ((context: InsertTextInputRuleContext) => RegExp | string | undefined);
  mode?: 'set' | 'toggle' | 'wrap';
  node?: string;
  removeMatchedText?: boolean;
  resolveMatch?: (args: {
    match: RegExpMatchArray | string;
    range: TRange;
    text: string;
  }) => TMatch | undefined;
  apply?: (
    context: InsertTextInputRuleContext,
    match: BlockStartInputRuleMatch & TMatch
  ) => boolean | void;
  enabled?: (context: InsertTextInputRuleContext) => boolean;
  priority?: number;
}): InsertTextInputRule<TMatch>;
```

```ts
import { createBlockStartInputRule } from 'platejs';

createBlockStartInputRule({
  trigger: ' ',
  match: '>',
  mode: 'wrap',
});
```

- `trigger` is the commit character — typically `' '`.
- `match` is the block-start text: a string, a `RegExp`, or a function that returns one based on context.
- `mode` picks the transform: `'set'` replaces the block type, `'toggle'` flips it, `'wrap'` wraps the block in a new element.
- `node` is the target element type used by `mode`.
- `apply` overrides the built-in transform entirely — supply your own when none
  of the modes fit. That also means you own matched-text cleanup; if you still
  want the shorthand removed, delete `match.range` yourself.
- `resolveMatch` returns extra fields only. Core still provides the base `{ range, text }` payload automatically, and `apply` receives the merged object.

### createBlockFenceInputRule

Fenced block patterns like triple-backtick code fences or `$$` math fences.

```ts
function createBlockFenceInputRule<TMatch>(config: {
  fence: string;
  on: 'break' | 'match';
  apply: (context: SelectionInputRuleContext, match: TMatch) => boolean | void;
  block?: string;
  resolveMatch?: (args: {
    fence: string;
    path: Path;
    range: TRange;
    text: string;
  }) => TMatch | undefined;
  enabled?: (context: SelectionInputRuleContext) => boolean;
  priority?: number;
}): InsertTextInputRule<TMatch> | InsertBreakInputRule<TMatch>;
```

```ts
import { createBlockFenceInputRule, KEYS } from 'platejs';

createBlockFenceInputRule({
  fence: '```',
  on: 'match',
  apply: (context, match) => {
    context.editor.tf.delete({ at: match.range });
    context.editor.tf.setNodes(
      { type: context.editor.getType(KEYS.codeBlock) },
      { at: match.path }
    );
  },
});
```

`on: 'match'` commits when the fence becomes complete inside the current
paragraph. `on: 'break'` commits when Enter is pressed after the fence is
complete — useful when the user may want to type more before committing.

The runtime owns the matcher: it checks that the selection is collapsed, the
cursor is at the block's end, and the block text equals `fence`. If you pass
`block`, the matcher also requires that block type. You own `apply`, which
performs the replacement. The returned rule targets `insertText` when
`on: 'match'` and `insertBreak` when `on: 'break'`.

### createTextSubstitutionInputRule

Glyph-for-glyph substitutions.

```ts
function createTextSubstitutionInputRule(config: {
  patterns: Array<{
    format: readonly [string, string] | string;
    match: readonly string[] | string;
    trigger?: readonly string[] | string;
  }>;
  enabled?: (context: InsertTextInputRuleContext) => boolean;
  priority?: number;
}): InsertTextInputRule;
```

```ts
import { createTextSubstitutionInputRule } from 'platejs';

createTextSubstitutionInputRule({
  patterns: [
    { format: '→', match: '->' },
    { format: ['«', '»'], match: '<<' },
  ],
});
```

`format` is either a replacement string or a `[open, close]` tuple that wraps
the typed content. `match` is a string or array of strings that trigger the
replacement. `trigger` defaults to the last character of each match and rarely
needs overriding.

### matchDelimitedInline

Low-level matcher used under `createMarkInputRule`. Returns a `{ content, deleteRange }` match for a delimited inline pattern, or `undefined`.

```ts
import { matchDelimitedInline } from 'platejs';

const match = matchDelimitedInline(context, {
  open: '**',
  close: '*',
  requireClosingDelimiter: true,
  trim: 'reject',
});
```

Use it when you're authoring a custom `insertText` rule that needs the same matching shape as a mark without going through `createMarkInputRule`.

### matchBlockStart / matchBlockFence

Companion matchers for block-start and block-fence rules. Both take the current
context plus a matcher config and return a match payload or `undefined`. Use
them when you want the matcher logic without the factory's `apply` wiring.

```ts
import { matchBlockFence, matchBlockStart } from 'platejs';

const startMatch = matchBlockStart(context, { match: '>' });
const fenceMatch = matchBlockFence(context, { fence: '```' });
```

### Package Rule Families

Every family below is a single export from its package. Each `.markdown()` (or `.autolink()`) call returns a concrete rule you pass into the matching plugin's `inputRules`.

| Family | Package | Description |
| ------ | ------- | ----------- |
| `HeadingRules` | `@platejs/basic-nodes` | Markdown prefix rules for H1–H6, derived from plugin key |
| `BlockquoteRules` | `@platejs/basic-nodes` | `>` block-wrap rule, gated out of code blocks |
| `HorizontalRuleRules` | `@platejs/basic-nodes` | `---` and `___` variant rules |
| `BoldRules` | `@platejs/basic-nodes` | `**x**` / `__x__` mark rule |
| `ItalicRules` | `@platejs/basic-nodes` | `*x*` / `_x_` mark rule |
| `UnderlineRules` | `@platejs/basic-nodes` | `__x__` mark rule |
| `CodeRules` | `@platejs/basic-nodes` | `` `x` `` inline code mark rule |
| `StrikethroughRules` | `@platejs/basic-nodes` | `~~x~~` mark rule |
| `SubscriptRules` | `@platejs/basic-nodes` | `~x~` mark rule |
| `SuperscriptRules` | `@platejs/basic-nodes` | `^x^` mark rule |
| `HighlightRules` | `@platejs/basic-nodes` | `==x==` / `≡x≡` mark rule |
| `MarkComboRules` | `@platejs/basic-nodes` | Multi-mark combo rules (bold/italic/underline) |
| `CodeBlockRules` | `@platejs/code-block` | Triple-backtick block fence rule, requires `on` |
| `BulletedListRules` | `@platejs/list` | `-` / `*` bulleted list rule |
| `OrderedListRules` | `@platejs/list` | `1.` / `1)` ordered list rule, preserves start number |
| `TaskListRules` | `@platejs/list` | `[]` / `[x]` task list rule |
| `MathRules` | `@platejs/math` | Inline `$x$` and block `$$x$$` rules |
| `LinkRules` | `@platejs/link` | Markdown `[label](url)` and autolink rules |

Each family's factory takes a narrow options object — see the per-section examples above for the exact shape.


# Plugin Methods

Source: https://platejs.org/docs/plugin-methods

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Plugin Methods
description: Configure, extend, and override Plate plugins.
---

Plugin methods return new plugin instances, so you can keep a base plugin stable and derive app-specific behavior from it. Use `.configure()` for existing fields, `.extend*()` for typed additions, and `.overrideEditor()` only when wrapping editor APIs or transforms that already exist. This guide maps each method to the runtime surface it changes.

## On This Page

- [Method Map](#method-map)
- [Configure Existing Fields](#configure-existing-fields)
- [Configure Nested Plugins](#configure-nested-plugins)
- [Extend The Plugin](#extend-the-plugin)
- [Selectors](#selectors)
- [API And Transforms](#api-and-transforms)
- [Override Editor Methods](#override-editor-methods)
- [Components](#components)
- [Convert Slate Plugins](#convert-slate-plugins)
- [API Reference](#api-reference)

## Method Map

| Method | Use it for | Writes to |
| --- | --- | --- |
| `.configure()` | Change existing plugin fields without widening the public type. | The current plugin. |
| `.configurePlugin()` | Change an existing nested plugin. | A child plugin already present in `plugins`. |
| `.extend()` | Add typed options, handlers, renderers, rules, or runtime hooks. | The current plugin. |
| `.extendPlugin()` | Extend a nested plugin, or add a keyed nested plugin when missing. | A child plugin under `plugins`. |
| `.extendSelectors()` | Add computed option selectors. | `getOption()` and `usePluginOption()`. |
| `.extendApi()` | Add plugin-specific API methods. | `editor.api[plugin.key]`. |
| `.extendEditorApi()` | Add editor-wide API methods. | `editor.api`. |
| `.extendTransforms()` | Add plugin-specific transforms. | `editor.tf[plugin.key]`. |
| `.extendEditorTransforms()` | Add editor-wide transforms. | `editor.tf`. |
| `.overrideEditor()` | Wrap existing editor API or transform methods. | `editor.api` and `editor.tf`. |
| `.withComponent()` | Attach a node component to a plugin. | `plugin.node.component` and `plugin.render.node`. |
| `.clone()` | Copy a plugin definition. | A new plugin object. |

Plugin method callbacks receive the same context described in [Plugin Context](/docs/plugin-context): `editor`, `plugin`, `api`, `tf`, `getOption`, `getOptions`, `setOption`, `setOptions`, and `type`.

## Configure Existing Fields

Use `.configure()` when the plugin already has the field and you only need to change its value.

```tsx title="plugins.tsx" showLineNumbers
import { H1Plugin } from '@platejs/basic-nodes/react';

export const AppH1Plugin = H1Plugin.configure({
  shortcuts: {
    toggle: { keys: 'mod+alt+1' },
  },
});
```

Function configs run when the plugin resolves inside an editor, so they can read the current plugin options.

```tsx title="plugins.tsx" showLineNumbers
import { NavigationFeedbackPlugin } from 'platejs/react';

const LongerFlashPlugin = NavigationFeedbackPlugin.configure(
  ({ getOption }) => ({
    options: {
      duration: getOption('duration') + 400,
    },
  })
);
```

Object configs are merged with the plugin through Plate's plugin merge rules: objects merge deeply, arrays are replaced, and `options` are shallow merged.

<Callout type="info" title="Configure does not widen types">
  `.configure()` is for existing plugin fields. If you need TypeScript to know
  about a new option, API method, transform, selector, handler, or renderer,
  use `.extend()` or the narrower `.extend*()` method.
</Callout>

## Configure Nested Plugins

Use `.configurePlugin()` when a parent plugin owns a child plugin and you want to adjust that child without replacing the whole parent.

```tsx title="plugins.tsx" showLineNumbers
import { createPlatePlugin } from 'platejs/react';

const CellPlugin = createPlatePlugin({
  key: 'cell',
  options: {
    padding: 12,
  },
});

export const GridPlugin = createPlatePlugin({
  key: 'grid',
  plugins: [CellPlugin],
}).configurePlugin(CellPlugin, {
  options: {
    padding: 8,
  },
});
```

`.configurePlugin()` searches nested `plugins` recursively. If the target plugin is not found, Plate leaves the parent unchanged.

Use `.extendPlugin()` when the child needs new typed behavior.

```tsx title="plugins.tsx" showLineNumbers
export const GridWithCellShortcutPlugin = GridPlugin.extendPlugin(CellPlugin, {
  shortcuts: {
    insertBelow: {
      keys: 'mod+enter',
      handler: ({ event }) => {
        event.preventDefault();

        return true;
      },
    },
  },
});
```

<Callout type="note" title="Missing nested plugins">
  `.configurePlugin()` does not add a missing child. `.extendPlugin()` does:
  when the target key is not found, Plate adds a keyed plugin at the top level
  of the parent's `plugins` array and applies the extension there.
</Callout>

## Extend The Plugin

Use `.extend()` for broad plugin additions. Object extensions merge immediately; function extensions run during plugin resolution with the current editor context.

```tsx title="plugins.tsx" showLineNumbers
import { createPlatePlugin } from 'platejs/react';

export const MentionPlugin = createPlatePlugin({
  key: 'mention',
  node: {
    isElement: true,
    isInline: true,
  },
}).extend(({ editor }) => ({
  handlers: {
    onKeyDown: ({ event }) => {
      if (event.key === 'Escape') {
        editor.tf.deselect();
        event.preventDefault();
      }
    },
  },
  options: {
    trigger: '@',
  },
}));
```

Use `.extend()` when one extension naturally touches several plugin fields. Use the narrower methods below when the addition is specifically an API method, transform, selector, or editor override.

## Selectors

Use `.extendSelectors()` for derived option values that components can subscribe to. Selectors are available through `getOption()` and React hooks such as `usePluginOption()`.

```tsx title="counter-plugin.tsx" showLineNumbers
import { type PluginConfig } from 'platejs';
import { createTPlatePlugin, usePluginOption } from 'platejs/react';

type CounterOptions = {
  value: number;
};

type CounterSelectors = {
  doubled: (factor: number) => number;
  isEven: () => boolean;
};

type CounterConfig = PluginConfig<
  'counter',
  CounterOptions,
  {},
  {},
  CounterSelectors
>;

export const CounterPlugin = createTPlatePlugin<CounterConfig>({
  key: 'counter',
  options: {
    value: 1,
  },
}).extendSelectors<CounterSelectors>(({ getOptions }) => ({
  doubled: (factor) => getOptions().value * factor,
  isEven: () => getOptions().value % 2 === 0,
}));

export function CounterValue() {
  const doubled = usePluginOption(CounterPlugin, 'doubled', 2);
  const isEven = usePluginOption(CounterPlugin, 'isEven');
  const value = usePluginOption(CounterPlugin, 'value');

  return (
    <span>
      {value} / {doubled} / {isEven ? 'even' : 'odd'}
    </span>
  );
}
```

Selectors are the right place for derived state. Use `.extendApi()` when the method is a query or utility that should not subscribe React components to option changes.

## API And Transforms

Use API methods for reads and utilities. Use transforms for operations that mutate editor state.

| Method | Access path | Typical use |
| --- | --- | --- |
| `.extendApi()` | `editor.api.counter.isEmpty()` | Plugin-specific query or utility. |
| `.extendEditorApi()` | `editor.api.counterLabel()` | Editor-wide query or utility. |
| `.extendTransforms()` | `editor.tf.counter.increment()` | Plugin-specific mutation. |
| `.extendEditorTransforms()` | `editor.tf.resetCounter()` | Editor-wide mutation. |

```tsx title="counter-plugin.tsx" showLineNumbers
import { type PluginConfig } from 'platejs';
import { createTPlatePlugin } from 'platejs/react';

type CounterOptions = {
  value: number;
};

type CounterPluginApi = {
  isEmpty: () => boolean;
};

type CounterEditorApi = {
  counterLabel: () => string;
};

type CounterPluginTransforms = {
  increment: () => void;
};

type CounterEditorTransforms = {
  resetCounter: () => void;
};

type CounterConfig = PluginConfig<'counter', CounterOptions>;

export const CounterPlugin = createTPlatePlugin<CounterConfig>({
  key: 'counter',
  options: {
    value: 0,
  },
})
  .extendApi<CounterPluginApi>(({ getOption }) => ({
    isEmpty: () => getOption('value') === 0,
  }))
  .extendEditorApi<CounterEditorApi>(({ getOption }) => ({
    counterLabel: () => `Count: ${getOption('value')}`,
  }))
  .extendTransforms<CounterPluginTransforms>(({ getOption, setOption }) => ({
    increment: () => setOption('value', getOption('value') + 1),
  }))
  .extendEditorTransforms<CounterEditorTransforms>(({ setOption }) => ({
    resetCounter: () => setOption('value', 0),
  }));
```

After the plugin resolves in an editor, call those methods from their resolved surfaces.

```ts
editor.api.counter.isEmpty();
editor.api.counterLabel();
editor.tf.counter.increment();
editor.tf.resetCounter();
```

`editor.tf` is the short alias for `editor.transforms`; both access the same transform tree.

## Override Editor Methods

Use `.overrideEditor()` when you need to wrap existing editor API or transform methods and keep access to the original method.

```tsx title="plugins.tsx" showLineNumbers
import { createPlatePlugin } from 'platejs/react';

export const LimitExclamationPlugin = createPlatePlugin({
  key: 'limitExclamation',
}).overrideEditor(({ tf: { insertText } }) => ({
  transforms: {
    insertText(text, options) {
      insertText(text === '!' ? '.' : text, options);
    },
  },
}));
```

The callback can override API methods, transform methods, or both.

```tsx title="plugins.tsx" showLineNumbers
const TrimStringPlugin = createPlatePlugin({
  key: 'trimString',
}).overrideEditor(({ api: { string } }) => ({
  api: {
    string(at, options) {
      return string(at, options).trim();
    },
  },
}));
```

Keep new editor methods in `.extendEditorApi()` or `.extendEditorTransforms()`. `.overrideEditor()` is for changing behavior while preserving the original call path.

## Components

Use `.withComponent()` to bind a Plate UI node component to a plugin. It writes both `node.component` and `render.node`, which keeps the component available to the editor renderer and plugin metadata.

```tsx title="plugins.tsx" showLineNumbers
import { ParagraphPlugin } from 'platejs/react';

import { ParagraphElement } from '@/components/ui/paragraph-node';

export const AppParagraphPlugin =
  ParagraphPlugin.withComponent(ParagraphElement);
```

Use `.withComponent()` for the common one-component case. Use `.extend()` when the same plugin also needs render wrappers, handlers, options, or rules.

## Convert Slate Plugins

Use `toPlatePlugin()` when you have a headless Slate plugin and need to add React-only fields such as `render`, `handlers`, or `useHooks`.

```tsx title="mention-plugin.tsx" showLineNumbers
import { createTSlatePlugin } from 'platejs';
import { toPlatePlugin } from 'platejs/react';

import { MentionElement } from '@/components/ui/mention-node';

const BaseMentionPlugin = createTSlatePlugin({
  key: 'mention',
  node: {
    isElement: true,
    isInline: true,
  },
});

export const MentionPlugin = toPlatePlugin(BaseMentionPlugin, {
  render: {
    node: MentionElement,
  },
});
```

`toPlatePlugin()` wraps the same plugin methods, so a converted plugin can still use `.configure()`, `.extend()`, `.extendApi()`, `.overrideEditor()`, and `.withComponent()`.

## API Reference

| Method | Accepts | Resolution behavior |
| --- | --- | --- |
| `.configure(config)` | Object or callback returning a partial plugin config. | Stores one configuration callback and applies it before function extensions. |
| `.configurePlugin(plugin, config)` | Target plugin and object or callback config. | Recursively configures an existing nested plugin; missing target is ignored. |
| `.extend(config)` | Object or callback returning a partial plugin config. | Object configs merge immediately; callback configs run during plugin resolution. |
| `.extendPlugin(plugin, config)` | Target plugin and object or callback extension. | Recursively extends a nested plugin; missing target is added by key. |
| `.extendSelectors(callback)` | Callback returning selector functions. | Extends the plugin option store selectors. |
| `.extendApi(callback)` | Callback returning functions. | Merges into `editor.api[plugin.key]` and `plugin.api[plugin.key]`. |
| `.extendEditorApi(callback)` | Callback returning functions or one-level nested function objects. | Merges into `editor.api` and `plugin.api`. |
| `.extendTransforms(callback)` | Callback returning functions. | Merges into `editor.tf[plugin.key]` and `plugin.transforms[plugin.key]`. |
| `.extendEditorTransforms(callback)` | Callback returning functions or one-level nested function objects. | Merges into `editor.tf` and `plugin.transforms`. |
| `.overrideEditor(callback)` | Callback returning `{ api?, transforms? }`. | Deep-merges overrides into editor and plugin API/transform objects. |
| `.withComponent(component)` | A node component. | Sets `node.component` and `render.node`. |
| `.clone()` | No arguments. | Returns a merged copy of the plugin definition. |

Done. Use configuration for existing fields, extension methods for new typed surface, and overrides only when the editor method already exists.


# Plugin Rules

Source: https://platejs.org/docs/plugin-rules

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Plugin Rules
description: Configure common editing behaviors.
---

Plugin Rules control how editor nodes respond to common user actions. Instead of overriding the editor methods, you can configure these behaviors directly on a plugin's `rules` property.

This guide shows you how to use `rules.break`, `rules.delete`, `rules.merge`, `rules.normalize`, `rules.selection`
 and `rules.match` to create intuitive editing experiences.

[plugin-rules-demo registry content](https://platejs.org/r/plugin-rules-demo)

## Actions

Plugin rules use specific action names to define behavior:

- **`'default'`**: Default Slate behavior.
- **`'reset'`**: Changes the current block to a default paragraph, keeping content.
- **`'exit'`**: Exits the current block, inserting a new paragraph after it. See [Exit Break](/docs/exit-break) to learn more about this behavior.
- **`'lift'`**: Lifts the current block out of the nearest matching ancestor container, changing one structural level at a time.
- **`'deleteExit'`**: Deletes content then exits the block.
- **`'lineBreak'`**: Inserts a line break (`\n`) instead of splitting the block.

### `default`

Standard Slate behavior. For `rules.break`, splits the block. For `rules.delete`, merges with the previous block.

```tsx
<p>
  Hello world|
</p>
```

After pressing `Enter`:

```tsx
<p>Hello world</p>
<p>
  |
</p>
```

After pressing `Backspace`:

```tsx
<p>Hello world|</p>
```

### `reset`

Converts the current block to a default paragraph while preserving content. Custom properties are removed.

```tsx
<h3 listStyleType="disc">
  |
</h3>
```

After pressing `Enter` with `rules: { break: { empty: 'reset' } }`:

```tsx
<p>
  |
</p>
```

### `exit`

Exits the current block structure by inserting a new paragraph after it.

```tsx
<blockquote>
  |
</blockquote>
```

After pressing `Enter` with `rules: { break: { empty: 'exit' } }`:

```tsx
<blockquote>
  <text />
</blockquote>
<p>
  |
</p>
```

### `lift`

Lifts the current block out of the nearest matching ancestor container.

```tsx
<blockquote>
  <p>
    |
  </p>
</blockquote>
```

After pressing `Enter` with `rules: { break: { empty: 'lift' } }`:

```tsx
<p>
  |
</p>
```

### `deleteExit`

Deletes content then exits the block.

```tsx
<blockquote>
  line1
  |
</blockquote>
```

After pressing `Enter` with `rules: { break: { emptyLineEnd: 'deleteExit' } }`:

```tsx
<blockquote>line1</blockquote>
<p>
  |
</p>
```

### `lineBreak`

Inserts a soft line break (`\n`) instead of splitting the block.

```tsx
<blockquote>
  Hello|
</blockquote>
```

After pressing `Enter` with `rules: { break: { default: 'lineBreak' } }`:

```tsx
<blockquote>
  Hello
  |
</blockquote>
```

## `rules.break`

Controls what happens when users press `Enter` within specific block types.

### Configuration

```tsx
CalloutPlugin.configure({
  rules: {
    break: {
      // Action when Enter is pressed normally
      default: 'default' | 'lineBreak' | 'exit' | 'deleteExit',
      
      // Action when Enter is pressed in an empty block
      empty: 'default' | 'reset' | 'exit' | 'lift' | 'deleteExit',
      
      // Action when Enter is pressed at end of empty line
      emptyLineEnd: 'default' | 'exit' | 'deleteExit',

      // If true, the new block after splitting will be reset
      splitReset: boolean,
    },
  },
});
```

Each property controls a specific scenario:

- `default`
  - [`'default'`](#default)
  - [`'lineBreak'`](#linebreak)
  - [`'exit'`](#exit)
  - [`'deleteExit'`](#deleteexit)

- `empty`
  - [`'default'`](#default)
  - [`'reset'`](#reset)
  - [`'exit'`](#exit)
  - [`'lift'`](#lift)
  - [`'deleteExit'`](#deleteexit)

- `emptyLineEnd`
  - [`'default'`](#default)
  - [`'exit'`](#exit)
  - [`'deleteExit'`](#deleteexit)

- `splitReset`: If `true`, resets the new block to the default type after a split. This is useful for exiting a formatted block like a heading.

### Examples

**Reset heading on break:**

```tsx
import { H1Plugin } from '@platejs/heading/react';

const plugins = [
  // ...otherPlugins,
  H1Plugin.configure({
    rules: {
      break: {
        splitReset: true,
      },
    },
  }),
];
```

Before pressing `Enter`:

```tsx
<h1>
  Heading|text
</h1>
```

After (split and reset):

```tsx
<h1>
  Heading
</h1>
<p>
  |text
</p>
```

**Callout with line breaks and smart exits:**

```tsx
import { CalloutPlugin } from '@platejs/callout/react';

const plugins = [
  // ...otherPlugins,
  CalloutPlugin.configure({
    rules: {
      break: {
        default: 'lineBreak',
        empty: 'reset',
        emptyLineEnd: 'deleteExit',
      },
    },
  }),
];
```

Before pressing `Enter` in callout:
```tsx
<callout>
  Quote text|
</callout>
```

After (line break):
```tsx
<callout>
  Quote text
  |
</callout>
```

**Code block with custom empty handling:**

```tsx
import { CodeBlockPlugin } from '@platejs/code-block/react';

const plugins = [
  // ...otherPlugins,
  CodeBlockPlugin.configure({
    rules: {
      delete: { empty: 'reset' },
      match: ({ editor, rule }) => {
        return rule === 'delete.empty' && isCodeBlockEmpty(editor);
      },
    },
  }),
];
```

Before pressing `Backspace` in empty code block:
```tsx
<code_block>
  <code_line>
    |
  </code_line>
</code_block>
```

After (reset):
```tsx
<p>
  |
</p>
```

## `rules.delete`

Controls what happens when users press `Backspace` at specific positions.

### Configuration

```tsx
HeadingPlugin.configure({
  rules: {
    delete: {
      // Action when Backspace is pressed at block start
      start: 'default' | 'reset' | 'lift',
      
      // Action when Backspace is pressed in empty block
      empty: 'default' | 'reset',
    },
  },
});
```

Each property controls a specific scenario:

- `start`
  - [`'default'`](#default)
  - [`'reset'`](#reset)
  - [`'lift'`](#lift)

- `empty`
  - [`'default'`](#default)
  - [`'reset'`](#reset)

### Examples

**Reset callouts at start:**

```tsx
import { CalloutPlugin } from '@platejs/callout/react';

const plugins = [
  // ...otherPlugins,
  CalloutPlugin.configure({
    rules: {
      delete: { start: 'reset' },
    },
  }),
];
```

Before pressing `Backspace` at start:
```tsx
<callout>
  |Callout content
</callout>
```

After (reset):
```tsx
<p>
  |Callout content
</p>
```

**List items with start reset:**

```tsx
import { ListPlugin } from '@platejs/list/react';

const plugins = [
  // ...otherPlugins,
  ListPlugin.configure({
    rules: {
      delete: { start: 'reset' },
      match: ({ rule, node }) => {
        return rule === 'delete.start' && Boolean(node.listStyleType);
      },
    },
  }),
];
```

Before pressing `Backspace` at start of list item:
```tsx
<p listStyleType="disc">
  |List item content
</p>
```

After (reset):
```tsx
<p>
  |List item content
</p>
```

## `rules.merge`

Controls how blocks behave when merging with previous blocks.

### Configuration

```tsx
ParagraphPlugin.configure({
  rules: {
    merge: {
      // Whether to remove empty blocks when merging
      removeEmpty: boolean,
    },
  },
});
```

### Examples

Only paragraph and heading plugins enable removal by default. Most other plugins use `false`:

```tsx
import { H1Plugin, ParagraphPlugin } from 'platejs/react';

const plugins = [
  // ...otherPlugins,
  H1Plugin, // rules.merge: { removeEmpty: true } by default
  ParagraphPlugin, // rules.merge: { removeEmpty: true } by default
];
```

Before pressing `Backspace` at start:
```tsx
<p>
  <text />
</p>
<h1>
  |Heading content
</h1>
```

After (empty paragraph removed):
```tsx
<h1>
  |Heading content
</h1>
```

**Callout with removal disabled:**

```tsx
import { CalloutPlugin } from '@platejs/callout/react';

const plugins = [
  // ...otherPlugins,
  CalloutPlugin.configure({
    rules: {
      merge: { removeEmpty: false }, // Default
    },
  }),
];
```

Before pressing `Backspace` at start:
```tsx
<p>
  <text />
</p>
<callout>
  |Callout content
</callout>
```

After (empty paragraph preserved):
```tsx
<p>
  |Code content
</p>
```

**Table cells preserve structure during merge:**

```tsx
import { TablePlugin } from '@platejs/table/react';

const plugins = [
  // ...otherPlugins,
  TablePlugin, // Table cells have rules.merge: { removeEmpty: false }
];
```

Before pressing `Delete` at end of paragraph:
```tsx
<p>
  Content|
</p>
<table>
  <tr>
    <td>
      <p>Cell data</p>
    </td>
    <td>
      <p>More data</p>
    </td>
  </tr>
</table>
```

After (cell content merged, structure preserved):
```tsx
<p>
  Content|Cell data
</p>
<table>
  <tr>
    <td>
      <p>
        <text />
      </p>
    </td>
    <td>
      <p>More data</p>
    </td>
  </tr>
</table>
```

<Callout>
Slate's default is `true` since the default block (paragraph) is first-class, while Plate plugins are likely used to define other node behaviors that shouldn't automatically remove empty predecessors.
</Callout>

## `rules.normalize`

Controls how nodes are normalized during the normalization process.

### Configuration

```tsx
LinkPlugin.configure({
  rules: {
    normalize: {
      // Whether to remove nodes with empty text
      removeEmpty: boolean,
    },
  },
});
```

### Examples

**Remove empty link nodes:**

```tsx
import { LinkPlugin } from '@platejs/link/react';

const plugins = [
  // ...otherPlugins,
  LinkPlugin.configure({
    rules: {
      normalize: { removeEmpty: true },
    },
  }),
];
```

Before normalization:
```tsx
<p>
  <a href="http://google.com">
    <text />
  </a>
  <cursor />
</p>
```

After normalization (empty link removed):
```tsx
<p>
  <cursor />
</p>
```

## `rules.match`

The `match` function in plugin rules allows you to override the default behavior of specific plugins based on node properties beyond just type matching. This is particularly useful when you want to extend existing node types with new behaviors.

### Examples

**Code block with custom empty detection:**

```tsx
import { CodeBlockPlugin } from '@platejs/code-block/react';

const plugins = [
  // ...otherPlugins,
  CodeBlockPlugin.configure({
    rules: {
      delete: { empty: 'reset' },
      match: ({ rule, node }) => {
        return rule === 'delete.empty' && isCodeBlockEmpty(editor);
      },
    },
  }),
];
```

Since the list plugin extends existing blocks that already have their own plugin configuration (e.g. `ParagraphPlugin`), using `rules.match` allows you to override those behaviors.

**List override for paragraphs:**

```tsx
import { ListPlugin } from '@platejs/list/react';

const plugins = [
  // ...otherPlugins,
  ListPlugin.configure({
    rules: {
      match: ({ editor, rule }) => {
        return rule === 'delete.empty' && isCodeBlockEmpty(editor);
      },
    },
  }),
];
```

## Custom Reset Logic

Some plugins need special reset behavior beyond the standard paragraph conversion. You can override the `resetBlock` transform:

**List plugin reset (outdents instead of converting to paragraph):**

```tsx
const ListPlugin = createPlatePlugin({
  key: 'list',
  // ... other config
}).overrideEditor(({ editor, tf: { resetBlock } }) => ({
  transforms: {
    resetBlock(options) {
      if (editor.api.block(options)?.[0]?.listStyleType) {
        outdentList();
        return;
      }
      
      return resetBlock(options);
    },
  },
}));
```

**Code block reset (unwraps instead of converting):**

```tsx
const CodeBlockPlugin = createPlatePlugin({
  key: 'code_block',
  // ... other config
}).overrideEditor(({ editor, tf: { resetBlock } }) => ({
  transforms: {
    resetBlock(options) {
      if (editor.api.block({
        at: options?.at,
        match: { type: 'code_block' },
      })) {
        unwrapCodeBlock();
        return;
      }
      
      return resetBlock(options);
    },
  },
}));
```

## Combining Rules

You can combine different rules for comprehensive block behavior:

```tsx
import { H1Plugin } from '@platejs/heading/react';

const plugins = [
  // ...otherPlugins,
  H1Plugin.configure({
    rules: {
      break: {
        empty: 'reset',
        splitReset: true,
      },
      delete: {
        start: 'reset',
      },
    },
  }),
];
```

**Line break behavior (default):**
```tsx
<blockquote>
  Hello|
</blockquote>
```

After `Enter`:
```tsx
<blockquote>
  Hello
  |
</blockquote>
```

**Empty reset behavior:**
```tsx
<blockquote>
  |
</blockquote>
```

After `Enter`:
```tsx
<p>
  |
</p>
```

**Start reset behavior:**
```tsx
<blockquote>
  |Quote content
</blockquote>
```
After `Backspace`:
```tsx
<p>
  |Quote content
</p>
```

## Advanced

For complex scenarios beyond simple rules, you can override editor transforms directly using [`.overrideEditor`](/docs/plugin-methods#overrideeditor). This gives you complete control over transforms like [`resetBlock`](/docs/plugin-methods#extendtransforms) and [`insertExitBreak`](/docs/plugin-methods#extendtransforms):

```tsx
const CustomPlugin = createPlatePlugin({
  key: 'custom',
  // ... other config
}).overrideEditor(({ editor, tf: { insertBreak, deleteBackward, resetBlock } }) => ({
  transforms: {
    insertBreak() {
      const block = editor.api.block();
      
      if (/* Custom condition */) {
        // Custom behavior
        return;
      }
      
      // Default behavior
      insertBreak();
    },
    
    deleteBackward(unit) {
      const block = editor.api.block();
      
      if (/* Custom condition */) {
        // Custom behavior
        return;
      }
      
      deleteBackward(unit);
    },
    
    resetBlock(options) {
      if (/* Custom condition */) {
        // Custom behavior
        return true;
      }
      
      return resetBlock(options);
    },
  },
}));
```

## `rules.selection`

Controls how cursor positioning and text insertion behave at node boundaries, particularly for marks and inline elements.

### Configuration

```tsx
BoldPlugin.configure({
  rules: {
    selection: {
      // Define selection behavior at boundaries
      affinity: 'default' | 'directional' | 'outward' | 'hard',
    },
  },
});
```

### Affinity Options

The `affinity` property determines how the cursor behaves when positioned at the boundary between different marks or inline elements:

#### `default`

Uses Slate's default behavior. For marks, the cursor has outward affinity at the start edge (typing before the mark doesn't apply it) and inward affinity at the end edge (typing after the mark extends it).

**At end of mark (inward affinity):**
```tsx
<p>
  <text bold>Bold text|</text><text>Normal text</text>
</p>
```

Typing would extend the bold formatting to new text.

**At start of mark (outward affinity):**
```tsx
<p>
  <text>Normal text|</text><text bold>Bold text</text>
</p>
```

Typing would not apply bold formatting to new text.

#### `directional`

Selection affinity is determined by the direction of cursor movement. When the cursor moves to a boundary, it maintains the affinity based on where it came from.

```tsx
import { BoldPlugin } from '@platejs/basic-nodes/react';

const plugins = [
  // ...otherPlugins,
  BoldPlugin.configure({
    rules: {
      selection: { affinity: 'directional' },
    },
  }),
];
```

**Movement from right (inward affinity):**
```tsx
<p>
  <text>Normal</text><text bold>B|old text</text>
</p>
```

After pressing `←`:
```tsx
<p>
  <text>Normal</text><text bold>|Bold text</text>
</p>
```

Typing would extend the bold formatting, which is not possible with `default` affinity.

```tsx
import { LinkPlugin } from '@platejs/link/react';

const plugins = [
  // ...otherPlugins,
  LinkPlugin.configure({
    rules: {
      selection: { affinity: 'directional' },
    },
  }),
];
```

**Movement from right (outward affinity):**
```tsx
<p>
  Visit <a href="https://example.com">our website</a> |for more information text.
</p>
```

After pressing `←`:
```tsx
<p>
  Visit <a href="https://example.com">our website</a>| for more information text.
</p>
```

Cursor movement direction determines whether new text extends the link or creates new text outside it.

#### `outward`

Forces outward affinity, automatically clearing marks when typing at their boundaries. This creates a natural "exit" behavior from formatted text.

```tsx
import { CommentPlugin } from '@platejs/comment/react';

const plugins = [
  // ...otherPlugins,
  CommentPlugin.configure({
    rules: {
      selection: { affinity: 'outward' },
    },
  }),
];
```

**At end of marked text:**
```tsx
<p>
  <text comment>Commented text|</text><text>Normal</text>
</p>
```

After typing:
```tsx
<p>
  <text comment>Commented text</text><text>x|Normal</text>
</p>
```

Users automatically exit comment formatting by typing at the end of commented text.

#### `hard`

Creates a "hard" edge that requires two key presses to move across. This provides precise cursor control for elements that need exact positioning.

```tsx
import { CodePlugin } from '@platejs/basic-nodes/react';

const plugins = [
  // ...otherPlugins,
  CodePlugin.configure({
    rules: {
      selection: { affinity: 'hard' },
    },
  }),
];
```

**Moving across hard edges:**
```tsx
<p>
  <text>Before</text><text code>code|</text><text>After</text>
</p>
```

First `→` press changes affinity:
```tsx
<p>
  <text>Before</text><text code>code</text>|<text>After</text>
</p>
```

Second `→` press moves cursor:
```tsx
<p>
  <text>Before</text><text code>code</text><text>A|fter</text>
</p>
```

This allows users to position the cursor precisely at the boundary and choose whether new text should be inside or outside the code formatting.


# Plugin Shortcuts

Source: https://platejs.org/docs/plugin-shortcuts

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Plugin Shortcuts
description: Configure keyboard shortcuts on Plate plugins.
---

Plugin shortcuts map key combinations to plugin methods or explicit handlers. Plate resolves shortcuts during plugin setup, stores them on `editor.meta.shortcuts`, and renders them through `EditorHotkeysEffect` inside the editable. This guide covers linked methods, custom handlers, overrides, priorities, and default shortcut ownership.

## How Shortcuts Resolve

Each plugin owns a `shortcuts` object. At resolution time Plate namespaces every shortcut as `${plugin.key}.${shortcutName}`.

When a shortcut has no `handler`, Plate looks for a matching plugin-specific method in this order:

1. `editor.tf[plugin.key][shortcutName]`
2. `editor.api[plugin.key][shortcutName]`

If neither method exists and no `handler` is provided, the shortcut is ignored by `EditorHotkeysEffect`.

| Field | Meaning |
| --- | --- |
| `keys` | Key combination passed to `useHotkeys`. Use a string like `'mod+b'` or arrays like `[[Key.Mod, 'b']]`. |
| `handler` | Explicit callback receiving `{ editor, event, eventDetails }`. |
| `priority` | Shortcut priority. Defaults to the parent plugin priority. |
| `preventDefault` | Passed through to `useHotkeys`. When omitted, Plate calls `event.preventDefault()` and `event.stopPropagation()` after handled shortcuts. |
| `null` | Removes that named shortcut from the plugin. |

## Linked Transform Shortcuts

Use a linked transform when the shortcut name and plugin transform name are the same.

```tsx title="plugins/signature-plugin.tsx" showLineNumbers
import { Key, createPlatePlugin } from 'platejs/react';

export const SignaturePlugin = createPlatePlugin({
  key: 'signature',
})
  .extendTransforms(({ editor }) => ({
    insertSignature: () => {
      editor.tf.insertText(' - Plate');
    },
  }))
  .extend({
    shortcuts: {
      insertSignature: {
        keys: [[Key.Mod, Key.Shift, 's']],
      },
    },
  });
```

Pressing `Mod+Shift+S` calls `editor.tf.signature.insertSignature()`.

## Linked API Shortcuts

If there is no matching transform, Plate falls back to the plugin-specific API method.

```tsx title="plugins/inspect-plugin.tsx" showLineNumbers
import { Key, createPlatePlugin } from 'platejs/react';

export const InspectPlugin = createPlatePlugin({
  key: 'inspect',
})
  .extendApi(({ editor }) => ({
    logText: () => {
      editor.api.debug.info('Editor text', editor.api.string([]));
    },
  }))
  .extend({
    shortcuts: {
      logText: {
        keys: [[Key.Mod, Key.Alt, 'l']],
      },
    },
  });
```

Pressing `Mod+Alt+L` calls `editor.api.inspect.logText()`.

<Callout type="info" title="Transforms win">
  If a transform and an API method share the same shortcut name, Plate uses the
  transform. Pick distinct names when you need both actions.
</Callout>

## Custom Handlers

Use a `handler` when the shortcut needs the keyboard event, custom branching, or work that should not live as a plugin API/transform method.

```tsx title="plugins/draft-plugin.tsx" showLineNumbers
import { Key, createPlatePlugin } from 'platejs/react';

export const DraftPlugin = createPlatePlugin({
  key: 'draft',
}).extend({
  shortcuts: {
    saveDraft: {
      keys: [[Key.Mod, 's']],
      handler: ({ editor }) => {
        const text = editor.api.string([]);

        if (text.trim().length === 0) return false;

        editor.api.debug.info('Draft text', text);

        return true;
      },
    },
  },
});
```

Returning `false` means "not handled"; Plate will not call `preventDefault()` for that key press. Returning `true` or `undefined` means handled when `preventDefault` is omitted.

## Prevent Default

Plate has two layers of default-prevention behavior:

| Configuration | Behavior |
| --- | --- |
| `preventDefault` omitted and handler returns anything except `false` | Plate calls `event.preventDefault()` and `event.stopPropagation()`. |
| Handler returns `false` | Plate leaves the event alone. |
| `preventDefault` is set | Plate passes the option to `useHotkeys` and skips its own `preventDefault()` call. |

Use the default omission for normal editor commands. Set `preventDefault` only when you intentionally want `useHotkeys` to own that behavior.

## Configure Existing Shortcuts

Configure a named shortcut to change its keys.

```tsx title="plugins/basic-marks.tsx" showLineNumbers
import { BoldPlugin } from '@platejs/basic-nodes/react';
import { Key } from 'platejs/react';

export const AppBoldPlugin = BoldPlugin.configure({
  shortcuts: {
    toggle: {
      keys: [[Key.Mod, Key.Shift, 'b']],
    },
  },
});
```

Set a shortcut to `null` to remove it.

```tsx title="plugins/basic-marks.tsx" showLineNumbers
import { ItalicPlugin } from '@platejs/basic-nodes/react';

export const AppItalicPlugin = ItalicPlugin.configure({
  shortcuts: {
    toggle: null,
  },
});
```

The `null` value removes `italic.toggle` from `editor.meta.shortcuts`.

## Multiple Shortcuts

A plugin can declare multiple shortcut names. Keep each name aligned with the method it should call.

```tsx title="plugins/review-plugin.tsx" showLineNumbers
import { Key, createPlatePlugin } from 'platejs/react';

export const ReviewPlugin = createPlatePlugin({
  key: 'review',
})
  .extendTransforms(({ editor }) => ({
    accept: () => editor.tf.insertText('Accepted'),
    reject: () => editor.tf.insertText('Rejected'),
  }))
  .extend({
    shortcuts: {
      accept: {
        keys: [[Key.Mod, Key.Alt, 'a']],
      },
      reject: {
        keys: [[Key.Mod, Key.Alt, 'r']],
      },
    },
  });
```

This creates `review.accept` and `review.reject` in `editor.meta.shortcuts`.

## Priority

Shortcut priority defaults to the parent plugin priority. Set `priority` on a shortcut when two handlers use the same key combination and one should win.

```tsx title="plugins/priority-plugin.tsx" showLineNumbers
import { createPlatePlugin } from 'platejs/react';

export const PriorityPlugin = createPlatePlugin({
  key: 'priority',
  priority: 20,
}).extend({
  shortcuts: {
    openCommandMenu: {
      keys: 'mod+k',
      priority: 200,
      handler: ({ editor }) => {
        editor.api.debug.info('Open command menu');

        return true;
      },
    },
  },
});
```

Plate stores the resolved priority with the shortcut and passes it to `useHotkeys`.

## Editor-Level Shortcuts

`createPlateEditor({ shortcuts })` attaches shortcuts to the root plugin. Use it for editor-wide commands that do not belong to one feature plugin.

```tsx title="editor.ts" showLineNumbers
import { createPlateEditor } from 'platejs/react';

export const editor = createPlateEditor({
  shortcuts: {
    reportWordCount: {
      keys: 'mod+shift+w',
      handler: ({ editor }) => {
        const words = editor.api.string([]).trim().split(/\s+/).filter(Boolean);

        editor.api.debug.info('Word count', words.length);

        return true;
      },
    },
  },
});
```

Internally this becomes a root shortcut, so plugin-owned shortcuts are still the better fit for feature-owned behavior.

## Default Shortcuts

| Plugin | Shortcut name | Keys |
| --- | --- | --- |
| `BoldPlugin` | `toggle` | `Mod+B` |
| `ItalicPlugin` | `toggle` | `Mod+I` |
| `UnderlinePlugin` | `toggle` | `Mod+U` |
| `ParagraphPlugin` | `toggleParagraph` | `Mod+Alt+0`, `Mod+Shift+0` |
| `CopilotPlugin` | `accept` | `Tab` |
| `CopilotPlugin` | `reject` | `Escape` |

Other plugins often expose `toggle`, `insert`, or feature-specific transforms without default keys. Add shortcuts in your app when those commands should be keyboard-accessible.

## API Reference

```ts title="Shortcut type"
type Shortcut = HotkeysOptions & {
  keys?: Keys | null;
  priority?: number;
  handler?: (ctx: {
    editor: PlateEditor;
    event: KeyboardEvent;
    eventDetails: HotkeysEvent;
  }) => boolean | void;
};
```

Done. Name shortcuts after plugin-specific transforms or API methods by default, and use handlers only when the keyboard event is part of the behavior.


# Plugin Configuration

Source: https://platejs.org/docs/plugin

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Plugin Configuration
description: How to configure and customize Plate plugins.
---

Plate plugins are highly configurable, allowing you to customize their behavior to suit your needs. This guide will walk you through the most common configuration options and how to use them.

- [Getting Started: Components](/docs/installation#components) - Instructions for adding plugins to your editor
- [PlatePlugin API](/docs/api/core/plate-plugin) - The complete API reference for creating plugins

## Basic Plugin Configuration

### New Plugin

The most basic plugin configuration requires only a `key`:

```ts
const MyPlugin = createPlatePlugin({
  key: 'minimal',
});
```

While this plugin doesn't do anything yet, it's a starting point for more complex configurations.

### Existing Plugin

The `.configure` method allows you to configure an existing plugin:

```ts
const ConfiguredPlugin = MyPlugin.configure({
  options: {
    myOption: 'new value',
  },
});
```

## Node Plugins

Node plugins are used to define new types of nodes in your editor using the `node` property. These can be elements (either block or inline) or leaf nodes (for text-level formatting).


### Elements

To create a new type of element, use the `node.isElement` option:

```ts
const ParagraphPlugin = createPlatePlugin({
  key: 'p',
  node: {
    isElement: true,
    type: 'p',
  },
});
```

You can associate a component with your element. See [Plugin Components](/docs/plugin-components) for more information.

```ts
const ParagraphPlugin = createPlatePlugin({
  key: 'p',
  node: {
    isElement: true,
    type: 'p',
    component: ParagraphElement,
  },
});
```

### Inline, Void, and Leaf Nodes

For inline elements, void elements, or leaf nodes, use the appropriate node options:

```ts
const LinkPlugin = createPlatePlugin({
  key: 'link',
  node: {
    isElement: true,
    isInline: true,
    type: 'a',
  },
});

const ImagePlugin = createPlatePlugin({
  key: 'image',
  node: {
    isElement: true,
    isVoid: true,
    type: 'img',
  },
});

const BoldPlugin = createPlatePlugin({
  key: 'bold',
  node: {
    isLeaf: true,
  },
});
```

## Behavioral Plugins

Rather than render an element or a mark, you may want to customize the behavior of your editor. Various plugin options are available to modify the behavior of Plate.

### Plugin Rules

The `rules` property allows you to configure common editing behaviors like breaking, deleting, and merging nodes without overriding editor methods. This is a powerful way to define intuitive interactions for your custom elements.

For example, you can define what happens when a user presses `Enter` in an empty heading, or `Backspace` at the start of a blockquote.

```ts
import { H1Plugin } from '@platejs/heading/react';

H1Plugin.configure({
  rules: {
    break: { empty: 'reset' },
  },
});
```

See the [Plugin Rules guide](/docs/plugin-rules) for a complete list of available rules and actions.

### Event Handlers

The recommended way to respond to user-generated events from inside a plugin is with the `handlers` plugin option. A handler should be a function that takes a `PlatePluginContext & { event }` object.

The `onChange` handler, which is called when the editor value changes, is an exception to this rule; the context object includes the changed `value` instead of `event`.

```ts showLineNumbers
const ExamplePlugin = createPlatePlugin({
  key: 'example',
  handlers: {
    onChange: ({ editor, value })  => {
      console.info(editor, value);
    },
    onKeyDown: ({ editor, event }) => {
      console.info(`You pressed ${event.key}`);
    },
  },
});
```

### Inject Props

You may want to inject a class name or CSS property into any node having a certain property. For example, the following plugin sets the `textAlign` CSS property on paragraphs with an `align` property.

```ts showLineNumbers
import { KEYS } from 'platejs';

const TextAlignPlugin = createPlatePlugin({
  key: 'align',
  inject: {
    nodeProps: {
      defaultNodeValue: 'start',
      nodeKey: 'align',
      styleKey: 'textAlign',
      validNodeValues: ['start', 'left', 'center', 'right', 'end', 'justify'],
    },
    targetPlugins: [KEYS.p],
    // This is injected into all `targetPlugins`. In this example, ParagraphPlugin will be able to deserialize `textAlign` style.
    targetPluginToInject: ({ editor, plugin }) => ({
      parsers: {
        html: {
          deserializer: {
            parse: ({ element, node }) => {
              if (element.style.textAlign) {
                node[editor.getType('align')] = element.style.textAlign;
              }
            },
          },
        },
      },
    }),
  },
});
```

A paragraph node affected by the above plugin would look like this:

```ts showLineNumbers {3}
{
  type: 'p',
  align: 'right',
  children: [{ text: 'This paragraph is aligned to the right!' }],
}
```

### Override Editor Methods

The `overrideEditor` method provides a way to override existing editor methods while maintaining access to the original implementations. This is particularly useful when you want to modify the behavior of core editor functionality.

```ts
const CustomPlugin = createPlatePlugin({
  key: 'custom',
}).overrideEditor(({ editor, tf: { deleteForward }, api: { isInline } }) => ({
  // Override transforms
  transforms: {
    deleteForward(options) {
      // Custom logic before deletion
      console.info('Deleting forward...');
      
      // Call original transform
      deleteForward(options);
      
      // Custom logic after deletion
      console.info('Deleted forward');
    },
  },
  // Override API methods
  api: {
    isInline(element) {
      // Custom inline element check
      if (element.type === 'custom-inline') {
        return true;
      }
      
      // Fall back to original behavior
      return isInline(element);
    },
  },
}));
```

- Access to original methods via destructured `tf` (transforms) and `api` parameters
- Type-safe overrides of existing methods
- Clean separation between transforms and API methods
- Plugin context and options access

Example with typed options:

```ts
type CustomConfig = PluginConfig<
  'custom',
  { allowDelete: boolean }
>;

const CustomPlugin = createTPlatePlugin<CustomConfig>({
  key: 'custom',
  options: { allowDelete: true },
}).overrideEditor(({ editor, tf: { deleteForward }, getOptions }) => ({
  transforms: {
    deleteForward(options) {
      // Use typed options to control behavior
      if (!getOptions().allowDelete) {
        return;
      }
      
      deleteForward(options);
    },
  },
}));
```

### Extend Editor (Advanced)

You can extend the editor for complex functionality. To do this, you can use the `extendEditor` plugin option to directly mutate properties of the `editor` object after its creation.

```ts showLineNumbers {20}
const CustomNormalizerPlugin = createPlatePlugin({
  key: 'customNormalizer',
  extendEditor: ({ editor }) => {
    editor.customState = true;
    
    return editor;
  },
});
```

<Callout type="info" title="Difference between extendEditor and overrideEditor">
- Use `extendEditor` when integrating legacy Slate plugins like `withYjs` that need direct editor mutation. There is only one `extendEditor` per plugin.
- Prefer using `overrideEditor` for modifying editor behavior as it has single purpose responsibility and better type safety. It can be called multiple times to layer different overrides.
</Callout>

## Advanced Plugin Configuration

### Plugin Store

Each plugin has its own store, which can be used to manage plugin-specific state.

```ts
const MyPlugin = createPlatePlugin({
  key: 'myPlugin',
  options: {
    count: 0,
  },
}).extend(({ editor, plugin, setOption }) => ({
  handlers: {
    onClick: () => {
      setOption('count', 1);
    },
  },
}));
```

You can access and update the store using the following methods:

```ts
// Get the current value
const count = editor.getOption(MyPlugin, 'count');

// Set a new value
editor.setOption(MyPlugin, 'count', 5);

// Update the value based on the previous state
editor.setOption(MyPlugin, 'count', (prev) => prev + 1);
```

In React components, you can use the `usePluginOption` or `usePluginOptions` hook to subscribe to store changes:

```tsx
const MyComponent = () => {
  const count = usePluginOption(MyPlugin, 'count');
  return <div>Count: {count}</div>;
};
```

See more in [Plugin Context](/docs/plugin-context) and [Editor Methods](/docs/editor-methods) guides.


### Dependencies

You can specify plugin dependencies using the `dependencies` property. This ensures that the required plugins are loaded before the current plugin.

```ts
const MyPlugin = createPlatePlugin({
  key: 'myPlugin',
  dependencies: ['paragraphPlugin', 'listPlugin'],
});
```

### Enabled Flag

The `enabled` property allows you to conditionally enable or disable a plugin:

```ts
const MyPlugin = createPlatePlugin({
  key: 'myPlugin',
  enabled: true, // or false to disable
});
```

### Nested Plugins

Plate supports nested plugins, allowing you to create plugin hierarchies. Use the `plugins` property to define child plugins:

```ts
const ParentPlugin = createPlatePlugin({
  key: 'parent',
  plugins: [
    createPlatePlugin({ key: 'child1' }),
    createPlatePlugin({ key: 'child2' }),
  ],
});
```

### Plugin Priority

The `priority` property determines the order in which plugins are registered and executed. Plugins with higher priority values are processed first:

```ts
const HighPriorityPlugin = createPlatePlugin({
  key: 'highPriority',
  priority: 100,
});

const LowPriorityPlugin = createPlatePlugin({
  key: 'lowPriority',
  priority: 50,
});
```

This is particularly useful when you need to ensure certain plugins are initialized or run before others.

### Custom Parsers

The `parsers` property accepts string keys to build your own parsers:

```ts
const MyPlugin = createPlatePlugin({
  key: 'myPlugin',
  parsers: {
    myCustomParser: {
      deserializer: {
        parse: // ...
      },
      serializer: {
        parse: // ...
      }
    },
  },
});
```

Core plugins includes `html` and `htmlReact` parsers.

## Typed Plugins

Using above methods, plugin types are automatically inferred from the given configuration.

If you need to pass an explicit type as generic, you can use `createTPlatePlugin`.

### Using createTPlatePlugin

The `createTPlatePlugin` function allows you to create a typed plugin:

```ts
type CodeBlockConfig = PluginConfig<
  // key
  'code_block',
  // options
  { syntax: boolean; syntaxPopularFirst: boolean },
  // api
  {
    plugin: {
      getSyntaxState: () => boolean;
    };
    toggleSyntax: () => void;
  },
  // transforms
  {
    insert: {
      codeBlock: (options: { language: string }) => void;
    }
  }
>;

const CodeBlockPlugin = createTPlatePlugin<CodeBlockConfig>({
  key: 'code_block',
  options: { syntax: true, syntaxPopularFirst: false },
}).extendEditorApi<CodeBlockConfig['api']>(() => ({
  plugin: {
    getSyntaxState: () => true,
  },
  toggleSyntax: () => {},
})).extendEditorTransforms<CodeBlockConfig['transforms']>(() => ({
  insert: {
    codeBlock: ({ editor, getOptions }) => {
      editor.tf.insertBlock({ type: 'code_block', language: getOptions().language });
    },
  },
}));
```

### Using Typed Plugins

When using typed plugins, you get full type checking and autocompletion ✨

```ts
const editor = createPlateEditor({
  plugins: [ExtendedCodeBlockPlugin],
});

// Type-safe access to options
const options = editor.getOptions(ExtendedCodeBlockPlugin);
options.syntax;
options.syntaxPopularFirst;
options.hotkey;

// Type-safe API
editor.api.toggleSyntax();
editor.api.plugin.getSyntaxState();
editor.api.plugin2.setLanguage('python');
editor.api.plugin.getLanguage();

// Type-safe Transforms
editor.tf.insert.codeBlock({ language: 'typescript' });
```

## See also

See the [PlatePlugin API](/docs/api/core/plate-plugin) for more plugin options.


# Static Rendering

Source: https://platejs.org/docs/static

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Static Rendering
description: A minimal, memoized, read-only version of Plate with RSC/SSR support.
---

`<PlateStatic>` is a **fast, read-only** React component for rendering Plate content, optimized for **server-side** or **React Server Component** (RSC) environments. It avoids client-side editing logic and memoizes node renders for better performance compared to using [`<Plate>`](/docs/api/core/plate-components) in read-only mode.

It's a core part of [`serializeHtml`](/docs/api/core/plate-plugin#serializehtml) for HTML export and is ideal for any server or RSC context needing a non-interactive, presentational view of Plate content.

## Key Advantages

-   **Server-Safe:** No browser API dependencies; works in SSR/RSC.
-   **No Plate Editor Overhead:** Excludes interactive features like selections or event handlers.
-   **Memoized Rendering:** Uses `_memo` and structural checks to re-render only changed nodes.
-   **Partial Re-Renders:** Changes in one part of the document don't force a full re-render.
-   **Lightweight:** Smaller bundle size as it omits interactive editor code.

## When to Use `<PlateStatic>`

-   Generating HTML with [HTML Serialization](/docs/html).
-   Displaying server-rendered previews in Next.js (especially with RSC).
-   Building static sites with read-only Plate content.
-   Optimizing performance-critical read-only views.
-   Rendering AI-streaming content.

<Callout type="info" title="Interactive vs. Static">
  For interactive read-only features (like comment popovers or selections), use the standard `<Plate>` component in the browser. For purely server-rendered, non-interactive content, `<PlateStatic>` is the recommended choice.
</Callout>

## Kit Usage

<Steps>

### Installation

The fastest way to enable static rendering is with the `BaseEditorKit`, which includes pre-configured base plugins that work seamlessly with server-side rendering.

[editor-base-kit registry content](https://platejs.org/r/editor-base-kit)

### Add Kit

```tsx
import { createSlateEditor } from 'platejs';
import { PlateStatic } from 'platejs/static';
import { BaseEditorKit } from '@/components/editor/editor-base-kit';

const editor = createSlateEditor({
  plugins: BaseEditorKit,
  value: [
    { type: 'h1', children: [{ text: 'Server-Rendered Title' }] },
    { type: 'p', children: [{ text: 'This content is rendered statically.' }] },
  ],
});

// Render statically
export default function MyStaticPage() {
  return <PlateStatic editor={editor} />;
}
```

### Example

See a complete server-side static rendering example:

[slate-to-html registry content](https://platejs.org/r/slate-to-html)

</Steps>

## Manual Usage

<Steps>

### Create a Slate Editor

Initialize a Slate editor instance using `createSlateEditor` with your required plugins and components. This is analogous to using `usePlateEditor` for the interactive `<Plate>` component.

```tsx title="lib/plate-static-editor.ts"
import { createSlateEditor } from 'platejs';
// Import your desired base plugins (e.g., BaseHeadingPlugin, MarkdownPlugin)
// Ensure you are NOT importing from /react subpaths for server environments.

const editor = createSlateEditor({
  plugins: [
    // Add your list of base plugins here
    // Example: BaseHeadingPlugin, MarkdownPlugin.configure({...})
  ],
  value: [ // Example initial value
    {
      type: 'p',
      children: [{ text: 'Hello from a static Plate editor!' }],
    },
  ],
});
```

### Define Static Node Components

If your interactive editor uses client-side components (e.g., with `use client` or event handlers), you **must** create static, server-safe equivalents. These components should render pure HTML without browser-specific logic.

```tsx title="components/ui/paragraph-node-static.tsx"
import React from 'react';
import type { SlateElementProps } from 'platejs/static';

export function ParagraphElementStatic(props: SlateElementProps) {
  return (
    <SlateElement {...props}>
      {props.children}
    </SlateElement>
  );
}
```
Create similar static components for headings, images, links, etc.

### Map Plugin Keys to Static Components

Create an object that maps plugin keys or node types to their corresponding static React components, then pass it to the editor.

```ts title="components/static-components.ts"
import { ParagraphElementStatic } from './ui/paragraph-node-static';
import { HeadingElementStatic } from './ui/heading-node-static';
// ... import other static components

export const staticComponents = {
  p: ParagraphElementStatic,
  h1: HeadingElementStatic,
  // ... add mappings for all your element and leaf types
};
```

### Render `<PlateStatic>`

Use the `<PlateStatic>` component, providing the `editor` instance configured with your components.

```tsx title="app/my-static-page/page.tsx (RSC Example)"
import { createSlateEditor } from 'platejs';
import { PlateStatic } from 'platejs/static';
// import { BaseHeadingPlugin, ... } from '@platejs/basic-nodes'; // etc.
import { staticComponents } from '@/components/static-components';

export default async function MyStaticPage() {
  // Example: Fetch or define editor value
  const initialValue = [
    { type: 'h1', children: [{ text: 'Server-Rendered Title' }] },
    { type: 'p', children: [{ text: 'Content rendered statically.' }] },
  ];

  const editor = createSlateEditor({
    plugins: [/* your base plugins */],
    components: staticComponents,
    value: initialValue,
  });

  return (
    <PlateStatic
      editor={editor}
      style={{ padding: 16 }}
      className="my-plate-static-content"
    />
  );
}
```

<Callout type="note" title="Value Override">
  If you pass a `value` prop directly to `<PlateStatic>`, it will override `editor.children`.
  ```tsx
  <PlateStatic
    editor={editor}
    value={[
      { type: 'p', children: [{ text: 'Overridden content.' }] }
    ]}
  />
  ```
</Callout>

### Memoization Details

`<PlateStatic>` enhances performance through memoization:
-   Each `<ElementStatic>` and `<LeafStatic>` is wrapped in `React.memo`.
-   **Reference Equality:** Unchanged node references prevent re-renders.
-   **`_memo` Field:** Setting `node._memo = true` (or any stable value) on an element or leaf can force Plate to skip re-rendering that specific node, even if its content changes. This is useful for fine-grained control over updates.

</Steps>

## Client-Side Alternative: `PlateView`

For cases where you need **minimal interactivity** with static content, use `<PlateView>`. This component wraps `<PlateStatic>` and adds client-side event handlers for user interactions while maintaining the performance benefits of static rendering.

### Example: Server Component with Both Static Views

```tsx title="app/document/page.tsx"
import { createStaticEditor, PlateStatic } from 'platejs/static';
import { BaseEditorKit } from '@/components/editor/editor-base-kit';
import { InteractiveViewer } from './interactive-viewer';

export default async function DocumentPage() {
  const content = await fetchDocument(); // Your document data
  
  // Server-side static editor
  const editor = createStaticEditor({
    plugins: BaseEditorKit,
    value: content,
  });

  return (
    <div className="grid grid-cols-2 gap-4">
      {/* Pure static rendering - no interactivity */}
      <div>
        <h2>Static View (Server Rendered)</h2>
        <PlateStatic editor={editor} />
      </div>

      {/* Interactive view - rendered on client */}
      <div>
        <h2>Interactive View</h2>
        <InteractiveViewer value={content} />
      </div>
    </div>
  );
}
```

### Example: Client Component with PlateView

```tsx title="app/document/interactive-viewer.tsx"
'use client';

import { usePlateViewEditor } from 'platejs/react';
import { PlateView } from 'platejs/react';
import { BaseEditorKit } from '@/components/editor/editor-base-kit';

export function InteractiveViewer({ value }) {
  const editor = usePlateViewEditor({
    plugins: BaseEditorKit,
    value,
  });

  return <PlateView editor={editor} />;
}
```

### Key Features of `PlateView`

- **Client-side only**: Requires `'use client'` directive
- **Adds interactivity**: Enables user interactions with the content (e.g., text selection, copying, future interactions like tooltips, highlights, etc.)
- **Minimal overhead**: Still uses `PlateStatic` internally for rendering
- **Use with `usePlateViewEditor`**: Creates a static editor optimized for view-only React components
- **ViewPlugin included**: The static editor automatically includes `ViewPlugin` which provides event handling capabilities

<Callout type="warning" title="Server Component Compatibility">
  `PlateView` cannot be used in Server Components. If you're passing an editor from a server component to a client component, you'll encounter serialization errors. Use `PlateStatic` on the server side, or create the editor client-side with `usePlateViewEditor`.
</Callout>

## `PlateStatic` vs. `PlateView` vs. `Plate` + `readOnly`

| Aspect                | `<PlateStatic>`                                       | `<PlateView>`                                          | `<Plate>` + `readOnly`                                 |
| --------------------- | ----------------------------------------------------- | ------------------------------------------------------ | ------------------------------------------------------ |
| **Environment**       | Server/Client (SSR/RSC safe)                          | Client-only                                            | Client-only                                            |
| **Interactivity**     | None                                                  | Minimal (selection, copy, toolbar, etc.)     | Full interactive features (browser-only)               |
| **Browser APIs**      | Not used                                              | Minimal (event handlers)                               | Full usage                                             |
| **Performance**       | Best - static HTML only                               | Good - static rendering + event delegation             | Heavier - full editor internals                        |
| **Bundle Size**       | Smallest                                              | Small                                                  | Largest                                                |
| **Use Cases**         | Server rendering, HTML export                         | Client-side content with basic interactions            | Full read-only editor with all features                |
| **Recommendation**    | SSR/RSC without any interactions                      | Client-side content needing light interactivity        | Client-side with complex interactive needs             |

## RSC/SSR Example

In a Next.js App Router (or similar RSC environment), `<PlateStatic>` can be used directly in Server Components:

```tsx title="app/preview/page.tsx (RSC)"
import { createSlateEditor } from 'platejs';
import { PlateStatic } from 'platejs/static';
// Example base plugins (ensure non-/react imports)
// import { BaseHeadingPlugin } from '@platejs/basic-nodes';
import { staticComponents } from '@/components/static-components'; // Your static components mapping

export default async function Page() {
  // Fetch or define content server-side
  const serverContent = [
    { type: 'h1', children: [{ text: 'Rendered on the Server! 🎉' }] },
    { type: 'p', children: [{ text: 'This content is static and server-rendered.' }] },
  ];

  const editor = createSlateEditor({
    // plugins: [BaseHeadingPlugin, /* ...other base plugins */],
    plugins: [], // Add your base plugins
    components: staticComponents,
    value: serverContent,
  });

  return (
    <PlateStatic
      editor={editor}
      className="my-static-preview-container"
    />
  );
}
```
This renders the content to HTML on the server without needing a client-side JavaScript bundle for `PlateStatic` itself.

## Pairing with `serializeHtml`

For generating a complete HTML string (e.g., for emails, PDFs, or external systems), use `serializeHtml`. It utilizes `<PlateStatic>` internally.

```ts title="lib/html-serializer.ts"
import { createSlateEditor } from 'platejs';
import { serializeHtml } from 'platejs/static';
import { staticComponents } from '@/components/static-components';
// import { BaseHeadingPlugin, ... } from '@platejs/basic-nodes';

async function getDocumentAsHtml(value: any[]) {
  const editor = createSlateEditor({
    plugins: [/* ...your base plugins... */],
    components: staticComponents,
    value,
  });

  const html = await serializeHtml(editor, {
    // editorComponent: PlateStatic, // Optional: Defaults to PlateStatic
    props: { className: 'prose max-w-none' }, // Example: Pass props to the root div
  });

  return html;
}

// Example Usage:
// const mySlateValue = [ { type: 'h1', children: [{ text: 'My Document' }] } ];
// getDocumentAsHtml(mySlateValue).then(console.log);
```
For more details, see the [HTML Serialization guide](/docs/html).

## API Reference

### `<PlateStatic>` Props

```ts
import type React from 'react';
import type { Descendant } from 'slate';
import type { PlateEditor } from 'platejs/core'; // Adjust imports as per your setup

interface PlateStaticProps extends React.HTMLAttributes<HTMLDivElement> {
  /**
   * The Plate editor instance, created via `createSlateEditor`.
   * Must include plugins and components relevant to the content being rendered.
   */
  editor: PlateEditor;

  /**
   * Optional Plate `Value` (array of `Descendant` nodes).
   * If provided, this will be used for rendering instead of `editor.children`.
   */
  value?: Descendant[];

  /** Inline CSS styles for the root `div` element. */
  style?: React.CSSProperties;

  // Other HTMLDivElement attributes like `className`, `id`, etc., are also supported.
}
```

-   **`editor`**: An instance of `PlateEditor` created with `createSlateEditor`, including components configuration.
-   **`value`**: Optional. If provided, this array of `Descendant` nodes will be rendered, overriding the content currently in `editor.children`.

## Next Steps

-   Explore [HTML Serialization](/docs/html) for exporting content.
-   Learn about using Plate in [React Server Components](/docs/installation/rsc).
-   Refer to individual plugin documentation for their base (non-React) imports.

# Troubleshooting

Source: https://platejs.org/docs/troubleshooting

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Troubleshooting
description: Diagnose common Plate setup and runtime issues.
---

Most Plate issues come from version skew, duplicate React/Slate runtimes, or
crossing the server/client import boundary. Start with package alignment, then
check runtime ownership, then inspect plugin resolution with `DebugPlugin`.

## Start Here

| Symptom | First check |
| --- | --- |
| Invalid hook call, null dispatcher, or React hook crashes. | Duplicate `react` / `react-dom` or mixed package-manager installs. |
| Plugins render as plain text or components do not attach. | Missing plugin, wrong `/react` versus base import, or wrong component map. |
| Server Component crashes on import. | A Server Component imported `platejs/react` or `@platejs/*/react`. |
| `OPTION_UNDEFINED` in the console. | Code reads or writes an option that is not declared in the plugin. |
| `PLUGIN_DEPENDENCY_MISSING` in the console. | A plugin dependency key is not present in the editor plugin list. |
| Markdown, HTML, or static rendering misses nodes. | The static/base plugin kit does not include the serializer or node plugin. |

Use the focused guide when the issue belongs to one area:

| Area | Guide |
| --- | --- |
| Editor creation and options | [Editor](/docs/editor) |
| Plugin configuration | [Plugin](/docs/plugin) |
| Plugin option state | [Plugin Context](/docs/plugin-context) |
| Debug logging | [Debugging](/docs/debugging) |
| Server Components | [RSC](/docs/installation/rsc) |
| Static rendering | [Static Rendering](/docs/static) |

## Align Plate Packages

Keep `platejs` and every `@platejs/*` package on the same release family.
`depset` is the fastest way to update a project that already has several Plate
packages installed.

```bash
npx depset@latest @platejs --latest --install --yes
npx depset@latest platejs --latest --install --yes
```

For pnpm projects:

```bash
pnpm dlx depset@latest @platejs --latest --install --yes
pnpm dlx depset@latest platejs --latest --install --yes
```

Then inspect what actually resolved.

```bash
npm ls platejs @platejs/core @platejs/slate react react-dom slate slate-dom slate-react
```

```bash
pnpm why platejs
pnpm why @platejs/core
pnpm why @platejs/slate
pnpm why react react-dom slate slate-dom slate-react
```

If the tree shows multiple Plate majors, align the Plate packages first. If it
shows multiple React or Slate copies, fix the package that pulls the extra copy
instead of papering over the tree with a random override.

## Fix Runtime Boundaries

Use React entrypoints only in client-side editor code.

| Runtime | Import from |
| --- | --- |
| Editable React editor | `platejs/react`, `@platejs/*/react` |
| Server Component static output | `platejs/static`, `platejs`, `@platejs/*` |
| Node script or route handler without React UI | `platejs`, `@platejs/*` |

<Callout type="warning" title="No React plugins on the server">
  Server Components and Node scripts should not import `platejs/react` or
  `@platejs/*/react`. Use base plugins such as `BaseH1Plugin` from
  `@platejs/basic-nodes`, not `H1Plugin` from `@platejs/basic-nodes/react`.
</Callout>

If a server route only needs serialization or transforms, use the Node path from
[Node.js](/docs/installation/node). If it renders read-only React output, use
[Static Rendering](/docs/static).

## Check Component Wiring

When a node appears as plain text or a default `div`, check the component path.

```tsx title="components/editor/plugins.tsx" showLineNumbers
import { H1Plugin } from '@platejs/basic-nodes/react';

import { H1Element } from '@/components/ui/heading-node';

export const plugins = [H1Plugin.withComponent(H1Element)];
```

For copied Plate UI kits, inspect the kit that owns the feature before adding
manual component overrides. Feature kits usually wire plugins, components,
shortcuts, and options together.

| Component surface | Guide |
| --- | --- |
| Copied registry components | [Plate UI](/docs/installation/plate-ui) |
| Feature-owned kits | [Feature Kits](/docs/feature-kits) |
| Manual node components | [Plugin Components](/docs/plugin-components) |

## Inspect Plugin Resolution

Enable `DebugPlugin` when plugin options, dependencies, or runtime behavior do
not match what the editor receives.

```tsx title="components/editor/plugins.tsx" showLineNumbers
import { DebugPlugin } from 'platejs';

export const plugins = [
  DebugPlugin.configure({
    options: {
      logLevel: 'warn',
    },
  }),
];
```

Common debug errors:

| Message | Meaning |
| --- | --- |
| `OPTION_UNDEFINED` | `editor.getOption`, `editor.setOption`, or plugin context used an option key missing from `plugin.options`. |
| `PLUGIN_DEPENDENCY_MISSING` | A plugin lists a dependency key that is not registered. |

Use [Plugin](/docs/plugin#advanced-plugin-configuration) to check `dependencies`,
`priority`, `enabled`, `plugins`, and `override.*` behavior.

## Reset The Install

When the dependency tree looks correct but the runtime still behaves like two
React or Slate copies are loaded, reinstall from the existing lockfile.

```bash
rm -rf node_modules
npm install
```

```bash
rm -rf node_modules
pnpm install
```

Delete the lockfile only when you intentionally want a fresh dependency
resolution. That is a package-management decision, not a Plate fix.

## Report A Reproduction

When you open an issue, include the smallest editor that reproduces the problem:

- Package manager and lockfile type.
- Output from the relevant `npm ls` or `pnpm why` commands.
- The plugin list passed to `usePlateEditor`, `createPlateEditor`,
  `createSlateEditor`, or `createStaticEditor`.
- The failing value, if the issue depends on document content.
- The exact error message from `DebugPlugin` or the browser console.

Small reproductions beat screenshots. The package tree and plugin list usually
tell the story.


# TypeScript

Source: https://platejs.org/docs/typescript

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: TypeScript
description: Configure TypeScript (tsconfig) for using Plate, including module resolution solutions.
---

Plate provides ESM packages, which require certain TypeScript (and bundler) configurations to ensure compatibility, especially when importing subpath modules like `platejs/react`. Below are several solutions and workarounds to make TypeScript happy.

## Quick Summary

1. **Recommended (Easiest):** Use TypeScript **5.0+** and set `"moduleResolution": "bundler"` in your `tsconfig.json`.
2. **Alternate (Node resolution):** Keep `"moduleResolution": "node"` and map paths to `dist/react` (and potentially alias them in your bundler config).
3. **Up-to-date Packages:** Use `depset` to upgrade Plate dependencies.


## Recommended: `"moduleResolution": "bundler"`

The simplest approach for modern bundlers (Vite, Next.js 14, etc.) is to enable the new TypeScript "bundler" resolution mode. Example:

```jsonc
// tsconfig.json
{
  "compilerOptions": {
    // ...
    "module": "esnext",
    "moduleResolution": "bundler",
    // ...
  }
}
```

This aligns TypeScript's resolution logic more closely with modern bundlers and ESM packages. Below is a working excerpt from [Plate template](https://github.com/udecode/plate-template):

```jsonc
{
  "compilerOptions": {
    "strict": false,
    "strictNullChecks": true,
    "allowUnusedLabels": false,
    "allowUnreachableCode": false,
    "exactOptionalPropertyTypes": false,
    "noFallthroughCasesInSwitch": true,
    "noImplicitOverride": true,
    "noImplicitReturns": false,
    "noPropertyAccessFromIndexSignature": false,
    "noUncheckedIndexedAccess": false,
    "noUnusedLocals": false,
    "noUnusedParameters": false,

    "isolatedModules": true,

    "allowJs": true,
    "checkJs": false,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,

    "lib": ["dom", "dom.iterable", "esnext"],
    "jsx": "preserve",
    "module": "esnext",
    "target": "es2022",
    "moduleResolution": "bundler",
    "moduleDetection": "force",
    "resolveJsonModule": true,
    "noEmit": true,
    "incremental": true,
    "sourceMap": true,

    "baseUrl": "src",
    "paths": {
      "@/*": ["./*"]
    }
  },
  "include": [
    "next-env.d.ts",
    ".next/types/**/*.ts",
    "src/**/*.ts",
    "src/**/*.tsx"
  ],
  "exclude": ["node_modules"]
}
```

- **`"moduleResolution": "bundler"`** was introduced in TypeScript 5.0.
- If your TS version is older than 5.0, you **must** upgrade or stick to `"moduleResolution": "node"` plus manual path aliases.

```jsonc
// package.json
{
  "devDependencies": {
    "typescript": "^5.0.0"
  }
}
```

If you see an error like `TS5023: Unknown compiler option 'moduleResolution'` (for `bundler`), it likely means your TypeScript version is below 5.0.

## Workaround: `"moduleResolution": "node"` + Path Aliases

If upgrading your entire project to TS 5.0 or changing the resolution mode is not possible:

1. Keep `"moduleResolution": "node"`.
2. Map each Plate subpath import to its `dist/react` types in `tsconfig.json` using `paths`.
3. Alias these paths in your bundler config.

### Example `tsconfig.json`

```jsonc
{
  "compilerOptions": {
    "moduleResolution": "node",
    "paths": {
      "platejs/react": [
        "./node_modules/platejs/dist/react/index.d.ts"
      ],
      "@platejs/core/react": [
        "./node_modules/@platejs/core/dist/react/index.d.ts"
      ],
      "@platejs/list/react": [
        "./node_modules/@platejs/list/dist/react/index.d.ts"
      ]
      // ...repeat for all @platejs/*/react packages
    }
  }
}
```

### Example `vite.config.ts`

```ts
import { defineConfig } from 'vite';
import path from 'path';

export default defineConfig({
  resolve: {
    alias: {
      'platejs/react': path.resolve(
        __dirname,
        'node_modules/platejs/dist/react'
      ),
      '@platejs/core/react': path.resolve(
        __dirname,
        'node_modules/@platejs/core/dist/react'
      ),
      '@platejs/list/react': path.resolve(
        __dirname,
        'node_modules/@platejs/list/dist/react'
      ),

      // Non-/react base aliases:
      'platejs': path.resolve(
        __dirname,
        'node_modules/platejs'
      ),
      '@platejs/core': path.resolve(
        __dirname,
        'node_modules/@platejs/core'
      ),
      '@platejs/list': path.resolve(
        __dirname,
        'node_modules/@platejs/list'
      )
    }
  }
});
```

**Note:**
- You must do this for every `@platejs/*/react` import you use.  
- For testing/Jest, replicate these aliases via `moduleNameMapper` or similar.

## Ensure Matching Plate Versions

Say you're upgrading one package to `52.0.1`, double-check that all your `platejs*` packages are on the **latest version up to `52.0.1`** (one package could stay at `52.0.0` if it has no `52.0.1` release). Mixing versions often leads to mismatches.

To easily manage and synchronize your `platejs*` package versions, you can use the `depset` CLI. For example, to ensure all your `@platejs/*` scope packages are aligned to the latest compatible with version `52.x.y`:

```bash
npx depset@latest @platejs 52 && npx depset@latest platejs 52
```

Or, for a specific version like `52.0.1` (this will set all packages in the scope to `52.0.1` if available, or the latest before it if not):

```bash
npx depset@latest @platejs 52.0.1 && npx depset@latest platejs 52.0.1
```

This helps prevent version conflicts by ensuring all related Plate packages are on compatible versions.

## FAQ

> I updated `moduleResolution` to `bundler` but it broke my older imports."

If your codebase has older TS usage or relies on `node` resolution, try the path alias approach or fully migrate to a TS 5+ / ESM environment.

> "I'm seeing `TS2305` about missing exports. Is that a resolution error or a real missing export?"  

It can be either:
- If the entire package is "not found," it's likely a resolution issue.  
- If it's specifically "no exported member," double-check that you spelled the import correctly (no typos) and that your installed version actually has that export.

> "Which minimum TS version do I need for `moduleResolution: bundler`?"  

TypeScript 5.0 or higher.

> "We switched to bundler resolution, but some older libraries in our project break."  

If your older libraries aren't ESM-friendly, you might stick to `node` resolution and do manual path aliases. Some large codebases gradually upgrade or create separate build pipelines for legacy code.

> "We see the error in Jest but not in Vite."  

You'll need to replicate your alias/resolution changes for Jest. For example:

```js
// jest.config.js
module.exports = {
  // ...
  moduleNameMapper: {
    '^platejs/react$': '<rootDir>/node_modules/platejs/dist/react',
    '^@platejs/core/react$': '<rootDir>/node_modules/@platejs/core/dist/react',
    // ...
  }
};
```


# Unit Testing Plate

Source: https://platejs.org/docs/unit-testing

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Unit Testing Plate
description: Learn how to unit test Plate editor and plugins.
---

This guide outlines best practices for unit testing Plate plugins and components using `@platejs/test-utils`.

## Installation

```bash
npm install @platejs/test-utils
```

## Setting Up Tests

Add the JSX pragma at the top of your test file:

```typescript
/** @jsx jsx */

import { jsx } from '@platejs/test-utils';

jsx; // so Biome doesn't remove unused imports
```

This allows you to use JSX syntax for creating editor values.

## Creating Test Cases

### Editor State Representation

Use JSX to represent editor states:

```typescript
const input = (
  <editor>
    <hp>
      Hello<cursor /> world
    </hp>
  </editor>
) as any as PlateEditor;
```

Node elements like `<hp />`, `<hul />`, `<hli />` represent different types of nodes.

Special elements like `<cursor />`, `<anchor />`, and `<focus />` represent selection states.

### Testing Transforms

1. Create an input state
2. Define the expected output state
3. Use `createPlateEditor` to set up the editor
4. Apply the transform(s) directly
5. Assert the editor's new state

Example testing bold formatting:

```typescript
it('should apply bold formatting', () => {
  const input = (
    <editor>
      <hp>
        Hello <anchor />
        world
        <focus />
      </hp>
    </editor>
  ) as any as PlateEditor;

  const output = (
    <editor>
      <hp>
        Hello <htext bold>world</htext>
      </hp>
    </editor>
  ) as any as PlateEditor;

  const editor = createPlateEditor({
    plugins: [BoldPlugin],
    value: input.children,
    selection: input.selection,
  });

  // Apply transform directly
  editor.tf.toggleMark('bold');

  expect(editor.children).toEqual(output.children);
});
```

### Testing Selection

Test how operations affect the editor's selection:

```typescript
it('should collapse selection on backspace', () => {
  const input = (
    <editor>
      <hp>
        He<anchor />llo wor<focus />ld
      </hp>
    </editor>
  ) as any as PlateEditor;

  const output = (
    <editor>
      <hp>
        He<cursor />ld
      </hp>
    </editor>
  ) as any as PlateEditor;

  const editor = createPlateEditor({
    value: input.children,
    selection: input.selection,
  });

  editor.tf.deleteBackward();

  expect(editor.children).toEqual(output.children);
  expect(editor.selection).toEqual(output.selection);
});
```

## Testing Key Events

When you need to test keyboard handlers directly:

```typescript
it('should call the onKeyDown handler', () => {
  const input = (
    <editor>
      <hp>
        Hello <anchor />world<focus />
      </hp>
    </editor>
  ) as any as PlateEditor;

  // Create a mock handler to verify it's called
  const onKeyDownMock = jest.fn();

  const editor = createPlateEditor({
    value: input.children,
    selection: input.selection,
    plugins: [
      {
        key: 'test',
        handlers: {
          onKeyDown: onKeyDownMock,
        },
      },
    ],
  });

  // Create the keyboard event
  const event = new KeyboardEvent('keydown', {
    key: 'Enter',
  }) as any;

  // Call the handler directly
  editor.plugins.test.handlers.onKeyDown({
    ...getEditorPlugin(editor, { key: 'test' }),
    event,
  });

  // Verify the handler was called
  expect(onKeyDownMock).toHaveBeenCalled();
});
```

## Testing Complex Scenarios

For complex plugins like tables, test various scenarios by directly applying transforms:

```typescript
describe('Table plugin', () => {
  it('should insert a table', () => {
    const input = (
      <editor>
        <hp>
          Test<cursor />
        </hp>
      </editor>
    ) as any as PlateEditor;

    const output = (
      <editor>
        <hp>Test</hp>
        <htable>
          <htr>
            <htd>
              <hp>
                <cursor />
              </hp>
            </htd>
            <htd>
              <hp></hp>
            </htd>
          </htr>
          <htr>
            <htd>
              <hp></hp>
            </htd>
            <htd>
              <hp></hp>
            </htd>
          </htr>
        </htable>
      </editor>
    ) as any as PlateEditor;

    const editor = createPlateEditor({
      value: input.children,
      selection: input.selection,
      plugins: [TablePlugin],
    });

    // Call transform directly
    editor.tf.insertTable({ rows: 2, columns: 2 });

    expect(editor.children).toEqual(output.children);
    expect(editor.selection).toEqual(output.selection);
  });
});
```

## Testing Plugins with Options

Test how different plugin options affect behavior:

```typescript
describe('when keepSelectedTextOnPaste is disabled', () => {
  it('replaces the selected text with the pasted url', () => {
    const input = (
      <fragment>
        <hp>
          start <anchor />
          of regular text
          <focus />
        </hp>
      </fragment>
    ) as any;

    const output = (
      <fragment>
        <hp>
          start <ha url="https://google.com">https://google.com</ha>
          <htext />
        </hp>
      </fragment>
    ) as any;

    const editor = createPlateEditor({
      plugins: [
        LinkPlugin.configure({
          options: {
            keepSelectedTextOnPaste: false,
          },
        }),
      ],
      value: input,
    });

    editor.tf.insertData({
      getData: (type: string) => (type === 'text/plain' ? 'https://google.com' : ''),
    } as any);

    expect(input.children).toEqual(output.children);
  });
});
```

## Mocking vs. Real Transforms

While mocking can be useful for isolating specific behaviors, Plate tests often assess actual editor children and selection after transforms. This approach ensures that plugins work correctly with the entire editor state.


# Collaboration Demo

Source: https://platejs.org/docs/examples/collaboration-example

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Collaboration Demo
description: Real-time Plate collaboration example with Yjs providers and remote cursors.
---

This example shows a Plate editor bound to a shared Yjs document. It uses the
`collaboration-demo` registry example with `YjsPlugin`, Hocuspocus, WebRTC, room
state, connection controls, and remote cursor rendering.

## Demo

[collaboration-demo registry content](https://platejs.org/r/collaboration-demo)

## Source

The demo creates a room id in `localStorage`, gives each tab a random user name
and cursor color, then initializes Yjs after mount.

[collaboration-demo registry content](https://platejs.org/r/collaboration-demo)

## Runtime Shape

| Piece | Owner | Notes |
| --- | --- | --- |
| `YjsPlugin` | `@platejs/yjs/react` | Binds Plate to a shared `Y.Doc`, provider list, awareness data, and cursor data. |
| Hocuspocus provider | App infrastructure | The demo points to `ws://localhost:8888`; run your own server for durable collaboration. |
| WebRTC provider | `y-webrtc` | The demo uses `ws://localhost:4444` in dev and `wss://signaling.yjs.dev` in production. |
| Room state | Registry example | The room id is stored in `localStorage` and passed to every provider plus `yjs.init`. |
| Connection controls | Registry example | The status bar reads `_providers` and `_isConnected`, then calls `connect` or `disconnect`. |

Set `skipInitialization: true` on the editor. Yjs owns the initial document
load, and `editor.getApi(YjsPlugin).yjs.init()` seeds the value only when the
shared document is empty.

## Remote Cursors

The demo renders remote selections with the registry `remote-cursor-overlay`
component.

[remote-cursor-overlay registry content](https://platejs.org/r/remote-cursor-overlay)

`RemoteCursorOverlay` waits for `_isSynced`, reads cursor positions with
`useRemoteCursorOverlayPositions`, then paints selection rectangles and a named
caret.

## Try It

Open the same demo in two tabs and use the same room id. Each tab receives a
different random user name and cursor color, so typing and selections are easy
to distinguish.

## Related

- [Yjs](/docs/yjs) covers provider setup, lifecycle methods, and API reference.
- [Remote Cursor Overlay](/docs/components/remote-cursor-overlay) covers the reusable cursor UI component.


# Editable Voids

Source: https://platejs.org/docs/examples/editable-voids

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Editable Voids
description: Nest editable controls and a Plate editor inside a void element.
---

This example renders form controls and a nested Plate editor inside a void
element. It is app-local demo code built with `createPlatePlugin`, not a packaged
feature plugin.

## Demo

[editable-voids-demo registry content](https://platejs.org/r/editable-voids-demo)

## Source

The demo registers an `editable-void` element plugin and renders custom React UI
for that node.

[editable-voids-demo registry content](https://platejs.org/r/editable-voids-demo)

The initial value contains a normal paragraph, one `editable-void` element, and
an empty paragraph after it.

<ComponentSource src="examples/values/editable-voids-value.tsx" />

## Runtime Shape

| Piece | Owner | Notes |
| --- | --- | --- |
| `EditableVoidPlugin` | Registry example | Uses `createPlatePlugin` with `node.isElement: true` and `node.isVoid: true`. |
| `EditableVoidElement` | Registry example | Renders inputs, radio controls, and a nested `<Plate>` instance. |
| Outer editor | Registry example | Loads `EditorKit` plus `EditableVoidPlugin` and the `editableVoidsValue`. |
| Inner editor | Registry example | Creates a separate `usePlateEditor({ plugins: EditorKit })` inside the void element. |
| Value shape | Slate | Keeps an empty text child inside the void node so Slate can select it. |

## Void Element Rules

Set `contentEditable={false}` on the custom void wrapper. Without it, browser
editing behavior can leak into the nested controls; the demo notes Firefox input
issues specifically.

Render `{children}` after the non-editable UI. Slate still needs the hidden void
child mounted even when your visible element is fully custom React.

The nested editor is a separate Plate editor. It does not share the outer
editor's value, selection, plugins, or undo history.

## Related

- [Plate Plugin](/docs/api/core/plate-plugin) covers `node.isVoid`, `node.component`, and plugin rendering.
- [Plugin Components](/docs/plugin-components) covers custom node components.
- [Plate Components](/docs/api/core/plate-components) covers `<Plate>`, editor providers, and node primitives.


# Export

Source: https://platejs.org/docs/examples/export

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Export
description: Export a Plate document to HTML, PDF, image, Markdown, or Word.
docs:
  - route: https://pro.platejs.org/docs/examples/export
    title: Plus
---

This example exports the current Plate editor value from the browser. The
registry `export-toolbar-button` owns the client-side download menu for HTML,
PDF, image, Markdown, and Word output.

## Demo

[playground-demo registry content](https://platejs.org/r/playground-demo)

## Toolbar Source

Install the [Export Toolbar Button](/docs/components/export-toolbar-button)
component to add the menu to an editor toolbar.

[export-toolbar-button registry content](https://platejs.org/r/export-toolbar-button)

## Export Formats

| Format | Implementation | Output |
| --- | --- | --- |
| HTML | `serializeHtml` from `platejs/static` with `BaseEditorKit` and `EditorStatic` | `plate.html` |
| PDF | `html2canvas-pro` snapshot converted with `pdf-lib` | `plate.pdf` |
| Image | `html2canvas-pro` snapshot | `plate.png` |
| Markdown | `editor.getApi(MarkdownPlugin).markdown.serialize()` | `plate.md` |
| Word | `exportToDocx(editor.children, { editorPlugins })` from `@platejs/docx-io` | `plate.docx` |

The PDF and image exporters snapshot the current editable DOM. Use them for a
quick client-side download, not for paginated print layout.

## DOCX Static Kit

Word export passes the base static editor kit plus `DocxExportKit` so custom
nodes can render with DOCX-friendly components.

[docx-export-kit registry content](https://platejs.org/r/docx-export-kit)

`DocxExportKit` overrides code blocks, columns, equations, callouts, and table
of contents rendering for the DOCX conversion path.

## Plus Export

Plate Plus includes a server-side export flow for PDF output with page settings.

[export-pro registry content](https://platejs.org/r/export-pro)

## Related

- [DOCX Import/Export](/docs/docx-io) covers `@platejs/docx-io` options and plugin APIs.
- [Markdown](/docs/markdown) covers Markdown serialization.
- [Static Rendering](/docs/static) covers static editor rendering and HTML serialization.


# Huge Document

Source: https://platejs.org/docs/examples/huge-document

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Huge Document
---

[huge-document-demo registry content](https://platejs.org/r/huge-document-demo)


# Hundreds Editors

Source: https://platejs.org/docs/examples/hundreds-editors

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Hundreds Editors
description: Render many independent Plate editors on one page.
---

This example mounts 300 separate Plate editors in a single React tree. Each
editor gets its own id and value, so the page stresses editor creation, store
isolation, and repeated editable surfaces.

## Demo

[hundreds-editors-demo registry content](https://platejs.org/r/hundreds-editors-demo)

## Source

The demo maps generated values to `<WithPlate id={idx + 1} value={value} />`.

[hundreds-editors-demo registry content](https://platejs.org/r/hundreds-editors-demo)

## Value Generator

Each generated editor value contains one heading and two paragraphs.

<ComponentSource src="examples/values/multi-editors-value.tsx" />

## Runtime Shape

| Surface | Owner | Notes |
| --- | --- | --- |
| `createMultiEditorsValue()` | Registry example | Creates 300 editor values with JSX test-utils syntax. |
| `WithPlate` | Registry example | Calls `usePlateEditor({ id, value })` for each editor. |
| `<Plate>` | `platejs/react` | Creates one editor store provider per editor instance. |
| `<EditorContainer>` / `<Editor>` | Registry UI | Renders the shared editor shell for every instance. |

Use this demo to inspect many-editor mounting cost, store isolation, and focus
behavior. It is a browser stress page, not a production layout recommendation.

## Related

- [Plate Components](/docs/api/core/plate-components) covers `<Plate>` and editor store providers.
- [Plate Controller](/docs/api/core/plate-controller) covers cross-editor coordination.
- [Plate Store](/docs/api/core/plate-store) covers scoped editor store access.


# Preview Markdown

Source: https://platejs.org/docs/examples/preview-markdown

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Preview Markdown
description: Decorate text ranges so Markdown syntax previews inline.
---

This example previews Markdown syntax with Slate decorations. It does not
deserialize Markdown into Plate nodes; it keeps the text as text and styles
matching ranges with a custom leaf renderer.

## Demo

[preview-markdown-demo registry content](https://platejs.org/r/preview-markdown-demo)

## Source

The demo tokenizes each text node with Prism's Markdown grammar and returns
decoration ranges for token types such as title, bold, italic, blockquote, list,
horizontal rule, and code.

[preview-markdown-demo registry content](https://platejs.org/r/preview-markdown-demo)

## Initial Value

The value is plain Plate content whose paragraph text includes Markdown
characters.

<ComponentSource src="examples/values/preview-md-value.tsx" />

## Runtime Shape

| Surface | Owner | Notes |
| --- | --- | --- |
| `decoratePreview` | Registry example | Reads text nodes, tokenizes `node.text`, and returns Slate ranges with token-type flags. |
| `PreviewLeaf` | Registry example | Applies CSS classes when a decorated leaf has `bold`, `italic`, `title`, `list`, `hr`, `blockquote`, or `code`. |
| `preview-markdown` plugin | Registry example | Local `createSlatePlugin({ decorate })` plugin. |
| `BasicNodesKit` | Registry kit | Supplies the editor's normal paragraph and heading plugins. |
| `prismjs` | Dependency | Supplies the Markdown tokenizer used by the decoration function. |

Use this pattern when the editor should keep raw Markdown characters visible.
Use [Markdown](/docs/markdown) when the editor should convert Markdown text into
Plate nodes.

## Related

- [Markdown](/docs/markdown) covers Markdown deserialization and serialization.
- [Plate Plugin](/docs/api/core/plate-plugin) covers `decorate`.
- [Text](/docs/api/slate/text) covers text decorations and decorated leaves.


# Version History

Source: https://platejs.org/docs/examples/version-history

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Version History
description: Save Plate value snapshots and render a diff against the live editor.
---

This example stores immutable Plate value snapshots in local React state. It compares the selected revision with the current value through `@platejs/diff`.

## Demo

[version-history-demo registry content](https://platejs.org/r/version-history-demo)

## Source

[version-history-demo registry content](https://platejs.org/r/version-history-demo)

## Runtime Shape

| Piece | Owner | Role |
| --- | --- | --- |
| `createVersionSnapshot` | registry example | Clones each `Value` with `cloneDeep` before saving or diffing. |
| `revisions` | registry example | Stores the saved Plate values and feeds the revision picker. |
| `computeDiff` | `@platejs/diff` | Compares the selected revision and live value, then returns diff-marked nodes. |
| `DiffPlugin` | registry example | Renders diff leaves and wraps diff elements with insert, delete, or update styling. |
| `InlinePlugin` and `InlineVoidPlugin` | registry example | Keep inline and inline-void nodes in the demo value so the diff path covers mixed content. |
| `withGetFragmentExcludeDiff` | `@platejs/diff` | Removes `diff` and `diffOperation` metadata from copied fragments. |

## Snapshot Flow

1. The editor starts from `initialValue` and keeps the live value in local state.
2. `Save revision` clones the live value and appends it to `revisions`.
3. The select menu chooses one saved revision for comparison.
4. `computeDiff` receives the selected revision, current value, `editor.api.isInline`, and `lineBreakChar: '¶'`.
5. The read-only diff editor renders the returned value with the same inline plugins plus `DiffPlugin`.

## Product Preview

Potion uses the same document-history idea in a full app surface with stored versions, restore actions, and visual comparison.

[potion-iframe-demo registry content](https://platejs.org/r/potion-iframe-demo)

## Related

- [Controlled Value](/docs/controlled) for owning editor value from React state.
- [Plate Plugin](/docs/api/core/plate-plugin) for render hooks like `render.node` and `render.aboveNodes`.


# cn

Source: https://platejs.org/docs/api/cn

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: cn
description: API reference for @udecode/cn.
---

`@udecode/cn` provides class-name helpers and component wrappers for React UI primitives. The package also re-exports `@udecode/react-utils` from its root entry.

## Install

```bash
npm install @udecode/cn
```

## Quick Use

```tsx
import * as React from 'react';

import { cn, withCn, withProps, withVariants } from '@udecode/cn';

const active = true;
const className = cn('px-2', active && 'bg-accent', 'px-4');

const ButtonBase = React.forwardRef<
  HTMLButtonElement,
  React.ComponentProps<'button'>
>((props, ref) => <button ref={ref} {...props} />);

const Button = withCn(ButtonBase, 'inline-flex items-center rounded-md');

const PrimaryButton = withProps(Button, {
  type: 'button',
  className: 'bg-primary text-primary-foreground',
});
```

## Ownership

| Surface | Owner | What It Does |
|---------|-------|--------------|
| `cn` | `@udecode/cn` | Combines `class-variance-authority` `cx` with `tailwind-merge`. |
| `withCn` | `@udecode/cn` | Creates a component with a default merged `className`. |
| `withProps` | `@udecode/cn` | Creates a `forwardRef` component with default props. |
| `withVariants` | `@udecode/cn` | Creates a `forwardRef` component that computes classes from `cva` variants. |
| React utility exports | `@udecode/react-utils` | Re-exported from the `@udecode/cn` root entry. |

## Behavior

| Helper | Behavior |
|--------|----------|
| `cn(...inputs)` | Runs values through `cx`, then resolves Tailwind conflicts with `twMerge`. |
| `withCn(Component, ...inputs)` | Calls `withProps` with a default `className` created from `cn`. |
| `withProps(Component, defaultProps)` | Merges default props first and consumer props second. |
| `withProps` class names | Merges `defaultProps.className` and `props.className` with `cn`. |
| `withProps` refs | Returns `React.forwardRef`. |
| `withVariants(Component, variants, onlyVariantsProps?)` | Applies `variants(variantProps)` and merges the result with `className`. |
| `onlyVariantsProps` | Removes variant-only props from the rendered component props. |

## API Reference

### `cn`

Merge conditional class values and resolve Tailwind conflicts.

```tsx
cn('px-2', active && 'bg-accent', 'px-4');
```

<API name="cn">
<APIParameters>
  <APIItem name="...inputs" type="CxOptions">
    Values accepted by `class-variance-authority` `cx`.
  </APIItem>
</APIParameters>
<APIReturns type="string">
  The merged class name.
</APIReturns>
</API>

### `withCn`

Create a component with default classes.

```tsx
const Card = withCn('div', 'rounded-md border bg-card');
```

<API name="withCn">
<APIParameters>
  <APIItem name="Component" type="React.ComponentType">
    Component receiving the default class name.
  </APIItem>
  <APIItem name="...inputs" type="CxOptions">
    Default class values.
  </APIItem>
</APIParameters>
<APIReturns type="React.ForwardRefExoticComponent">
  A component that merges the default class name with consumer `className`.
</APIReturns>
</API>

### `withProps`

Create a component with default props. Consumer props override default props, except class names are merged.

```tsx
const SubmitButton = withProps('button', {
  type: 'submit',
  className: 'font-medium',
});
```

<API name="withProps">
<APIParameters>
  <APIItem name="Component" type="React.ElementType">
    Component receiving default props.
  </APIItem>
  <APIItem name="defaultProps" type="Partial<React.ComponentPropsWithoutRef<T>>">
    Props applied before consumer props.
  </APIItem>
</APIParameters>
<APIReturns type="React.ForwardRefExoticComponent">
  A `forwardRef` component with merged class names.
</APIReturns>
</API>

### `withVariants`

Create a component backed by `class-variance-authority` variants.

```tsx
import { cva } from 'class-variance-authority';

const buttonVariants = cva('inline-flex items-center', {
  variants: {
    size: {
      sm: 'h-8 px-2',
      md: 'h-9 px-3',
    },
  },
});

const Button = withVariants('button', buttonVariants, ['size']);
```

<API name="withVariants">
<APIParameters>
  <APIItem name="Component" type="React.ElementType">
    Component receiving variant classes.
  </APIItem>
  <APIItem name="variants" type="V extends ReturnType<typeof cva>">
    `cva` variant function.
  </APIItem>
  <APIItem name="onlyVariantsProps" type="(keyof VariantProps<V>)[]" optional>
    Variant props to remove before rendering the component.
  </APIItem>
</APIParameters>
<APIReturns type="React.ForwardRefExoticComponent">
  A `forwardRef` component with variant props and merged class names.
</APIReturns>
</API>


# Plate Core

Source: https://platejs.org/docs/api/core

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Plate Core
description: API reference for @platejs/core.
---

## API

### `createPlateEditor`

Generates a new instance of a `PlateEditor`, initialized with a set of plugins and their configurations.

<API name="createPlateEditor">
<APIOptions type="CreatePlateEditorOptions">
  <APIItem name="id" type="any" optional>
    Unique identifier for the editor.
  </APIItem>
  <APIItem name="editor" type="E" optional>
    Initial editor without `withPlate`.
  </APIItem>
  <APIItem name="plugins" type="P[]" optional>
    An array of editor plugins.
  </APIItem>
  <APIItem name="value" type="V | string | ((editor: PlateEditor) => V | Promise<V>)" optional>
    Initial value of the editor. Can be:
    - A static value array
    - An HTML string to be deserialized
    - A function that returns a value (can be async)
  </APIItem>
  <APIItem name="autoSelect" type="'end' | 'start' | boolean" optional>
    Select the editor after initialization.
    - **Default:** `false`
    - `true` | 'end': Select the end of the editor
    - `false`: Do not select anything
    - `'start'`: Select the start of the editor
  </APIItem>
  <APIItem name="onReady" type="(ctx: { editor: PlateEditor; isAsync: boolean; value: V }) => void" optional>
    Callback called when the editor initialization completes. The `isAsync` flag indicates whether the value was loaded asynchronously.
  </APIItem>
  <APIItem name="maxLength" type="number" optional>
    Specifies the maximum number of characters allowed in the editor.
  </APIItem>
  <APIItem name="navigationFeedback" type="object | boolean" optional>
    Configuration for the built-in navigation feedback plugin.
    <APISubList>
      <APISubListItem parent="navigationFeedback" name="duration" type="number" optional>
        Default flash duration in milliseconds.
        - **Default:** `1600`
      </APISubListItem>
    </APISubList>
  </APIItem>
  <APIItem name="nodeId" type="object | boolean" optional>
    Configuration for automatic node ID generation and management.
    <APISubList>
      <APISubListItem parent="nodeId" name="disableInsertOverrides" type="boolean" optional>
        Disable using existing IDs when inserting nodes.
        - When `false`: Keeps existing IDs if they don't exist in document
        - When `true`: Always generates new IDs
        - **Default:** `false`
      </APISubListItem>
      <APISubListItem parent="nodeId" name="filterInline" type="boolean" optional>
        Filter inline Element nodes from receiving IDs.
        - **Default:** `true`
      </APISubListItem>
      <APISubListItem parent="nodeId" name="filterText" type="boolean" optional>
        Filter Text nodes from receiving IDs.
        - **Default:** `true`
      </APISubListItem>
      <APISubListItem parent="nodeId" name="idCreator" type="() => any" optional>
        Function to generate unique IDs.
        - **Default:** `() => nanoid(10)`
      </APISubListItem>
      <APISubListItem parent="nodeId" name="idKey" type="string" optional>
        Property key used to store node IDs.
        - **Default:** `'id'`
      </APISubListItem>
      <APISubListItem parent="nodeId" name="initialValueIds" type="false | 'always' | 'if-needed'" optional>
        Controls how missing IDs are assigned in the initial value.
        - When `'if-needed'`: Only checks the first and last top-level nodes
        - When `'always'`: Walks the whole initial value and fills missing IDs
        - When `false`: Skips initial-value ID assignment
        - **Default:** `'if-needed'`
      </APISubListItem>
      <APISubListItem parent="nodeId" name="normalizeInitialValue" type="boolean | null" optional>
        Deprecated alias for `initialValueIds`.
        - When `false`: Same as `'if-needed'`
        - When `true`: Same as `'always'`
        - When `null`: Same as `false`
      </APISubListItem>
      <APISubListItem parent="nodeId" name="reuseId" type="boolean" optional>
        Reuse IDs on undo/redo and copy/paste.
        - When `true`: Keeps IDs if they don't exist in document
        - When `false`: Always generates new IDs (safer across documents)
        - **Default:** `false`
      </APISubListItem>
      <APISubListItem parent="nodeId" name="allow" type="string[]" optional>
        Node types that should receive IDs.
      </APISubListItem>
      <APISubListItem parent="nodeId" name="exclude" type="string[]" optional>
        Node types that should not receive IDs.
      </APISubListItem>
      <APISubListItem parent="nodeId" name="filter" type="(node: NodeEntry) => boolean" optional>
        Custom filter function for nodes that should receive IDs.
        - **Default:** `() => true`
      </APISubListItem>
    </APISubList>
  </APIItem>
  <APIItem name="chunking" type="object | boolean" optional>
    Configure Slate's chunking optimization, which reduces latency while typing. Set to `false` to disable. [Learn more about chunking.](https://docs.slatejs.org/walkthroughs/09-performance)
    <APISubList>
      <APISubListItem parent="chunking" name="chunkSize" type="number" optional>
        The number of blocks per chunk.
        - **Default:** 1000
      </APISubListItem>
      <APISubListItem parent="chunking" name="contentVisibilityAuto" type="boolean" optional>
        Whether to render each chunk as a DOM element with `content-visibility: auto`, which optimizes DOM painting. When set to `false`, no DOM element will be rendered for each chunk.
        - **Default:** `true`
      </APISubListItem>
      <APISubListItem parent="chunking" name="query" type="(ancestor: Ancestor) => boolean" optional>
        Determine which ancestors should have chunking applied to their children. Only blocks containing other blocks can have chunking applied.
        - **Default:** `NodeApi.isEditor`
      </APISubListItem>
    </APISubList>
  </APIItem>
  <APIItem name="selection" type="TSelection" optional>
    Initial selection for the editor.
  </APIItem>
  <APIItem name="shouldNormalizeEditor" type="boolean" optional>
    When `true`, it will normalize the initial `value` passed to the `editor`.
    - **Default:** `false`
  </APIItem>
  <APIItem name="rootPlugin" type="(plugin: AnyPlatePlugin) => AnyPlatePlugin" optional>
    Function to configure the root plugin.
  </APIItem>
  <APIItem name="api" type="object" optional>
    API methods for the editor.
  </APIItem>
  <APIItem name="decorate" type="function" optional>
    Decoration function for the editor.
  </APIItem>
  <APIItem name="extendEditor" type="function" optional>
    Function to extend the editor.
  </APIItem>
  <APIItem name="handlers" type="object" optional>
    Event handlers for the editor.
  </APIItem>
  <APIItem name="inject" type="object" optional>
    Injection configuration for the editor.
  </APIItem>
  <APIItem name="transformInitialValue" type="function" optional>
    Function to transform the initial value before the editor is ready.
  </APIItem>
  <APIItem name="normalizeInitialValue" type="function" optional>
    Deprecated alias for `transformInitialValue`. Legacy hooks may either
    mutate `value` in place or return the next value.
  </APIItem>
  <APIItem name="options" type="object" optional>
    Additional options for the editor.
  </APIItem>
  <APIItem name="override" type="object" optional>
    Override configuration for the editor.
  </APIItem>
  <APIItem name="priority" type="number" optional>
    Priority of the editor plugin.
  </APIItem>
  <APIItem name="readOnly" type="boolean" optional>
    Editor read-only initial state. For dynamic value, use
    `Plate.readOnly` prop.
  </APIItem>
  <APIItem name="render" type="object" optional>
    Render functions for the editor.
  </APIItem>
  <APIItem name="shortcuts" type="object" optional>
    Keyboard shortcuts for the editor.
  </APIItem>
  <APIItem name="transforms" type="object" optional>
    Transform functions for the editor.
  </APIItem>
  <APIItem name="useHooks" type="function" optional>
    Hook to use with the editor.
  </APIItem>
</APIOptions>

<APIReturns type="PlateEditor">
  An editor instance with plugins and config applied.
</APIReturns>
</API>

For more details on editor configuration, refer to the [Editor Configuration](/docs/editor) guide.

### `createPlatePlugin`

Creates a new Plate plugin with the given configuration, supporting extension, nested plugin manipulation, and runtime configuration.

<API name="createPlatePlugin">
<APIParameters>
  <APIItem name="config" type="PlatePluginConfig | ((editor: PlateEditor) => PlatePluginConfig)">
    The configuration object for the plugin, or a function that returns the configuration. If a function is provided, it will be executed when the plugin is resolved with the editor.

    For details on the `PlatePluginConfig` type, refer to the [PlatePlugin API](/docs/api/core/plate-plugin#plugin-properties).
  </APIItem>
</APIParameters>

<APIReturns type="PlatePlugin">
  A new plugin instance.
</APIReturns>
</API>

### `createTPlatePlugin`

Explicitly typed version of `createPlatePlugin`.

<API name="createTPlatePlugin">
<APIParameters>
  <APIItem name="config" type="TPlatePluginConfig<C> | ((editor: PlateEditor) => TPlatePluginConfig<C>)">
    The configuration object for the plugin, or a function that returns the configuration. This version requires an explicit type parameter `C` extending `AnyPluginConfig`.

    For details on the `TPlatePluginConfig` type, refer to the [PlatePlugin API](/docs/api/core/plate-plugin#plugin-properties).
  </APIItem>
</APIParameters>

<APIReturns type="PlatePlugin<C>">
  A new plugin instance.
</APIReturns>
</API>

### `toPlatePlugin`

Extends a SlatePlugin to create a React PlatePlugin.

<API name="toPlatePlugin">
<APIParameters>
  <APIItem name="basePlugin" type="SlatePlugin">
    The base SlatePlugin to be extended.
  </APIItem>
  <APIItem name="extendConfig" type="PlatePluginConfig | ((ctx: PlatePluginContext<C>) => PlatePluginConfig)" optional>
    A function or object that provides the extension configuration. If a function, it receives the plugin context and should return a partial PlatePlugin. If an object, it should be a partial PlatePlugin configuration.
  </APIItem>
</APIParameters>

<APIReturns type="PlatePlugin">
  A new plugin instance that combines the base SlatePlugin functionality with React-specific features defined in the extension configuration.
</APIReturns>
</API>

### `toTPlatePlugin`

Explicitly typed version of `toPlatePlugin`.

<API name="toTPlatePlugin">
<APIParameters>
  <APIItem name="basePlugin" type="SlatePlugin<TContext>">
    The base SlatePlugin to be extended.
  </APIItem>
  <APIItem name="extendConfig" type="ExtendPluginConfig<C> | ((ctx: PlatePluginContext<TContext>) => ExtendPluginConfig<C>)" optional>
    A function or object that provides the extension configuration. This version requires explicit type parameters for both the base plugin configuration (`TContext`) and the extension configuration (`C`).
  </APIItem>
</APIParameters>

<APIReturns type="PlatePlugin<C>">
  A new plugin instance with precise type control.
</APIReturns>
</API>

### `usePlateEditor`

Creates a memoized Plate editor for React components.

<API name="usePlateEditor">
<APIParameters>
  <APIItem name="options" type="CreatePlateEditorOptions & { enabled?: boolean; onReady?: (ctx: { editor: PlateEditor; isAsync: boolean; value: V }) => void }" optional>
    Configuration options for creating the Plate editor. All options from `createPlateEditor` are supported, plus:
    <APISubList>
      <APISubListItem parent="options" name="enabled" type="boolean" optional>
        Whether the editor should be created. When `false`, returns `null`.
        - **Default:** `true`
      </APISubListItem>
      <APISubListItem parent="options" name="onReady" type="(ctx: { editor: PlateEditor; isAsync: boolean; value: V }) => void" optional>
        Callback called when the editor initialization completes. The `isAsync` flag indicates whether the value was loaded asynchronously.
      </APISubListItem>
    </APISubList>
  </APIItem>
  <APIItem name="deps" type="React.DependencyList" optional>
    Additional dependencies for the useMemo hook.
    - **Default:** `[]`
  </APIItem>
</APIParameters>

<APIReturns type="PlateEditor | null">
  A memoized Plate editor instance. Returns `null` if `enabled` is `false`.
</APIReturns>
</API>

### `useEditorContainerRef`

<API name="useEditorContainerRef">
<APIReturns type="React.RefObject<HTMLDivElement>">
  The editor container DOM reference.
</APIReturns>
</API>

### `useEditorScrollRef`

<API name="useEditorScrollRef">
<APIReturns type="React.RefObject<HTMLDivElement>">
  The editor scroll container DOM reference.
</APIReturns>
</API>

### `useScrollRef`

<API name="useScrollRef">
<APIReturns type="React.RefObject<HTMLDivElement>">
The editor scroll container reference. Returns the scroll ref if it exists, otherwise returns the container ref.
</APIReturns>
</API>

### `useEditorPlugin`

Get editor and plugin context.

<API name="useEditorPlugin">
<APIParameters>
  <APIItem name="p" type="WithRequiredKey<P>">
    The plugin or plugin configuration with a required key.
  </APIItem>
</APIParameters>

<APIReturns type="PlatePluginContext">
  <APIItem name="editor" type="PlateEditor">
      The current editor instance.
  </APIItem>
  <APIItem name="plugin" type="PlatePlugin">
      The plugin instance.
  </APIItem>
  <APIItem name="getOption" type="function">
      Function to get a specific option value.
  </APIItem>
  <APIItem name="getOptions" type="function">
      Function to get all options for the plugin.
  </APIItem>
  <APIItem name="setOption" type="function">
      Function to set a specific option value.
  </APIItem>
  <APIItem name="setOptions" type="function">
      Function to set multiple options.
  </APIItem>
  <APIItem name="store" type="PlateStore">
      The Plate store for the editor.
  </APIItem>
</APIReturns>
</API>

### `useEditorRef`

Get the Plate editor reference without re-rendering. The returned editor object is enhanced with a `store` property that provides access to the Plate store.

<API name="useEditorRef">
<APIParameters>
  <APIItem name="id" type="string" optional>
    Editor ID used for accessing nested editors. When not provided, returns the closest editor instance in the React tree. Only use this parameter when working with nested editors to target a specific scope.
  </APIItem>
</APIParameters>

<APIReturns type="PlateEditor & { store: PlateStore }">
  The editor reference with attached store.
</APIReturns>
</API>

### `useEditorSelector`

Subscribe to a specific property of the editor.

<API name="useEditorSelector">
<APIParameters>
  <APIItem name="selector" type="(editor: PlateEditor<V>, prev?: T) => T">
    The selector function.
  </APIItem>
  <APIItem name="deps" type="DependencyList">
    The dependency list for the selector function.
  </APIItem>
  <APIItem name="options" type="UseEditorSelectorOptions<T>" optional>
    Options for the selector function.
  </APIItem>
</APIParameters>

<APIOptions>
  <APIItem name="id" type="string" optional>
    The ID of the plate editor. Useful only when nesting editors. Default is using the closest editor id.
  </APIItem>
  <APIItem name="equalityFn" type="(a: T, b: T) => boolean" optional>
    Equality function to determine whether the result of the selector function has changed. Default is `(a, b) => a === b`.
  </APIItem>
</APIOptions>

<APIReturns type="T">
  The return value of the selector function.
</APIReturns>
</API>

### `useEditorState`

Get the Plate editor reference with re-rendering.

<API name="useEditorState">
<APIParameters>
  <APIItem name="id" type="string" optional>
    The ID of the plate editor. Default is using the closest editor id.
  </APIItem>
</APIParameters>

<APIReturns type="PlateEditor">
  The editor reference.
</APIReturns>
</API>

### `useEditorComposing`

Get the editor's `composing` state.

<API name="useEditorComposing">
<APIParameters>
  <APIItem name="id" type="string" optional>
    The ID of the plate editor.
  </APIItem>
</APIParameters>
<APIReturns type="boolean">
  Whether the editor is composing.
</APIReturns>
</API>

### `useEditorReadOnly`

Get the editor's `readOnly` state.
<API name="useEditorReadOnly">
<APIParameters>
  <APIItem name="id" type="string" optional>
    The ID of the plate editor.
  </APIItem>
</APIParameters>
<APIReturns type="boolean">
  Whether the editor is read-only.
</APIReturns>
</API>

### `useEditorMounted`

Get the editor's `isMounted` state.

<API name="useEditorMounted">
<APIParameters>
  <APIItem name="id" type="string" optional>
    The ID of the plate editor.
  </APIItem>
</APIParameters>
<APIReturns type="boolean">
  Whether the editor is mounted.
</APIReturns>
</API>

### `useEditorSelection`

Get the editor's selection. Memoized so it does not re-render if the range is the same.

<API name="useEditorSelection">
<APIParameters>
  <APIItem name="id" type="string" optional>
    The ID of the plate editor.
  </APIItem>
</APIParameters>
<APIReturns type="TRange | null">
The current selection in the editor.
</APIReturns>
</API>

### `useEditorVersion`

Get the version of the editor value. That version is incremented on each editor change.

<API name="useEditorVersion">
<APIParameters>
  <APIItem name="id" type="string" optional>
    The ID of the plate editor.
  </APIItem>
</APIParameters>
<APIReturns type="number">
The current version of the editor value.
</APIReturns>
</API>  

### `useSelectionVersion`

Get the version of the editor selection. That version is incremented on each selection change (the range being different).

<API name="useSelectionVersion">
<APIParameters>
  <APIItem name="id" type="string" optional>
    The ID of the plate editor.
  </APIItem>
</APIParameters>
<APIReturns type="number">
The current version of the editor selection.
</APIReturns>
</API>

### `useSelectionCollapsed`

<API name="useSelectionCollapsed">
<APIReturns type="boolean">
Whether the current selection is collapsed.
</APIReturns>
</API>

### `useSelectionExpanded`

<API name="useSelectionExpanded">
<APIReturns type="boolean">
Whether the current selection is expanded.
</APIReturns>
</API>

### `useSelectionWithinBlock`

<API name="useSelectionWithinBlock">
<APIReturns type="boolean">
Whether the current selection is within a single block.
</APIReturns>
</API>

### `useSelectionAcrossBlocks`

<API name="useSelectionAcrossBlocks">
<APIReturns type="boolean">
Whether the current selection spans across multiple blocks.
</APIReturns>
</API>

### `useSelectionFragment`

Returns the fragment of the current selection, optionally unwrapping structural nodes.

<API name="useSelectionFragment">
<APIReturns type="TElement[]">
  The fragment of the current selection. Returns an empty array if the selection is not expanded or if no fragment is found.
</APIReturns>
</API>

### `useSelectionFragmentProp`

Returns a prop value derived from the current selection fragment.
    
<API name="useSelectionFragmentProp">
<APIOptions type="GetSelectionFragmentOptions & GetFragmentPropOptions" optional>
<APIItem name="key" type="string" optional>
The key of the property to extract from each node.
</APIItem>
<APIItem name="defaultValue" type="string" optional>
The default value to return if no valid prop is found.
</APIItem>
<APIItem name="getProp" type="(node: TElement | TText) => any" optional>
Custom function to extract the prop value from a node.
</APIItem>
<APIItem name="mode" type="'all' | 'block' | 'text'" optional>
Determines how to traverse the fragment:
- 'all': Check both block and text nodes
- 'block': Only check block nodes
- 'text': Only check text nodes
  
- **Default**: `'block'`
</APIItem>
</APIOptions>

<APIReturns>
A value derived from the fragment nodes, or undefined if no consistent value is found across the specified nodes.
</APIReturns>
</API>

### `useNodePath`

Returns the path of a node in the editor.

<API name="useNodePath">
<APIParameters>
  <APIItem name="node" type="TNode">
    The node to find the path for.
  </APIItem>
</APIParameters>

<APIReturns>
  A memoized Path array representing the location of the node in the editor's tree structure.
</APIReturns>
</API>

### `usePath`

Get the memoized path of the closest element.

<API name="usePath">
<APIParameters>
  <APIItem name="pluginKey" type="string" optional>
    The key of the plugin to get the path for.
  </APIItem>
</APIParameters>

<APIReturns>
  The path of the element, or `undefined` if used outside of a node component's context.
</APIReturns>
</API>  

### `usePluginOption`

Hook to access plugin options from the plugin store. For usage inside `<Plate>`.

<API name="usePluginOption">
<APIParameters>
  <APIItem name="plugin" type="PlatePlugin">
    The plugin to get options from.
  </APIItem>
  <APIItem name="key" type="keyof (InferOptions<C> | InferSelectors<C>) | 'state'">
    The key of the option or selector to access.
  </APIItem>
  <APIItem name="...args" type="any[]" optional>
    Additional arguments:
    - For selectors: The selector parameters
    - Last argument can be an equality function `(a: T, b: T) => boolean`
  </APIItem>
</APIParameters>

<APIReturns type="T">
  The value of the option or selector result:
  - For 'state': Returns the entire state object
  - For selector keys: Returns the selector's return value
  - For option keys: Returns the option value
</APIReturns>

```tsx
// Access a simple option
const value = usePluginOption(plugin, 'value');
// Access a selector with parameters
const doubleValue = usePluginOption(plugin, 'doubleValue', 2);
// Access with equality function
const value = usePluginOption(plugin, 'value', (a, b) => a === b);
// Access entire state
const state = usePluginOption(plugin, 'state');
```

</API>

### `useEditorPluginOption`

Hook to access plugin options from the plugin store. For usage outside `<Plate>`.

<API name="useEditorPluginOption">
<APIParameters>
  <APIItem name="editor" type="PlateEditor">
    The editor instance.
  </APIItem>
  <APIItem name="plugin" type="PlatePlugin">
    The plugin to get options from.
  </APIItem>
  <APIItem name="key" type="keyof (InferOptions<C> | InferSelectors<C>) | 'state'">
    The key of the option or selector to access.
  </APIItem>
  <APIItem name="...args" type="any[]" optional>
    Additional arguments:
    - For selectors: The selector parameters
    - Last argument can be an equality function `(a: T, b: T) => boolean`
  </APIItem>
</APIParameters>

<APIReturns type="T">
  The value of the option or selector result:
  - For 'state': Returns the entire state object
  - For selector keys: Returns the selector's return value
  - For option keys: Returns the option value
</APIReturns>

```tsx
// Access a simple option
const value = useEditorPluginOption(editor, plugin, 'value');
// Access a selector with parameters
const doubleValue = useEditorPluginOption(editor, plugin, 'doubleValue', 2);
// Access with equality function
const value = useEditorPluginOption(editor, plugin, 'value', (a, b) => a === b);
// Access entire state
const state = useEditorPluginOption(editor, plugin, 'state');
```
</API>


### `useElement`

Get the element by plugin key.

<API name="useElement">
<APIParameters>
  <APIItem name="pluginKey" type="string" optional>
    The key of the plugin to get the element for.
    - **Default:** `'element'`
  </APIItem>
</APIParameters>

<APIReturns>
  The element of type `T extends TElement`, or an empty object if used outside of a node component's context.
</APIReturns>
</API>

## Core plugins

### `DebugPlugin`
Provides debugging capabilities with configurable log levels and error handling. 

See [Debugging](/docs/debugging) for more details.

### `SlateExtensionPlugin & SlateReactExtensionPlugin`
Extend core apis and improve default functionality.

`SlateExtensionPlugin` exposes `editor.api.isElementStateEmpty(element)`. It
checks the element's own props, not its text content. By default, only `type`
and props claimed by plugins through `node.isMetadataProp` are ignored; any other
prop means the element carries state. `NodeIdPlugin` uses `node.isMetadataProp` for
the configured NodeId key.

```tsx
editor.api.isElementStateEmpty({
  children: [{ text: '' }],
  type: 'p',
}); // true

editor.api.isElementStateEmpty({
  children: [{ text: '' }],
  listStyleType: 'disc',
  type: 'p',
}); // false

const CustomMetadataPlugin = createSlatePlugin({
  key: 'customMetadata',
  node: {
    isMetadataProp: ({ key }) => key === 'customId',
  },
});
```

### `DOMPlugin & ReactPlugin`
Integrates React-specific functionality into the editor.

### `HistoryPlugin`
Enables undo and redo functionality for the editor.

### `InlineVoidPlugin`
Manages inline and void elements in the editor.

### `ParserPlugin`
Handles parsing of content for the editor.

### `LengthPlugin`
Enforces a maximum length for the editor content.

### `HtmlPlugin`
Enables HTML serialization and deserialization.

### `AstPlugin`
Handles Abstract Syntax Tree (AST) operations for the editor.

### `ParagraphPlugin`
Provides paragraph formatting functionality.

### `EventEditorPlugin`
Manages editor events such as focus and blur.

## Utils

### `isType`

Checks whether a node matches the provided type.

<API name="isType">
<APIParameters>
  <APIItem name="editor" type="PlateEditor<V>">
    The editor in which the node is present.
  </APIItem>
  <APIItem name="node" type="any">
    The node to be checked.
  </APIItem>
  <APIItem name="key" type="string | string[]" optional>
    The type or types to match the node against. Can be a string or an array of
    strings.
  </APIItem>
</APIParameters>
<APIReturns>
  A boolean indicating whether the node's type matches the provided type or
  types.
</APIReturns>
</API>

## Components

### `<PlateElement>`

Generic component for rendering an element.

<API name="PlateElement">
<APIProps>
  <APIItem name="className" type="string" optional>
    The CSS class to apply to the component.
  </APIItem>
  <APIItem name="editor" type="E">
    The editor instance. Also available using `useEditorRef` hook.
  </APIItem>
  <APIItem name="element" type="TElement">
    The element node. Also available using `useElement` hook.
  </APIItem>
  <APIItem name="path" type="Path">
    The path of the element in the editor tree. Also available using `usePath` hook.
  </APIItem>
  <APIItem name="attributes" type="HTMLAttributes<HTMLElement>">
    Attributes of the element to be spread on the top-level element.
    <APISubList>
      <APISubListItem parent="attributes" name="data-slate-node" type="'element'">
        Always set to `'element'`.
      </APISubListItem>
      <APISubListItem parent="attributes" name="data-slate-inline" type="boolean" optional />
      <APISubListItem parent="attributes" name="data-slate-void" type="boolean" optional />
      <APISubListItem parent="attributes" name="dir" type="string" optional />
      <APISubListItem parent="attributes" name="ref" type="any">
        The reference to the element. If using your own reference, merge it with this one.
      </APISubListItem>
    </APISubList>
  </APIItem>
  <APIItem name="children" type="any">
    Necessary for rendering the node children.
  </APIItem>
  <APIItem name="as" type="React.ElementType" optional>
    The component type to render as.
    - **Default:** `'div'`
  </APIItem>
</APIProps>
</API>

### `<PlateLeaf>`

Generic component for rendering a leaf.

<API name="PlateLeaf">
<APIProps>
  <APIItem name="className" type="string" optional>
    The CSS class to apply to the component.
  </APIItem>
  <APIItem name="editor" type="E">
    The editor context.
  </APIItem>
  <APIItem name="children" type="any">
    Necessary for rendering the node children.
  </APIItem>
  <APIItem name="leaf" type="TText">
    The leaf node.
  </APIItem>
  <APIItem name="text" type="TText">
    The text node.
  </APIItem>
  <APIItem name="attributes" type="HTMLAttributes<HTMLElement>">
    Attributes of the leaf to be spread on the top-level element.
    <APISubList>
      <APISubListItem parent="attributes" name="data-slate-leaf" type="true">
        Always set to `true`.
      </APISubListItem>
    </APISubList>
  </APIItem>
  <APIItem name="as" type="React.ElementType" optional>
    The component type to render as.
    - **Default:** `'span'`
  </APIItem>
</APIProps>
</API>

### `<PlateText>`

Generic component for rendering text.

<API name="PlateText">
<APIProps>
  <APIItem name="className" type="string" optional>
    The CSS class to apply to the component.
  </APIItem>
  <APIItem name="text" type="TText">
    The text node.
  </APIItem>
  <APIItem name="attributes" type="HTMLAttributes<HTMLElement>">
    Attributes of the text to be spread on the top-level element.
  </APIItem>
  <APIItem name="children" type="any">
    Necessary for rendering the node children.
  </APIItem>
  <APIItem name="as" type="React.ElementType" optional>
    The component type to render as.
    - **Default:** `'span'`
  </APIItem>
</APIProps>
</API>


# Floating

Source: https://platejs.org/docs/api/floating

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Floating
description: API reference for @platejs/floating.
---

`@platejs/floating` contains the React hooks and rectangle utilities used by floating toolbars, cursor-anchored UI, and virtual elements in Plate. It wraps Floating UI and exports the Floating UI primitives Plate components use.

## Installation

```bash
npm install @platejs/floating
```

## Ownership

| Surface | Owner | Use |
| --- | --- | --- |
| `useVirtualFloating` | `@platejs/floating` | `useFloating` with a controlled virtual reference element. |
| `useFloatingToolbarState` | `@platejs/floating` | Builds toolbar state from editor focus, selection, read-only state, and Floating UI options. |
| `useFloatingToolbar` | `@platejs/floating` | Turns toolbar state into DOM props, ref, outside-click ref, and hidden state. |
| Rect utilities | `@platejs/floating` | Convert editor ranges, DOM selection, and client rect arrays into Floating UI-compatible rects. |
| Floating UI exports | `@platejs/floating` | Re-exported middleware and hooks from `@floating-ui/react`. |

## Virtual Floating

`useVirtualFloating` creates a Floating UI virtual reference. Use it when the floating element follows a selection, cursor, or computed rectangle instead of a real DOM reference element.

```tsx title="Virtual floating element"
import {
  flip,
  getDefaultBoundingClientRect,
  offset,
  useVirtualFloating,
} from '@platejs/floating';

export function SelectionPopover({
  open,
  rect,
}: {
  open: boolean;
  rect?: DOMRect;
}) {
  const floating = useVirtualFloating({
    getBoundingClientRect: () => rect ?? getDefaultBoundingClientRect(),
    middleware: [offset(8), flip()],
    open,
    placement: 'top',
  });

  return (
    <div ref={floating.refs.setFloating} style={floating.style}>
      Selection actions
    </div>
  );
}
```

<API name="useVirtualFloating">
<APIOptions type="UseVirtualFloatingOptions">
  <APIItem name="getBoundingClientRect" type="() => ClientRectObject" optional>
    Supplies the virtual element rect. Defaults to `getDefaultBoundingClientRect`.
  </APIItem>
  <APIItem name="open" type="boolean" optional>
    When `false`, the returned style sets `display: 'none'`.
  </APIItem>
  <APIItem name="whileElementsMounted" type="UseFloatingOptions['whileElementsMounted']" optional>
    Defaults to Floating UI `autoUpdate`.
  </APIItem>
  <APIItem name="...floatingOptions" type="Partial<UseFloatingOptions>" optional>
    Forwarded to Floating UI `useFloating`.
  </APIItem>
</APIOptions>
<APIReturns type="UseVirtualFloatingReturn">
  <APIItem name="style" type="React.CSSProperties">
    Absolute/fixed position style: `position`, `left`, `top`, `display`, and `visibility`.
  </APIItem>
  <APIItem name="virtualElementRef" type="React.MutableRefObject<VirtualElement>">
    Mutable virtual reference element. The hook updates its `getBoundingClientRect`.
  </APIItem>
  <APIItem name="refs" type="UseFloatingReturn['refs']">
    Floating UI refs. Attach `refs.setFloating` to the floating element.
  </APIItem>
  <APIItem name="update" type="UseFloatingReturn['update']">
    Floating UI manual position update.
  </APIItem>
</APIReturns>
</API>

## Floating Toolbar

Floating toolbar setup is split into two hooks. Build state first, then pass that state to `useFloatingToolbar`.

```tsx title="Floating toolbar state"
import {
  flip,
  offset,
  useFloatingToolbar,
  useFloatingToolbarState,
} from '@platejs/floating';
import { useEditorId, useEventEditorValue } from 'platejs/react';

export function ToolbarShell() {
  const editorId = useEditorId();
  const focusedEditorId = useEventEditorValue('focus');

  const state = useFloatingToolbarState({
    editorId,
    focusedEditorId,
    floatingOptions: {
      middleware: [offset(12), flip({ padding: 12 })],
      placement: 'top',
    },
  });

  const { clickOutsideRef, hidden, props, ref } = useFloatingToolbar(state);

  if (hidden) return null;

  return (
    <div ref={clickOutsideRef}>
      <div ref={ref} {...props}>
        Toolbar
      </div>
    </div>
  );
}
```

<API name="useFloatingToolbarState">
<APIOptions type="FloatingToolbarState & { editorId: string; focusedEditorId: string | null }">
  <APIItem name="editorId" type="string" required>
    Current editor id.
  </APIItem>
  <APIItem name="focusedEditorId" type="string | null" required>
    Focused editor id from `useEventEditorValue('focus')`.
  </APIItem>
  <APIItem name="floatingOptions" type="UseVirtualFloatingOptions" optional>
    Options passed to `useVirtualFloating`.
  </APIItem>
  <APIItem name="hideToolbar" type="boolean" optional>
    Force the toolbar closed.
  </APIItem>
  <APIItem name="showWhenReadOnly" type="boolean" optional>
    Allow the toolbar to show when the editor is read-only.
  </APIItem>
</APIOptions>
<APIReturns type="ReturnType<typeof useFloatingToolbarState>">
  Internal toolbar state for `useFloatingToolbar`.
</APIReturns>
</API>

<API name="useFloatingToolbar">
<APIOptions type="ReturnType<typeof useFloatingToolbarState>">
  <APIItem name="state" type="ReturnType<typeof useFloatingToolbarState>" required>
    State returned by `useFloatingToolbarState`.
  </APIItem>
</APIOptions>
<APIReturns type="object">
  <APIItem name="clickOutsideRef" type="React.RefObject<HTMLElement>">
    Ref from `useOnClickOutside`. It closes the toolbar and ignores `.ignore-click-outside/toolbar`.
  </APIItem>
  <APIItem name="hidden" type="boolean">
    `true` when the toolbar should not render.
  </APIItem>
  <APIItem name="props" type="{ style: React.CSSProperties }">
    Props to spread on the toolbar root.
  </APIItem>
  <APIItem name="ref" type="UseFloatingReturn['refs']['setFloating']">
    Floating element ref callback.
  </APIItem>
</APIReturns>
</API>

The toolbar opens only for an expanded selection with text. It stays hidden while the mouse is down, when `hideToolbar` is true, when a different editor owns focus, or when the editor is read-only and `showWhenReadOnly` is not set.

## Rectangle Utilities

These helpers normalize editor locations and DOM ranges into rectangles.

<API name="Rectangle utilities">
<APIMethods>
  <APIItem name="getDefaultBoundingClientRect" type="() => ClientRectObject">
    Returns a zero-size offscreen rect used as a safe Floating UI fallback.
  </APIItem>
  <APIItem name="createVirtualElement" type="() => VirtualElement">
    Creates a Floating UI virtual element with `getDefaultBoundingClientRect`.
  </APIItem>
  <APIItem name="createVirtualRef" type="(editor: Editor, at?: TLocation | TLocation[], options?: { fallbackRect?: ClientRect }) => VirtualRef">
    Creates a ref-like object whose `current.getBoundingClientRect()` reads editor locations. It throws when no rect exists and no `fallbackRect` is provided.
  </APIItem>
  <APIItem name="getBoundingClientRect" type="(editor: Editor, at?: TLocation | TLocation[]) => DOMRect | undefined">
    Reads one or more editor locations, converts them to DOM ranges, and returns the merged bounding rect. If `at` is omitted, it uses `editor.selection`.
  </APIItem>
  <APIItem name="getRangeBoundingClientRect" type="(editor: Editor, at: TRange | null) => ClientRectObject">
    Returns the DOM rect for a range, or `getDefaultBoundingClientRect()` when the range or DOM range is missing.
  </APIItem>
  <APIItem name="getSelectionBoundingClientRect" type="(editor: PlateEditor) => ClientRectObject">
    Returns the selection rect only when the editor selection is expanded. Collapsed selections return the default rect.
  </APIItem>
  <APIItem name="getDOMSelectionBoundingClientRect" type="() => ClientRectObject">
    Returns `window.getSelection().getRangeAt(0).getBoundingClientRect()`, or the default rect when no DOM selection exists.
  </APIItem>
  <APIItem name="makeClientRect" type="(rect: { bottom: number; left: number; right: number; top: number }) => DOMRect">
    Creates a DOMRect-like object and computes `width`, `height`, `x`, and `y`.
  </APIItem>
  <APIItem name="mergeClientRects" type="(clientRects: DOMRect[]) => DOMRect">
    Merges client rects by min left/top and max right/bottom. It throws when the array is empty.
  </APIItem>
</APIMethods>
</API>

## Floating UI Re-exports

`@platejs/floating` re-exports the Floating UI middleware and React hooks used by Plate UI, including `autoUpdate`, `flip`, `hide`, `inline`, `offset`, `shift`, `size`, `useFloating`, `useInteractions`, `useClick`, `useDismiss`, `FloatingPortal`, and related types.

Use those exports when a Plate UI component already imports from `@platejs/floating`; use `@floating-ui/react` directly only when the component is not coupled to Plate.

## Related Components

- [Toolbar](/docs/toolbar) covers the registry floating-toolbar component that consumes these hooks.
- [Plate Store](/docs/api/core/plate-store) covers `useEditorId` and `useEventEditorValue`.


# Plate

Source: https://platejs.org/docs/api/plate

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Plate
description: API reference for the platejs package.
---

`platejs` is the umbrella package for Plate's base, React, and static APIs. It re-exports the core runtime, Slate runtime, utilities, React helpers, and static renderer through three public subpaths.

## Installation

```bash
npm install platejs
```

`platejs` has React peer dependencies because the package also owns `platejs/react`.

## Import Paths

| Import | Re-exports | Use |
| --- | --- | --- |
| `platejs` | `@platejs/core`, `@platejs/slate`, `@platejs/utils`, `@udecode/utils` | Headless editor creation, Slate APIs, core types, and shared utilities. |
| `platejs/react` | `@platejs/core/react`, `@platejs/utils/react`, `@udecode/react-hotkeys`, `@udecode/react-utils` | React editors, components, hooks, stores, plugins, and React utility hooks. |
| `platejs/static` | `@platejs/core/static` | Static editor creation, static rendering, HTML serialization, and static node renderers. |

Use the umbrella imports in application code. Package code can import direct package surfaces such as `@platejs/core/react` when it needs a tighter dependency boundary.

## Base Runtime

Use `platejs` for non-React editor work and shared types.

```ts title="lib/create-headless-editor.ts"
import { createSlateEditor } from 'platejs';

export const editor = createSlateEditor({
  value: [
    {
      type: 'p',
      children: [{ text: 'Headless editor.' }],
    },
  ],
});
```

## React Runtime

Use `platejs/react` for app editors.

```tsx title="components/basic-editor.tsx"
import { Plate, PlateContent, usePlateEditor } from 'platejs/react';

export function BasicEditor() {
  const editor = usePlateEditor({
    value: [
      {
        type: 'p',
        children: [{ text: 'React editor.' }],
      },
    ],
  });

  return (
    <Plate editor={editor}>
      <PlateContent />
    </Plate>
  );
}
```

## Static Runtime

Use `platejs/static` for rendering or serialization paths that do not mount an editable React editor.

```tsx title="lib/create-static-editor.ts"
import { createStaticEditor } from 'platejs/static';

export const staticEditor = createStaticEditor({
  value: [
    {
      type: 'p',
      children: [{ text: 'Static editor.' }],
    },
  ],
});
```

## API Pages

| Page | Covers |
| --- | --- |
| [Plate Core](/docs/api/core) | Editor creation, React runtime, plugins, stores, and render primitives. |
| [Slate](/docs/api/slate) | Slate-compatible editor API, transforms, nodes, locations, operations, and refs. |
| [Plate Utils](/docs/api/utils) | Shared non-React utilities. |
| [React Utils](/docs/api/react-utils) | React utility hooks and helpers re-exported through `platejs/react`. |
| [Plate Components](/docs/api/core/plate-components) | `Plate`, `PlateContent`, `PlateView`, and component primitives. |
| [Plate Editor](/docs/api/core/plate-editor) | Runtime editor type, core APIs, transforms, DOM state, and metadata. |


# React Utils

Source: https://platejs.org/docs/api/react-utils

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: React Utils
description: API reference for @udecode/react-utils.
---

`@udecode/react-utils` provides small React primitives used across Plate UI packages. It is also re-exported from `platejs/react` and `@udecode/cn`.

## Installation

```bash
npm install @udecode/react-utils
```

Use direct imports in shared UI packages. Use `platejs/react` when you are already inside a Plate app surface.

## Components

| Component | Renders | Notes |
| --- | --- | --- |
| `PortalBody` | `ReactDOM.createPortal(children, element ?? document.body)` | Returns children directly when no DOM container is available. |
| `Box` | Slot-aware `div` | Created with `createSlotComponent('div')`. Supports `as` and `asChild`. |
| `Text` | Slot-aware `span` | Created with `createSlotComponent('span')`. Supports `as` and `asChild`. |
| `MemoizedChildren` | `React.memo(({ children }) => <>{children}</>)` | Prevents child-only rerenders when parent props are stable. |

```tsx title="Portal to body"
import { PortalBody } from '@udecode/react-utils';

export function BodyOverlay() {
  return (
    <PortalBody>
      <div role="status">Saving</div>
    </PortalBody>
  );
}
```

## Primitive Factories

Use primitive factories when a component needs `asChild`, composed refs, hook-provided props, or hook-provided state.

<API name="createSlotComponent">
<APIParameters>
  <APIItem name="element" type="React.ElementType">
    Default element or component.
  </APIItem>
</APIParameters>
<APIReturns type="React.ForwardRefExoticComponent">
  A component that renders `Slot` when `asChild` is true, `as` when provided, otherwise the default element.
</APIReturns>
</API>

<API name="createPrimitiveElement">
<APIParameters>
  <APIItem name="tag" type="keyof HTMLElementTagNameMap">
    HTML tag to render.
  </APIItem>
</APIParameters>
<APIReturns type="React.ForwardRefExoticComponent">
  A typed `forwardRef` component for that intrinsic element.
</APIReturns>
</API>

<API name="createPrimitiveComponent">
<APIParameters>
  <APIItem name="element" type="React.ElementType">
    Default element or component.
  </APIItem>
  <APIItem name="stateHook" type="(options: any) => any" optional>
    Hook used to create state when the caller does not provide `state`.
  </APIItem>
  <APIItem name="propsHook" type="(state: any) => { hidden?: boolean; props?: object; ref?: React.Ref<any> }" optional>
    Hook used to derive props, hidden state, and a ref from state.
  </APIItem>
</APIParameters>
<APIReturns type="React.ForwardRefExoticComponent">
  A primitive component with `as`, `asChild`, `options`, `state`, `className`, `style`, and `setProps`.
</APIReturns>
</API>

`createPrimitiveComponent` merges hook class names before consumer class names, merges hook style before consumer style, composes forwarded refs with hook refs, and returns `null` when `hidden` is true unless `asChild` is set.

## Ref and Effect Hooks

| API | Type | Behavior |
| --- | --- | --- |
| `composeRefs(...refs)` | `(...refs) => (node) => cleanup?` | Sets callback refs and ref objects to the same node. If refs return cleanup functions, the composed ref returns a cleanup. |
| `useComposedRef(...refs)` | `(...refs) => refCallback` | Memoized `composeRefs` callback. |
| `useStableFn(fn, deps?)` | `(fn, deps = []) => stableFn` | Returns a stable function that calls the latest `fn`. |
| `useStableMemo(producer, deps?)` | `(producer, deps?) => value` | Stores a produced value in state and updates it in a layout effect. |
| `useEffectOnce(effect, deps)` | `(effect, deps) => void` | Runs the effect on first render and again when the dependency values change. |
| `useIsomorphicLayoutEffect` | `React.useLayoutEffect \| React.useEffect` | Uses layout effect in the browser and effect during SSR. |

```tsx title="Compose refs"
import * as React from 'react';
import { useComposedRef } from '@udecode/react-utils';

export const Input = React.forwardRef<HTMLInputElement, React.ComponentProps<'input'>>(
  (props, ref) => {
    const localRef = React.useRef<HTMLInputElement>(null);
    const composedRef = useComposedRef(ref, localRef);

    return <input ref={composedRef} {...props} />;
  }
);
```

## Outside Click

`useOnClickOutside` returns a callback ref unless you pass explicit refs.

<API name="useOnClickOutside">
<APIParameters>
  <APIItem name="callback" type="(event: Event) => void">
    Called when a configured event lands outside every tracked element.
  </APIItem>
  <APIItem name="options.disabled" type="boolean" optional>
    Removes listeners while true.
  </APIItem>
  <APIItem name="options.eventTypes" type="string[]" optional>
    Defaults to `['mousedown', 'touchstart']`.
  </APIItem>
  <APIItem name="options.ignoreClass" type="string | string[]" optional>
    Defaults to `ignore-onclickoutside`. Matching ancestors are ignored.
  </APIItem>
  <APIItem name="options.excludeScrollbar" type="boolean" optional>
    Ignores scrollbar clicks.
  </APIItem>
  <APIItem name="options.detectIFrame" type="boolean" optional>
    Defaults to `true`. Uses window blur to detect iframe focus.
  </APIItem>
  <APIItem name="options.refs" type="React.RefObject<HTMLElement | null>[]" optional>
    Explicit refs to observe instead of the returned callback ref.
  </APIItem>
</APIParameters>
<APIReturns type="(element: HTMLElement | null) => void">
  Callback ref that registers an element for outside-click detection.
</APIReturns>
</API>

## Memo and Event Helpers

| API | Type | Behavior |
| --- | --- | --- |
| `useMemoizedSelector(selector, deps, equalityFn?)` | `(selector, deps, equalityFn?) => value` | Re-renders only when the selector result changes. The default equality is strict equality. |
| `composeEventHandlers(original, next, options?)` | `(event) => void` | Calls `original`, then calls `next` unless `event.defaultPrevented` and `checkForDefaultPrevented` is true. |

## Component Wrappers

<API name="withRef">
<APIParameters>
  <APIItem name="renderFunction" type="React.ForwardRefRenderFunction">
    Forward-ref render function.
  </APIItem>
</APIParameters>
<APIReturns type="React.ForwardRefExoticComponent">
  Typed `React.forwardRef` result.
</APIReturns>
</API>

<API name="withProviders">
<APIParameters>
  <APIItem name="...providers" type="React.ComponentType | [React.ComponentType, props][]">
    Providers to wrap around the component. Array entries pass props to a provider.
  </APIItem>
  <APIItem name="WrappedComponent" type="React.FC<T>">
    Component to wrap.
  </APIItem>
</APIParameters>
<APIReturns type="(props: T) => React.ReactElement">
  Component wrapped by the providers from right to left.
</APIReturns>
</API>

```tsx title="Wrap providers"
import { withProviders } from '@udecode/react-utils';

const ThemeProvider = ({ children }: { children: React.ReactNode }) => (
  <div data-theme="dark">{children}</div>
);

const Page = () => <main>Docs</main>;

export const ThemedPage = withProviders(ThemeProvider)(Page);
```

## Related APIs

- [cn](/docs/api/cn) covers `@udecode/cn`, which re-exports this package.
- [Plate](/docs/api/plate) covers the `platejs/react` umbrella export.


# Resizable

Source: https://platejs.org/docs/api/resizable

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Resizable
description: API reference for @platejs/resizable.
---

`@platejs/resizable` provides the headless resize wrapper, resize handle primitive,
shared resize stores, and length utilities used by Plate media components. It
owns behavior; registry components own styling.

## Installation

```bash
npm install @platejs/resizable
```

## Ownership

| Surface | Owner | Use |
| --- | --- | --- |
| `Resizable` | `@platejs/resizable` | Wraps a Plate element, tracks width, clamps resize values, and writes the final width to the node. |
| `ResizeHandle` | `@platejs/resizable` | Primitive handle that starts mouse/touch resizing and emits `ResizeEvent` values. |
| `ResizableProvider` | `@platejs/resizable` | Stores the active width for the current resizable subtree. |
| `ResizeHandleProvider` | `@platejs/resizable` | Shares the wrapper `onResize` callback with nested handles. |
| Resize hooks | `@platejs/resizable` | Split state from DOM props for custom wrappers and handles. |
| Length utilities | `@platejs/resizable` | Convert and clamp static pixel widths and relative percent widths. |

## Media Pattern

Wrap each resizable element with `ResizableProvider`. Media components use the
provider width for captions and use `Resizable` plus left/right handles around
the media body.

```tsx title="Resizable media element"
import type { TImageElement } from 'platejs';
import type { PlateElementProps } from 'platejs/react';

import {
  Resizable,
  ResizableProvider,
  ResizeHandle,
  useResizableValue,
} from '@platejs/resizable';
import { PlateElement, withHOC } from 'platejs/react';

export const ImageElement = withHOC(
  ResizableProvider,
  function ImageElement(props: PlateElementProps<TImageElement>) {
    const width = useResizableValue('width');

    return (
      <PlateElement {...props}>
        <figure contentEditable={false}>
          <Resizable
            options={{
              align: 'center',
              maxWidth: '100%',
              minWidth: 120,
            }}
          >
            <ResizeHandle options={{ direction: 'left' }} />
            <img alt="" src={props.element.url as string} />
            <ResizeHandle options={{ direction: 'right' }} />
          </Resizable>

          <figcaption style={{ width }}>Caption</figcaption>
        </figure>

        {props.children}
      </PlateElement>
    );
  }
);
```

The registry `resize-handle` component imports these primitives and adds the absolute positioning, hover affordance, and alignment classes.

## Resizable Wrapper

`Resizable` composes `useResizableState` and `useResizable`. It renders a
relative outer wrapper and a relative inner wrapper, then provides its resize
callback to descendants through `ResizeHandleProvider`.

<API name="Resizable">
<APIOptions type="{ options: ResizableOptions } & React.HTMLAttributes<HTMLDivElement>">
  <APIItem name="options" type="ResizableOptions" required>
    Width constraints and alignment used by the resize calculation.
  </APIItem>
  <APIItem name="children" type="React.ReactNode" optional>
    Media body, resize handles, or custom controls.
  </APIItem>
</APIOptions>
</API>

<API name="useResizableState">
<APIOptions type="ResizableOptions">
  <APIItem name="align" type="'center' | 'left' | 'right'" optional>
    Alignment used to calculate resize delta. Defaults to `center`.
  </APIItem>
  <APIItem name="maxWidth" type="ResizeLength" optional>
    Maximum width. Defaults to `100%`.
  </APIItem>
  <APIItem name="minWidth" type="ResizeLength" optional>
    Minimum width. Defaults to `92`.
  </APIItem>
  <APIItem name="readOnly" type="boolean" optional>
    Reserved in the options type. `Resizable` itself does not read this value.
  </APIItem>
</APIOptions>
<APIReturns type="ReturnType<typeof useResizableState>">
  <APIItem name="align" type="'center' | 'left' | 'right'">
    Alignment used by resize math.
  </APIItem>
  <APIItem name="maxWidth" type="ResizeLength">
    Maximum width passed to the wrapper style and clamp utility.
  </APIItem>
  <APIItem name="minWidth" type="ResizeLength">
    Minimum width passed to the wrapper style and clamp utility.
  </APIItem>
  <APIItem name="setNodeWidth" type="(width: number) => void">
    Writes the finished width to the current `TResizableElement`. If the width is unchanged, it selects the node.
  </APIItem>
  <APIItem name="setWidth" type="(width: React.CSSProperties['width']) => void">
    Updates the transient provider width while dragging.
  </APIItem>
  <APIItem name="width" type="React.CSSProperties['width']">
    Current provider width. It is synced from `element.width ?? '100%'`.
  </APIItem>
</APIReturns>
</API>

<API name="useResizable">
<APIParameters>
  <APIItem name="state" type="ReturnType<typeof useResizableState>">
    State returned by `useResizableState`.
  </APIItem>
</APIParameters>
<APIReturns type="object">
  <APIItem name="context.onResize" type="(event: ResizeEvent) => void">
    Converts a handle delta into a new width, clamps it, stores it while dragging, and writes it to the node when `finished` is true.
  </APIItem>
  <APIItem name="props" type="{ style: React.CSSProperties }">
    Inner wrapper props with `position: 'relative'`, `width`, `minWidth`, and `maxWidth`.
  </APIItem>
  <APIItem name="wrapperProps" type="{ style: React.CSSProperties }">
    Outer wrapper props with `position: 'relative'`.
  </APIItem>
  <APIItem name="wrapperRef" type="React.RefObject<HTMLDivElement>">
    Measures the static wrapper width for percent-to-pixel conversion.
  </APIItem>
</APIReturns>
</API>

For centered elements, left and right handles double the delta so the element grows from both sides. Left handles invert the delta before clamping.

## Resize Handles

`ResizeHandle` is a primitive `div` created with `createPrimitiveComponent`. It
returns `null` in read-only mode because `useResizeHandle` sets `hidden` from
`useReadOnly()`.

<API name="ResizeHandle">
<APIOptions type="ResizeHandleProps">
  <APIItem name="options" type="ResizeHandleOptions" optional>
    Direction, initial size, and lifecycle callbacks for the handle.
  </APIItem>
  <APIItem name="state" type="ReturnType<typeof useResizeHandleState>" optional>
    Precomputed state when composing your own handle pipeline.
  </APIItem>
</APIOptions>
</API>

<API name="useResizeHandleState">
<APIOptions type="ResizeHandleOptions">
  <APIItem name="direction" type="ResizeDirection" optional>
    Resize edge. Defaults to `left`.
  </APIItem>
  <APIItem name="initialSize" type="number" optional>
    Starting width or height. If omitted, the handle reads its parent element on pointer start.
  </APIItem>
  <APIItem name="onHover" type="() => void" optional>
    Called on mouse over and touch move.
  </APIItem>
  <APIItem name="onHoverEnd" type="() => void" optional>
    Called after hover ends or resizing finishes.
  </APIItem>
  <APIItem name="onMouseDown" type="React.MouseEventHandler" optional>
    Called after the hook records the starting pointer position and size.
  </APIItem>
  <APIItem name="onResize" type="(event: ResizeEvent) => void" optional>
    Resize callback. Defaults to the nearest `ResizeHandleProvider` value.
  </APIItem>
  <APIItem name="onTouchStart" type="React.TouchEventHandler" optional>
    Called after the hook records the starting touch position and size.
  </APIItem>
</APIOptions>
<APIReturns type="ReturnType<typeof useResizeHandleState>">
  Direction, pointer state, horizontal/vertical mode, read-only state, setters, and callbacks consumed by `useResizeHandle`.
</APIReturns>
</API>

<API name="useResizeHandle">
<APIParameters>
  <APIItem name="state" type="ReturnType<typeof useResizeHandleState>">
    State returned by `useResizeHandleState`.
  </APIItem>
</APIParameters>
<APIReturns type="object">
  <APIItem name="hidden" type="boolean">
    `true` while the editor is read-only.
  </APIItem>
  <APIItem name="props" type="React.HTMLAttributes<HTMLDivElement>">
    Mouse and touch handlers for starting resize, tracking hover, and finishing resize.
  </APIItem>
</APIReturns>
</API>

Resize handles listen on `window` while dragging. Mouse and touch move events emit `finished: false`; mouse up and touch end emit `finished: true`.

## Stores

| API | State | Use |
| --- | --- | --- |
| `ResizableProvider` | `{ width: React.CSSProperties['width'] }` | Wrap a resizable node and expose the active width to captions or overlays. |
| `useResizableValue('width')` | `React.CSSProperties['width']` | Read the current width. |
| `useResizableSet('width')` | setter | Set the current width. |
| `useResizableStore` / `resizableStore` | atom store | Advanced access to the resizable store. |
| `ResizeHandleProvider` | `{ onResize: (event: ResizeEvent) => void }` | Provides the wrapper resize callback to nested handles. |
| `useResizeHandleValue('onResize')` | callback | Read the current resize callback. |
| `useResizeHandleSet('onResize')` | setter | Replace the current resize callback. |
| `useResizeHandleStore` | atom store | Advanced access to the handle store. |

## Types

| Type | Value |
| --- | --- |
| `ResizeDirection` | `'bottom' \| 'left' \| 'right' \| 'top'` |
| `ResizeLength` | `number \| string` |
| `ResizeLengthStatic` | `number` |
| `ResizeLengthRelative` | `string` |
| `ResizeEvent` | `{ delta: number; direction: ResizeDirection; finished: boolean; initialSize: number }` |

## Length Utilities

<API name="Length utilities">
<APIMethods>
  <APIItem name="resizeLengthClampStatic" type="(length: number, options: { min?: number; max?: number }) => number">
    Clamps a pixel length to pixel min/max values.
  </APIItem>
  <APIItem name="resizeLengthClamp" type="<T extends ResizeLength>(length: T, parentLength: number, options: { min?: ResizeLength; max?: ResizeLength }) => T">
    Converts length and constraints to pixels, clamps the value, then returns the same length kind as the input.
  </APIItem>
  <APIItem name="resizeLengthToRelative" type="(length: ResizeLength, parentLength: number) => string">
    Converts a pixel length to a percent string. Percent strings pass through unchanged.
  </APIItem>
  <APIItem name="resizeLengthToStatic" type="(length: ResizeLength, parentLength: number) => number">
    Converts a percent string to pixels. Numbers pass through unchanged.
  </APIItem>
  <APIItem name="isTouchEvent" type="(event: MouseEvent | TouchEvent) => event is TouchEvent">
    Narrows pointer events by checking for `touches`.
  </APIItem>
</APIMethods>
</API>

`resizeLengthToStatic` parses strings as percentages. Use numeric pixel lengths when the source value is not a percentage.

## Related Components

- [Media](/docs/media) covers the image, video, audio, and embed elements that consume the resizable primitives.
- [Resize Handle](/docs/components/resize-handle) covers the styled registry wrapper.


# Slate

Source: https://platejs.org/docs/api/slate

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Slate
description: API reference for @platejs/slate.
---

`@platejs/slate` is Plate's framework-free Slate layer. It exports the editor
factory, editor APIs, transforms, node/location types, DOM helpers from
`slate-dom`, history helpers, and small query utilities.

## Installation

```bash
npm install @platejs/slate
```

Use `@platejs/slate` in package code that should not import React or Plate core.
Use `platejs` in app code when the umbrella package is already available.

## Quick Use

```ts title="Create a framework-free editor"
import { createEditor, withHistory } from '@platejs/slate';

const editor = withHistory(
  createEditor({
    children: [{ children: [{ text: 'Hello' }], type: 'p' }],
  })
);

editor.tf.insertText(' world');

const text = editor.api.string([]);
```

`createEditor` returns an editor with `api`, `tf`, and legacy direct methods.
`withHistory` replaces `undo`, `redo`, `apply`, and `writeHistory` with real
history behavior.

## Package Surface

| Surface | Export | Use |
| --- | --- | --- |
| Editor factory | `createEditor` | Creates a Slate editor and binds Plate's `api` and `tf` namespaces. |
| Editor types | `Editor`, `Value`, `ValueOf` | Type editor instances and document values. |
| Editor API | `EditorApi` | Read/query editor state through `editor.api`. |
| Editor transforms | `EditorTransforms` | Change editor state through `editor.tf`. |
| Interfaces | `ElementApi`, `NodeApi`, `TextApi`, `PathApi`, `PointApi`, `RangeApi`, `OperationApi` | Typed helpers for Slate data structures. |
| Refs | `PathRef`, `PointRef`, `RangeRef` | Mutable location refs that track editor operations. |
| History | `HistoryApi`, `withHistory` | Undo/redo stacks and history batching flags. |
| DOM helpers | `slate-dom` re-exports | DOM selection, browser, and diff helpers used by editable surfaces. |
| Utilities | `getAt`, `match`, `queryEditor`, `queryNode`, `deleteMerge` | Shared query and transform predicates. |

## Editor Shape

An `Editor` contains the Slate document state plus Plate's namespaced helpers.

| Field | Type | Use |
| --- | --- | --- |
| `children` | `Value` | Document nodes. |
| `selection` | `TRange \| null` | Current selection. |
| `operations` | `Operation[]` | Operations applied since the last change flush. |
| `marks` | `Record<string, any> \| null` | Marks applied to the next inserted text. |
| `history` | `History` | Undo and redo stacks. |
| `meta` | `UnknownObject & { isNormalizing?: boolean }` | Custom metadata and normalization state. |
| `api` | `EditorApi` | Query methods. |
| `tf` | `EditorTransforms` | Transform methods. |
| `transforms` | `EditorTransforms` | Alias of `tf` for compatibility. |

`createEditor` also syncs legacy direct methods, so existing Slate-style calls
such as `editor.insertText()` continue to route to the current transform
implementation.

## API Map

| Page | Covers |
| --- | --- |
| [Editor API](/docs/api/slate/editor-api) | Query methods on `editor.api`, including locations, DOM lookup, marks, blocks, and selection predicates. |
| [Editor Transforms](/docs/api/slate/editor-transforms) | Mutation methods on `editor.tf`, including text, node, mark, selection, history, and keyboard transforms. |
| [Node](/docs/api/slate/node) | Node, descendant, ancestor, and node-entry helpers. |
| [Element](/docs/api/slate/element) | Element types, element props, and element guards. |
| [Text](/docs/api/slate/text) | Text node types, mark objects, and text guards. |
| [Path](/docs/api/slate/path) | Path comparison, movement, ancestry, and transform helpers. |
| [Point](/docs/api/slate/point) | Point comparison, edge checks, and point transforms. |
| [Range](/docs/api/slate/range) | Range checks, edge helpers, intersection, inclusion, and transforms. |
| [Location](/docs/api/slate/location) | `Path`, `Point`, `Range`, and `Span` location unions. |
| [Location Ref](/docs/api/slate/location-ref) | `PathRef`, `PointRef`, and `RangeRef` affinity behavior. |
| [Operation](/docs/api/slate/operation) | Slate operation types, operation lists, and operation inversion. |

## History

```ts title="Batch history"
editor.tf.withNewBatch(() => {
  editor.tf.insertText('Title');
  editor.tf.insertBreak();
});

editor.tf.withoutSaving(() => {
  editor.tf.select([]);
});
```

`withHistory` stores undo batches in `history.undos` and redo batches in
`history.redos`. Selection-only operations are not saved. Adjacent text inserts
or removals on the same path merge into one batch unless a history transform
sets a different batching mode.

## DOM Helpers

`@platejs/slate` re-exports selected `slate-dom` helpers, including browser
flags, DOM point/range types, DOM selection helpers, string diff helpers, and
`withDOM`.

Use these exports when a package already depends on `@platejs/slate`; import
from `slate-dom` directly only for code that is intentionally independent of
Plate's Slate layer.

## Utilities

| Utility | Use |
| --- | --- |
| `getAt` | Normalizes editor locations and node inputs before query/transform calls. |
| `match` | Builds node predicates from match options. |
| `queryEditor` | Checks editor state before running a transform. |
| `queryNode` | Checks a node against type, path, and predicate options. |
| `deleteMerge` | Shared delete/merge behavior for text deletion transforms. |
| `assignLegacyTransforms` / `syncLegacyMethods` | Keeps legacy direct editor methods wired to `editor.tf`. |

## Related APIs

- [Plate](/docs/api/plate) shows where `@platejs/slate` is re-exported from the
  `platejs` umbrella package.
- [Plate Editor](/docs/api/core/plate-editor) covers the React/Core editor layer
  built on top of this package.


# Plate Utils

Source: https://platejs.org/docs/api/utils

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Plate Utils
description: API reference for @platejs/utils.
---

`@platejs/utils` contains Plate's shared key constants, editor value types, and
small utility plugins. `@platejs/utils/react` adds React hooks and the block
placeholder plugin used by registry UI.

## Installation

```bash
npm install @platejs/utils
```

Application code usually imports this surface from `platejs` and `platejs/react`.
Direct package imports are useful inside packages that should not depend on the
umbrella `platejs` package.

## Import Paths

| Import | Re-exports | Use |
| --- | --- | --- |
| `@platejs/utils` | `plate-keys`, `plate-types`, utility plugins | Shared node keys, Plate element/mark types, and headless utility plugins. |
| `@platejs/utils/react` | React hooks, `BlockPlaceholderPlugin` | Registry controls and React-only utility behavior. |
| `platejs` | `@platejs/utils` | App-level imports for headless constants, types, and utility plugins. |
| `platejs/react` | `@platejs/utils/react` | App-level imports for React hooks and `BlockPlaceholderPlugin`. |

## Key Constants

`KEYS` is the canonical key map used by Plate packages, registry components, and
plugin configuration.

| Export | Contains | Notes |
| --- | --- | --- |
| `NODES` | Element and mark node keys such as `p`, `blockquote`, `codeBlock`, `table`, `bold`, and `link` | `link` maps to the same node type as `a`. |
| `STYLE_KEYS` | Style property keys such as `color`, `fontSize`, `indent`, and `textAlign` | Used by style plugins and registry controls. |
| `KEYS` | `NODES`, `STYLE_KEYS`, and plugin keys such as `exitBreak`, `normalizeTypes`, `singleBlock`, and `trailingBlock` | Also includes grouped values such as `heading`. |
| `NodeKey` | Union of values from `NODES` | Use for node-type values. |
| `StyleKey` | Union of values from `STYLE_KEYS` | Use for style keys. |
| `PlateKey` | Union of values from `KEYS` | Includes string values and grouped key arrays. |

```ts title="Use Plate keys"
import { KEYS, TrailingBlockPlugin } from 'platejs';

export const trailingBlock = TrailingBlockPlugin.configure({
  options: {
    type: KEYS.p,
  },
});
```

## Shared Types

`plate-types` exports common element, prop, media, list, table, mark, and
suggestion shapes used across feature packages.

| Type group | Examples | Use |
| --- | --- | --- |
| Block elements | `TCalloutElement`, `TCodeBlockElement`, `TColumnElement`, `TDateElement`, `TEquationElement` | Typed element props for feature packages and registry nodes. |
| Media elements | `TImageElement`, `TAudioElement`, `TFileElement`, `TVideoElement`, `TMediaEmbedElement` | Media nodes with `url`, `id`, upload, provider, and source metadata. |
| Table elements | `TTableElement`, `TTableRowElement`, `TTableCellElement`, `TTableCellBorder` | Table structure, spans, sizes, backgrounds, and borders. |
| Shared props | `TIdProps`, `TCaptionProps`, `TIndentProps`, `TResizableProps`, `TListProps` | Reusable node property contracts. |
| Marks | `TBasicMarks`, `TFontMarks`, `TCommentText`, `TSuggestionText` | Text marks and collaboration text state. |
| Suggestions | `TSuggestionData`, `TInsertSuggestionData`, `TRemoveSuggestionData`, `TUpdateSuggestionData` | Suggestion metadata stored on elements or text. |

```ts title="Type a media element"
import type { TImageElement } from 'platejs';

export function getImageUrl(element: TImageElement) {
  return element.url;
}
```

## Utility Plugins

| Plugin | Key | Behavior |
| --- | --- | --- |
| `ExitBreakPlugin` | `KEYS.exitBreak` | Adds `editor.tf.insert` and `editor.tf.insertBefore` wrappers around `insertExitBreak`. |
| `NormalizeTypesPlugin` | `KEYS.normalizeTypes` | Normalizes configured root paths to a required `type` or `strictType`. |
| `SingleBlockPlugin` | `KEYS.singleBlock` | Forces the editor value into one block and turns hard breaks into soft breaks. |
| `SingleLinePlugin` | `KEYS.singleLine` | Forces one block and strips line-break characters from text nodes. |
| `TrailingBlockPlugin` | `KEYS.trailingBlock` | Ensures a trailing block exists at the configured level and type. |
| `withTrailingBlock` | Override editor helper | Implements the trailing block normalization logic used by `TrailingBlockPlugin`. |

Use the plugin guide pages for options and examples:
[Exit Break](/docs/exit-break), [Forced Layout](/docs/forced-layout),
[Single Block](/docs/single-block), and [Trailing Block](/docs/trailing-block).

## React Hooks

| Hook | Returns | Use |
| --- | --- | --- |
| `useEditorString()` | `string` | Reads `editor.api.string([])` through `useEditorSelector`. |
| `useFormInputProps(options?)` | `{ props }` | Adds an optional `onKeyDownCapture` handler that prevents Enter from submitting a wrapper form. |
| `useMarkToolbarButtonState({ nodeType, clear? })` | `{ clear, nodeType, pressed }` | Reads whether a mark is active. |
| `useMarkToolbarButton(state)` | `{ props }` | Provides `pressed`, `onClick`, and `onMouseDown` props that toggle a mark and focus the editor. |
| `useRemoveNodeButton({ element })` | `{ props }` | Provides button props that remove an element by path. |
| `useSelectionCollapsed()` | `boolean` | Selection is collapsed. |
| `useSelectionExpanded()` | `boolean` | Selection is expanded. |
| `useSelectionWithinBlock()` | `boolean` | Selection is inside one block. |
| `useSelectionAcrossBlocks()` | `boolean` | Selection spans blocks. |
| `useSelectionFragment()` | `Descendant[]` | Reads the selected fragment while unwrapping container types. |
| `useSelectionFragmentProp(options?)` | `unknown` | Reads a property from the selected fragment. |

```tsx title="registry/ui/mark-toolbar-button.tsx"
import {
  useMarkToolbarButton,
  useMarkToolbarButtonState,
} from 'platejs/react';

export function MarkToolbarButton({ nodeType }: { nodeType: string }) {
  const state = useMarkToolbarButtonState({ nodeType });
  const { props } = useMarkToolbarButton(state);

  return <button type="button" aria-pressed={props.pressed} {...props} />;
}
```

## React Plugins

| Plugin | Key | Behavior |
| --- | --- | --- |
| `BlockPlaceholderPlugin` | `KEYS.blockPlaceholder` | Tracks the current empty block and injects `placeholder` and optional `className` props into matching block components. |

`BlockPlaceholderPlugin` defaults to paragraph placeholders and only targets a
focused, editable, collapsed selection. Configure `placeholders` by plugin key
and `query` by node/path.

```tsx title="components/editor/plugins/block-placeholder-kit.tsx"
import { KEYS } from 'platejs';
import { BlockPlaceholderPlugin } from 'platejs/react';

export const blockPlaceholderPlugin = BlockPlaceholderPlugin.configure({
  options: {
    placeholders: {
      [KEYS.p]: 'Type something...',
    },
    query: ({ path }) => path.length === 1,
  },
});
```

## Related APIs

- [Plate](/docs/api/plate) covers the umbrella package that re-exports these APIs.
- [Plate Core](/docs/api/core) covers editor creation, plugin contracts, and stores.
- [React Utils](/docs/api/react-utils) covers `@udecode/react-utils`, which is re-exported through `platejs/react`.
- [Toolbar](/docs/toolbar) covers registry controls that use the React hook helpers.


# Local Docs

Source: https://platejs.org/docs/installation/docs

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Local Docs
description: Set up Plate's documentation locally for version-controlled, AI-enhanced development.
---

Host Plate's documentation locally to integrate it directly with your project. This setup ensures your team works with documentation that matches your Plate version while enabling AI tools to better understand and assist with your codebase.

## Why Host Documentation Locally?

Local documentation provides distinct advantages over external sites:

*   **Version Lock-In:** Keep documentation synchronized with your project's Plate version. Avoid confusion from features or APIs in newer, unadopted Plate releases.
*   **AI-Ready Development:**
    *   **Better than `llms.txt`:** While dumping docs into a single text file is common for LLM context, this breaks down with large documentation (exceeding typical 100k token limits). Our structured, local setup lets AI tools access exactly what they need.
    *   **Direct Access for AI Tools:** Your AI-assisted IDE gets direct access to version-specific documentation, enabling accurate code generation and contextual help with your Plate setup.
    *   **Structured for AI Tasks:** AI tools can help with tasks like translating docs, creating summaries, or updating documentation between Plate versions.
*   **Customization & Control:** Modify documentation appearance and structure to match your project needs.
*   **Easy Updates:** Treat documentation like code - review, update, and version control it with your codebase.
*   **Fast Access:** Get reliable, quick access to documentation.
*   **Central Hub:** Keep Plate docs alongside documentation for other libraries in one place.

## Setup Guide

There are two ways to set up local documentation:

### Option 1: Docs App

This option sets up a complete documentation site using Fumadocs, providing a searchable, navigable interface.

<Steps>

#### Create Fumadocs App

Set up a Fumadocs app which provides the Next.js-based framework for your documentation site:

```bash
pnpm create fumadocs-app
```

During setup:
- **Name:** Enter `docs` when prompted
- **Choose your preferred options** (defaults work well)
- The wizard will create a `docs` directory with all necessary files

Navigate to your newly created `docs` directory:

```bash
cd docs
```

For detailed Fumadocs setup, see the [Fumadocs UI documentation](https://fumadocs.dev/docs/ui).

#### Create `components.json`

In your docs directory, create a `components.json` file. You have two options:

**Option A: Command line**

```bash
echo '{\n  "$schema": "https://ui.shadcn.com/schema.json",\n  "style": "new-york",\n  "rsc": true,\n  "tsx": true,\n  "tailwind": {\n    "config": "",\n    "css": "app/global.css",\n    "baseColor": "neutral",\n    "cssVariables": true,\n    "prefix": ""\n  },\n  "aliases": {\n    "components": "@/components",\n    "utils": "@/lib/utils",\n    "ui": "@/components/ui",\n    "lib": "@/lib",\n    "hooks": "@/hooks"\n  },\n  "iconLibrary": "lucide"\n}' > components.json
```

**Option B: Copy and paste**

Create a new file called `components.json` in your docs directory with this content:

```json
{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "new-york",
  "rsc": true,
  "tsx": true,
  "tailwind": {
    "config": "",
    "css": "app/global.css",
    "baseColor": "neutral",
    "cssVariables": true,
    "prefix": ""
  },
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils",
    "ui": "@/components/ui",
    "lib": "@/lib",
    "hooks": "@/hooks"
  },
  "iconLibrary": "lucide"
}
```

#### Add Plate Documentation

Fetch the Plate documentation files and necessary MDX components from the `@plate` registry.

```bash
npx shadcn@latest add @plate/fumadocs
```

<Callout type="warning" title="Version-Specific Documentation">
  The command above installs the current Plate documentation from the live registry.
  For older Plate versions, raw GitHub URLs are safe only for leaf registry
  items that declare no `registryDependencies`.

  Do not install aggregate items such as `fumadocs.json` or `docs.json` from a
  raw GitHub tag: their transitive registry dependencies can resolve from the
  live registry. For full version-pinned docs, generate or serve the registry
  from the matching Plate checkout so every transitive item comes from the same
  version.
</Callout>

#### Run Fumadocs App

Start the development server:

```bash
pnpm run dev
```

Your documentation site will be available at:
- Plate docs: `http://localhost:3000/docs/plate`

#### Customize

Enhance your docs with [Fumadocs features](https://fumadocs.dev/docs/ui#writing-content).

</Steps>

### Option 2: MDX Files Only

If you just want the documentation files without setting up a full site, you can add them directly to your existing project:

```bash
# Run from your project root (wherever you want the docs)
npx shadcn@latest add @plate/docs
```

This will:
- Install MDX documentation files in your project (typically in a `docs/` or similar directory)
- Skip the Fumadocs setup entirely
- Give you raw MDX files to use however you need

Use cases:
- Reference documentation directly in your codebase
- Integrate with your existing documentation setup
- Make docs available to AI tools for better context

## Advanced Integration

### MCP Integration

Enable AI tools to work with your local documentation by adding the Plate server to your `.cursor/mcp.json` (or equivalent).

```json
{
  "mcpServers": {
    "shadcn": {
      "description": "Shadcn and Plate MCP",
      "command": "npx",
      "args": [
        "shadcn@latest",
        "mcp"
      ]
    }
  }
}
```

Your AI tools can then:
*   Access documentation context for better code assistance
*   Help manage and update documentation
*   Generate code with proper imports and configurations
*   Assist with editor setup and feature integration

See the [MCP Guide](/docs/installation/mcp) for more details.

<Callout>
  Once configured, try asking your AI:
  ```bash
  "Help me understand how the Plate AI plugin works"
  "How to create a custom plugin?"
  "What's new in the latest Plate version?"
  ```
</Callout>

### Centralizing Multiple Documentations

Your `content/docs/` directory can host documentation for multiple libraries. Replicate the process for Plate to add docs for other internal or external tools:

```plaintext
content/
└── docs/
    ├── plate/         # Plate documentation
    │   └── ...
    ├── other-library/ # Documentation for another library
    │   └── ...
    └── index.mdx      # Main landing page for all docs
```

This creates a unified, version-controlled knowledge base for your project stack.


# Manual Installation

Source: https://platejs.org/docs/installation/manual

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Manual Installation
description: Install and configure Plate in your React project without relying on UI component libraries.
---

This guide walks you through setting up Plate from scratch, giving you full control over styling and component rendering. This approach is ideal if you're not using a UI library like shadcn/ui or Tailwind CSS.

<Steps>

### Create Project

<Callout type="info">
This guide uses **Vite** for demonstrating the initial project setup. Plate is framework-agnostic and integrates seamlessly with other React environments like Next.js or Remix. You can adapt the general setup principles to your chosen framework.
</Callout>

To begin with Vite, create a new project and select the **React + TypeScript** template:

```bash
npm create vite@latest
```

### Install Core Dependencies

First, install the necessary Plate packages. These packages provide the core editor functionality, React integration, and basic plugins for marks and elements.

```bash
npm install platejs @platejs/basic-nodes
```

-   `platejs`: The core Plate engine and React components.
-   `@platejs/basic-nodes`: Plugin for basic nodes like headings, bold, italic, underline, etc.

### TypeScript Configuration

Plate provides ESM packages. If you're using TypeScript, ensure your `tsconfig.json` is configured correctly. The recommended setup for Plate requires TypeScript 5.0+ with the `"moduleResolution": "bundler"` setting:

```jsonc
// tsconfig.json
{
  "compilerOptions": {
    // ... other options
    "module": "esnext", // or commonjs if your setup requires it and handles ESM interop
    "moduleResolution": "bundler",
    // ... other options
  },
}
```

<Callout type="info">
  If you cannot use `"moduleResolution": "bundler"` or are on an older TypeScript version, please see our [full TypeScript guide](/docs/typescript) for alternative configurations using path aliases.
</Callout>

### Create Your First Editor

Start by creating a basic editor component. This example sets up a simple editor.

```tsx title="src/App.tsx"
import React from 'react';
import type { Value } from 'platejs';
import { Plate, PlateContent, usePlateEditor } from 'platejs/react';

export default function App() {
  const editor = usePlateEditor();

  return (
    <Plate editor={editor}>
      <PlateContent 
        style={{ padding: '16px 64px', minHeight: '100px' }}
        placeholder="Type your amazing content here..."
      />
    </Plate>
  );
}
```

<Callout type="info">
  `usePlateEditor` creates a memoized editor instance, ensuring stability across re-renders. For a non-memoized version, use `createPlateEditor` from `platejs/react`.
</Callout>

[installation-next-01-editor-demo registry content](https://platejs.org/r/installation-next-01-editor-demo)

At this point, you'll have a very basic editor capable of displaying and editing plain text.

### Adding Basic Marks

Let's add support for basic text formatting like bold, italic, and underline.

```tsx showLineNumbers title="src/App.tsx" {4-8,32}
import React from 'react';
import type { Value } from 'platejs';

import {
  BoldPlugin,
  ItalicPlugin,
  UnderlinePlugin,
} from '@platejs/basic-nodes/react';
import {
  Plate,
  PlateContent,
  usePlateEditor,
} from 'platejs/react';

const initialValue: Value = [
  {
    type: 'p',
    children: [
      { text: 'Hello! Try out the ' },
      { text: 'bold', bold: true },
      { text: ', ' },
      { text: 'italic', italic: true },
      { text: ', and ' },
      { text: 'underline', underline: true },
      { text: ' formatting.' },
    ],
  },
];

export default function App() {
  const editor = usePlateEditor({
    plugins: [BoldPlugin, ItalicPlugin, UnderlinePlugin],
    value: initialValue,
  });

  return (
    <Plate editor={editor}>
      {/* You would typically add a toolbar here to toggle marks */}
      <PlateContent style={{ padding: '16px 64px', minHeight: '100px' }} />
    </Plate>
  );
}
```

<Callout type="info" title="Default Components">
  Mark plugins like `BoldPlugin`, `ItalicPlugin`, and `UnderlinePlugin` come with default components that render as `<strong>`, `<em>`, and `<u>` elements respectively. You don't need to register custom components unless you want to customize their appearance.
</Callout>

[installation-next-02-marks-demo registry content](https://platejs.org/r/installation-next-02-marks-demo)

You'll need to implement your own toolbar to apply these marks. For example, to toggle bold: `editor.tf.bold.toggle()`.

### Adding Basic Elements

Now, let's add support for block-level elements like headings, and blockquotes.

```tsx showLineNumbers title="src/App.tsx" {5,7-9,76-79}
import React from 'react';
import type { Value } from 'platejs';

import {
  BlockquotePlugin,
  BoldPlugin,
  H1Plugin,
  H2Plugin,
  H3Plugin,
  ItalicPlugin,
  UnderlinePlugin,
} from '@platejs/basic-nodes/react';
import {
  Plate,
  PlateContent,
  PlateElement,
  usePlateEditor,
  type PlateElementProps,
} from 'platejs/react';

const initialValue: Value = [
  {
    children: [{ text: 'Title' }],
    type: 'h3',
  },
  {
    children: [
      {
        children: [{ text: 'This is a quote.' }],
        type: 'p',
      },
    ],
    type: 'blockquote',
  },
  {
    children: [
      { text: 'With some ' },
      { bold: true, text: 'bold' },
      { text: ' text for emphasis!' },
    ],
    type: 'p',
  },
];

// Define element components
function H1Element(props: PlateElementProps) {
  return <PlateElement as="h1" {...props} />;
}

function H2Element(props: PlateElementProps) {
  return <PlateElement as="h2" {...props} />;
}

function H3Element(props: PlateElementProps) {
  return <PlateElement as="h3" {...props} />;
}

function BlockquoteElement(props: PlateElementProps) {
  return (
    <PlateElement
      as="blockquote"
      style={{
        borderLeft: '2px solid #eee',
        marginLeft: 0,
        marginRight: 0,
        paddingLeft: '24px',
        color: '#666',
        fontStyle: 'italic',
      }}
      {...props}
    />
  );
}

export default function App() {
  const editor = usePlateEditor({
    plugins: [
      BoldPlugin,
      ItalicPlugin,
      UnderlinePlugin,
      H1Plugin.withComponent(H1Element),
      H2Plugin.withComponent(H2Element),
      H3Plugin.withComponent(H3Element),
      BlockquotePlugin.withComponent(BlockquoteElement),
    ],
    value: initialValue,
  });

  return (
    <Plate editor={editor}>
      {/* You would typically add a toolbar here to toggle elements and marks */}
      <PlateContent style={{ padding: '16px 64px', minHeight: '100px' }} />
    </Plate>
  );
}
```

<Callout type="note">
  Notice how we use `Plugin.withComponent(Component)` to register components with block element plugins like headings and blockquotes. This is the recommended approach for associating React components with Plate plugins when you need custom styling or behavior.
</Callout>

[installation-next-03-elements-demo registry content](https://platejs.org/r/installation-next-03-elements-demo)

### Handling Editor Value

To make the editor's content persistent, let's integrate state management to save and load the editor's value.

```tsx showLineNumbers title="src/App.tsx" {81-84,90-92}
import React from 'react';
import type { Value } from 'platejs';

import {
  BlockquotePlugin,
  BoldPlugin,
  H1Plugin,
  H2Plugin,
  H3Plugin,
  ItalicPlugin,
  UnderlinePlugin,
} from '@platejs/basic-nodes/react';
import {
  Plate,
  PlateContent,
  PlateElement,
  usePlateEditor,
  type PlateElementProps,
} from 'platejs/react';

const initialValue: Value = [
  {
    children: [{ text: 'Title' }],
    type: 'h3',
  },
  {
    children: [
      {
        children: [{ text: 'This is a quote.' }],
        type: 'p',
      },
    ],
    type: 'blockquote',
  },
  {
    children: [
      { text: 'With some ' },
      { bold: true, text: 'bold' },
      { text: ' text for emphasis!' },
    ],
    type: 'p',
  },
];

// Define element components
function H1Element(props: PlateElementProps) {
  return <PlateElement as="h1" {...props} />;
}

function H2Element(props: PlateElementProps) {
  return <PlateElement as="h2" {...props} />;
}

function H3Element(props: PlateElementProps) {
  return <PlateElement as="h3" {...props} />;
}

function BlockquoteElement(props: PlateElementProps) {
  return (
    <PlateElement
      as="blockquote"
      style={{
        borderLeft: '2px solid #eee',
        marginLeft: 0,
        marginRight: 0,
        paddingLeft: '24px',
        color: '#666',
        fontStyle: 'italic',
      }}
      {...props}
    />
  );
}

export default function App() {
  const editor = usePlateEditor({
    plugins: [
      BoldPlugin,
      ItalicPlugin,
      UnderlinePlugin,
      H1Plugin.withComponent(H1Element),
      H2Plugin.withComponent(H2Element),
      H3Plugin.withComponent(H3Element),
      BlockquotePlugin.withComponent(BlockquoteElement),
    ],
    value: () => {
      const savedValue = localStorage.getItem('plate-manual-demo');
      return savedValue ? JSON.parse(savedValue) : initialValue;
    },
  });

  return (
    <Plate
      editor={editor}
      onChange={({ value }) => {
        localStorage.setItem('plate-manual-demo', JSON.stringify(value));
      }}
    >
      {/* Toolbar would go here */}
      <div style={{ padding: '8px 0' }}>
        <button
          onClick={() => editor.tf.setValue(initialValue)}
          style={{
            padding: '4px 8px',
            margin: '0 4px',
            border: '1px solid #ccc',
            borderRadius: '4px',
            cursor: 'pointer',
          }}
        >
          Reset
        </button>
      </div>
      <PlateContent
        style={{
          padding: '16px 64px',
          minHeight: '100px',
          border: '1px solid #eee',
          borderRadius: '4px',
        }}
        placeholder="Type your amazing content here..."
      />
    </Plate>
  );
}
```

<Callout type="info" title="Value Management">
  The example above demonstrates a basic pattern for managing editor value:
  - Initial value is set through the `value` option in `usePlateEditor`
  - Changes can be handled via the `onChange` prop on `<Plate>`
  - The reset button uses `editor.tf.setValue()` to restore the initial value
  - To control the value, see [Controlled Value](/docs/controlled)
</Callout>

[installation-next-demo registry content](https://platejs.org/r/installation-next-demo)

### Next Steps

You've now set up a basic Plate editor manually! From here, you can:

*   **Add Styling:**
    *   For a quick start with pre-built components, consider using [Plate UI](/docs/installation/plate-ui)
    *   Or continue styling manually using CSS, CSS-in-JS libraries, or your preferred styling solution
*   **[Add Plugins](/docs/plugins):** Plate has a rich ecosystem of plugins for features like tables, mentions, images, lists, and more. Install their packages (e.g., `@platejs/table`) and add them to your `plugins` array.
*   **[Build a Toolbar](/docs/toolbar):** Create React components for toolbar buttons that use the [Editor Transforms](/docs/transforms) to apply formatting (e.g., `editor.tf.bold.toggle()`, `editor.tf.h1.toggle()`). You can also use the editor state with the [Editor API](/docs/api).
*   **Learn More:**
    *   [Editor Configuration](/docs/editor)
    *   [Plugin Configuration](/docs/plugin)
    *   [Plugin Components](/docs/plugin-components)

</Steps>


# MCP Server

Source: https://platejs.org/docs/installation/mcp

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: MCP Server
description: Use the Model Context Protocol with Plate.
---

Plate has an official MCP server. This lets AI tools understand and work with our rich ecosystem of editor templates, plugin configurations, UI components, and documentation.

## What is MCP?

The Model Context Protocol (MCP) is an open protocol that standardizes how applications provide context to LLMs. This is useful for Plate because you can now give your AI-assisted IDE direct access to hundreds of Plate resources.

## Using MCP with Plate

Your AI can now:

- Access to all our editor templates, plugins, and UI components
- Access our complete documentation, including guides and API references
- Generate code with the right imports and configurations
- Help with setting up full editor instances or specific features
- Keep your Plate configurations and components up to date

Try asking your AI:

```bash
"Set up a Plate editor with basic formatting and table support"
"Help me understand how the Plate AI plugin works"
"Update my editor components to the latest version"
```

## How it works

The Plate ecosystem provides structured information that MCP-enabled tools can read from a unified registry that includes:

- Editor templates and plugin configurations
- UI components and their dependencies
- Documentation files and migration guides
- API references and examples

This comprehensive registry ensures AI tools have complete context for both code generation and understanding Plate's features.

## Local Documentation

For teams working with Plate, integrating local documentation is key to maximizing the benefits of MCP. We recommend following our [Local Docs](/docs/installation/docs) guide to set this up. This approach offers several advantages for AI-powered development:

-   **Version-Specific Context:** AI tools gain direct access to documentation that precisely matches your project's Plate version, ensuring relevant and accurate assistance.
-   **Superior to `llms.txt`:** Unlike simply dumping documentation into a text file (which can struggle with large volumes and context limits), a structured local setup allows AI to efficiently access the specific information it needs.
-   **Integrated Workflow:** Documentation becomes a part of your codebase, simplifying updates, version control, and team collaboration.
-   **AI-Ready:** A well-structured local documentation allows AI to more effectively assist with tasks such as generating code, creating summaries, or explaining complex Plate features within the context of your project.

## Setup MCP

Follow these steps to set up MCP with Plate:

### Step 1: Install Plate

For an existing shadcn project, add the Plate registry to `components.json`:

```json
{
  "registries": {
    "@plate": "https://platejs.org/r/{name}.json"
  }
}
```

Then add the basic editor from the `@plate` registry:

```bash
npx shadcn@latest add @plate/editor-basic
```

For a new project, initialize with the Plate preset:

```bash
npx shadcn@latest init --preset https://platejs.org/init
```

### Step 2: Configure your IDE

Choose the configuration for your IDE:

#### Cursor

Copy and paste into `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "plate": {
      "description": "Plate editors, plugins and components",
      "type": "stdio",
      "command": "npx",
      "args": [
        "shadcn@latest",
        "mcp"
      ]
    }
  }
}
```

#### VS Code

Copy and paste into `.vscode/mcp.json` in your workspace:

```json
{
  "servers": {
    "plate": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "shadcn@latest",
        "mcp"
      ]
    }
  }
}
```

#### Claude

Copy and paste into `.mcp.json`:

```json
{
  "mcpServers": {
    "plate": {
      "description": "Plate editors, plugins and components",
      "type": "stdio",
      "command": "npx",
      "args": [
        "shadcn@latest",
        "mcp"
      ]
    }
  }
}
```

#### CodeX

1. Open or create the file `~/.codex/config.toml`
2. Add the following configuration:

```toml
[mcp_servers.plate]
command = "npx"
args = ["shadcn@latest", "mcp"]
```

3. Restart CodeX to load the MCP server

## Best Practices

1.  **Local Documentation:** Set up local documentation to give AI tools version-specific context. This ensures more accurate assistance, especially for larger projects.
2.  **AI-Assisted Development:** Let AI handle editor setup, plugin integration, and component additions.
3.  **Manual Fallback:** Use the [shadcn CLI](/docs/components/cli) for manual additions when needed (e.g., with small models or outdated documentation).
4.  **Stay Updated:** Keep both your Plate components and local documentation in sync. Use [Sync copied files](/docs/installation/plate-ui#sync-copied-files) when your AI needs to sync copied registry files.


# Next.js

Source: https://platejs.org/docs/installation/next

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Next.js
description: Install and configure Plate UI for Next.js
---

<Callout type="warning" title="Prerequisites">
  Before you begin, ensure you have installed and configured [shadcn/ui](https://ui.shadcn.com/docs/installation/next) and [Plate UI](/docs/installation/plate-ui).
</Callout>

This guide walks you through incrementally building a Plate editor in your Next.js application.

<Steps>

### Create Your First Editor

Start by adding the core [Editor](/docs/components/editor) component to your project:

```bash
npx shadcn@latest add @plate/editor
```

Next, create a basic editor page. This example sets up a simple editor within an `EditorContainer`.

```tsx showLineNumbers title="app/editor/page.tsx"
'use client';

import { Plate, usePlateEditor } from 'platejs/react';

import { Editor, EditorContainer } from '@/components/ui/editor';

export default function MyEditorPage() {
  const editor = usePlateEditor(); // Initializes the editor instance

  return (
    <Plate editor={editor}>      {/* Provides editor context */}
      <EditorContainer>         {/* Styles the editor area */}
        <Editor placeholder="Type your amazing content here..." />
      </EditorContainer>
    </Plate>
  );
}
```

<Callout type="info">
  `usePlateEditor` creates a memoized editor instance, ensuring stability across re-renders. For a non-memoized version, use `createPlateEditor`.
</Callout>

[installation-next-01-editor-demo registry content](https://platejs.org/r/installation-next-01-editor-demo)

### Adding Basic Marks

Enhance your editor with text formatting. Add the **Basic Nodes Kit**, [FixedToolbar](/docs/components/fixed-toolbar) and [MarkToolbarButton](/docs/components/mark-toolbar-button) components:

```bash
npx shadcn@latest add @plate/basic-nodes-kit @plate/fixed-toolbar @plate/mark-toolbar-button
```

<Callout type="info">
  The `basic-nodes-kit` includes all the basic plugins (bold, italic, underline, headings, blockquotes, etc.) and their components that we'll use in the following steps.
</Callout>

Update your editor page to include these components and the basic mark plugins.
This example adds bold, italic, and underline functionality.

```tsx showLineNumbers title="app/editor/page.tsx" {4,6-10,17-18,20-33,37-38,43-47}
'use client';

import * as React from 'react';
import type { Value } from 'platejs';

import {
  BoldPlugin,
  ItalicPlugin,
  UnderlinePlugin,
} from '@platejs/basic-nodes/react';
import {
  Plate,
  usePlateEditor,
} from 'platejs/react';

import { Editor, EditorContainer } from '@/components/ui/editor';
import { FixedToolbar } from '@/components/ui/fixed-toolbar';
import { MarkToolbarButton } from '@/components/ui/mark-toolbar-button';

const initialValue: Value = [
  {
    type: 'p',
    children: [
      { text: 'Hello! Try out the ' },
      { text: 'bold', bold: true },
      { text: ', ' },
      { text: 'italic', italic: true },
      { text: ', and ' },
      { text: 'underline', underline: true },
      { text: ' formatting.' },
    ],
  },
];

export default function MyEditorPage() {
  const editor = usePlateEditor({
    plugins: [BoldPlugin, ItalicPlugin, UnderlinePlugin], // Add the mark plugins
    value: initialValue,         // Set initial content
  });

  return (
    <Plate editor={editor}>
      <FixedToolbar className="justify-start rounded-t-lg">
        <MarkToolbarButton nodeType="bold" tooltip="Bold (⌘+B)">B</MarkToolbarButton>
        <MarkToolbarButton nodeType="italic" tooltip="Italic (⌘+I)">I</MarkToolbarButton>
        <MarkToolbarButton nodeType="underline" tooltip="Underline (⌘+U)">U</MarkToolbarButton>
      </FixedToolbar>
      <EditorContainer>
        <Editor placeholder="Type your amazing content here..." />
      </EditorContainer>
    </Plate>
  );
}
```

[installation-next-02-marks-demo registry content](https://platejs.org/r/installation-next-02-marks-demo)

### Adding Basic Elements

Introduce block-level elements like headings and blockquotes with custom components.

```tsx showLineNumbers title="app/editor/page.tsx" {7,9-11,20,23,25,28-35,52-55,63-67}
'use client';

import * as React from 'react';
import type { Value } from 'platejs';

import {
  BlockquotePlugin,
  BoldPlugin,
  H1Plugin,
  H2Plugin,
  H3Plugin,
  ItalicPlugin,
  UnderlinePlugin,
} from '@platejs/basic-nodes/react';
import {
  Plate,
  usePlateEditor,
} from 'platejs/react';

import { BlockquoteElement } from '@/components/ui/blockquote-node';
import { Editor, EditorContainer } from '@/components/ui/editor';
import { FixedToolbar } from '@/components/ui/fixed-toolbar';
import { H1Element, H2Element, H3Element } from '@/components/ui/heading-node';
import { MarkToolbarButton } from '@/components/ui/mark-toolbar-button';
import { ToolbarButton } from '@/components/ui/toolbar'; // Generic toolbar button

const initialValue: Value = [
  {
    children: [{ text: 'Title' }],
    type: 'h3',
  },
  {
    children: [
      {
        children: [{ text: 'This is a quote.' }],
        type: 'p',
      },
    ],
    type: 'blockquote',
  },
  {
    children: [
      { text: 'With some ' },
      { bold: true, text: 'bold' },
      { text: ' text for emphasis!' },
    ],
    type: 'p',
  },
];

export default function MyEditorPage() {
  const editor = usePlateEditor({
    plugins: [
      BoldPlugin,
      ItalicPlugin,
      UnderlinePlugin,
      H1Plugin.withComponent(H1Element),
      H2Plugin.withComponent(H2Element),
      H3Plugin.withComponent(H3Element),
      BlockquotePlugin.withComponent(BlockquoteElement),
    ],
    value: initialValue,
  });

  return (
    <Plate editor={editor}>
      <FixedToolbar className="flex justify-start gap-1 rounded-t-lg">
        {/* Element Toolbar Buttons */}
        <ToolbarButton onClick={() => editor.tf.h1.toggle()}>H1</ToolbarButton>
        <ToolbarButton onClick={() => editor.tf.h2.toggle()}>H2</ToolbarButton>
        <ToolbarButton onClick={() => editor.tf.h3.toggle()}>H3</ToolbarButton>
        <ToolbarButton onClick={() => editor.tf.blockquote.toggle()}>Quote</ToolbarButton>
        {/* Mark Toolbar Buttons */}
        <MarkToolbarButton nodeType="bold" tooltip="Bold (⌘+B)">B</MarkToolbarButton>
        <MarkToolbarButton nodeType="italic" tooltip="Italic (⌘+I)">I</MarkToolbarButton>
        <MarkToolbarButton nodeType="underline" tooltip="Underline (⌘+U)">U</MarkToolbarButton>
      </FixedToolbar>
      <EditorContainer>
        <Editor placeholder="Type your amazing content here..." />
      </EditorContainer>
    </Plate>
  );
}
```

[installation-next-03-elements-demo registry content](https://platejs.org/r/installation-next-03-elements-demo)

<Callout type="info" title="Component Registration">
  Notice how we use `Plugin.withComponent(Component)` to register components with their respective plugins. This is the recommended approach for associating React components with Plate plugins.

  For a quicker start with common plugins and components pre-configured, use the `editor-basic` block:
  ```bash
  npx shadcn@latest add @plate/editor-basic
  ```
  This handles much of the boilerplate for you.
</Callout>

### Handling Editor Value

To make the editor content persistent, let's integrate `localStorage` to save and load the editor's value client-side.

```tsx showLineNumbers title="app/editor/page.tsx" {57-60,66-68,78-84}
'use client';

import * as React from 'react';
import type { Value } from 'platejs';

import {
  BlockquotePlugin,
  BoldPlugin,
  H1Plugin,
  H2Plugin,
  H3Plugin,
  ItalicPlugin,
  UnderlinePlugin,
} from '@platejs/basic-nodes/react';
import {
  Plate,
  usePlateEditor,
} from 'platejs/react';

import { BlockquoteElement } from '@/components/ui/blockquote-node';
import { Editor, EditorContainer } from '@/components/ui/editor';
import { FixedToolbar } from '@/components/ui/fixed-toolbar';
import { H1Element, H2Element, H3Element } from '@/components/ui/heading-node';
import { MarkToolbarButton } from '@/components/ui/mark-toolbar-button';
import { ToolbarButton } from '@/components/ui/toolbar';

const initialValue: Value = [
  {
    children: [{ text: 'Title' }],
    type: 'h3',
  },
  {
    children: [
      {
        children: [{ text: 'This is a quote.' }],
        type: 'p',
      },
    ],
    type: 'blockquote',
  },
  {
    children: [
      { text: 'With some ' },
      { bold: true, text: 'bold' },
      { text: ' text for emphasis!' },
    ],
    type: 'p',
  },
];

export default function MyEditorPage() {
  const editor = usePlateEditor({
    plugins: [
      BoldPlugin,
      ItalicPlugin,
      UnderlinePlugin,
      H1Plugin.withComponent(H1Element),
      H2Plugin.withComponent(H2Element),
      H3Plugin.withComponent(H3Element),
      BlockquotePlugin.withComponent(BlockquoteElement),
    ],
    value: () => {
      const savedValue = localStorage.getItem('installation-next-demo');
      return savedValue ? JSON.parse(savedValue) : initialValue;
    },
  });

  return (
    <Plate
      editor={editor}
      onChange={({ value }) => {
        localStorage.setItem('installation-next-demo', JSON.stringify(value));
      }}
    >
      <FixedToolbar className="flex justify-start gap-1 rounded-t-lg">
        <ToolbarButton onClick={() => editor.tf.h1.toggle()}>H1</ToolbarButton>
        <ToolbarButton onClick={() => editor.tf.h2.toggle()}>H2</ToolbarButton>
        <ToolbarButton onClick={() => editor.tf.h3.toggle()}>H3</ToolbarButton>
        <ToolbarButton onClick={() => editor.tf.blockquote.toggle()}>Quote</ToolbarButton>
        <MarkToolbarButton nodeType="bold" tooltip="Bold (⌘+B)">B</MarkToolbarButton>
        <MarkToolbarButton nodeType="italic" tooltip="Italic (⌘+I)">I</MarkToolbarButton>
        <MarkToolbarButton nodeType="underline" tooltip="Underline (⌘+U)">U</MarkToolbarButton>
        <div className="flex-1" />
        <ToolbarButton
          className="px-2"
          onClick={() => editor.tf.setValue(initialValue)}
        >
          Reset
        </ToolbarButton>
      </FixedToolbar>
      <EditorContainer>
        <Editor placeholder="Type your amazing content here..." />
      </EditorContainer>
    </Plate>
  );
}
```

[installation-next-demo registry content](https://platejs.org/r/installation-next-demo)

### Next Steps

Congratulations! You've built a foundational Plate editor in Next.js.

To further enhance your editor:

*   **Explore Components:** Discover [Toolbars, Menus, Node components](/docs/components), and more.
*   **Add Plugins:** Integrate features like [Tables](/docs/table), [Mentions](/docs/mention), [AI](/docs/ai), or [Markdown](/docs/markdown).
*   **Use Editor Blocks:** Quickly set up pre-configured editors:
    *   Basic editor: `npx shadcn@latest add @plate/editor-basic`
    *   AI-powered editor: `npx shadcn@latest add @plate/editor-ai`
*   **Learn More:**
    *   [Editor Configuration](/docs/editor)
    *   [Plugin Configuration](/docs/plugin)
    *   [Plugin Components](/docs/plugin-components)

</Steps>


# Node.js

Source: https://platejs.org/docs/installation/node

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Node.js
description: Install and configure Plate for Node.js.
---

Use Plate in Node.js when you need to read, validate, transform, or serialize editor values outside the browser. Node scripts use the base runtime imports, while React editors use `/react` subpaths. This guide walks through a server-safe editor, Markdown IO, and a content transform.

## Node.js Setup

<Callout type="warning" title="Use base imports">
  Do not import from `platejs/react` or `@platejs/*/react` in Node.js scripts.
  Use `createSlateEditor` from `platejs` and base plugins from `@platejs/*`
  packages.
</Callout>

<Steps>

### Install Packages

Install the core runtime and the packages your pipeline needs.

```bash
npm install platejs @platejs/basic-nodes @platejs/markdown
```

| Package | Owns |
| --- | --- |
| `platejs` | `createSlateEditor`, core editor APIs, core paragraph behavior. |
| `@platejs/basic-nodes` | Base headings, blockquotes, horizontal rules, and text marks. |
| `@platejs/markdown` | Markdown serialization, deserialization, and the `MarkdownPlugin` API. |

### Create a Server Editor

Create the editor with base plugins only. The editor exposes the same `editor.api`
and `editor.tf` surfaces without mounting a React tree.

```ts showLineNumbers title="scripts/process-content.ts"
import type { Value } from 'platejs';

import {
  BaseBasicBlocksPlugin,
  BaseBasicMarksPlugin,
} from '@platejs/basic-nodes';
import { createSlateEditor } from 'platejs';

const value: Value = [
  {
    children: [{ text: 'Document Title' }],
    type: 'h1',
  },
  {
    children: [
      { text: 'With ' },
      { bold: true, text: 'bold' },
      { text: ' text.' },
    ],
    type: 'p',
  },
];

const editor = createSlateEditor({
  plugins: [BaseBasicBlocksPlugin, BaseBasicMarksPlugin],
  value,
});

const plainText = editor.api.string([]);

console.info(plainText);
```

### Read and Write Markdown

Add `MarkdownPlugin` when the script needs Markdown helpers through
`editor.getApi(MarkdownPlugin)`. You can also call `deserializeMd` and
`serializeMd` directly.

```ts showLineNumbers title="scripts/markdown-io.ts"
import {
  BaseBasicBlocksPlugin,
  BaseBasicMarksPlugin,
} from '@platejs/basic-nodes';
import {
  MarkdownPlugin,
  deserializeMd,
  serializeMd,
} from '@platejs/markdown';
import { createSlateEditor } from 'platejs';

const editor = createSlateEditor({
  plugins: [BaseBasicBlocksPlugin, BaseBasicMarksPlugin, MarkdownPlugin],
});

const value = deserializeMd(
  editor,
  [
    '# Migration Note',
    '',
    'Move legacy content into **Plate** format.',
  ].join('\n')
);

const markdown = serializeMd(editor, { value });

console.info(markdown);
```

### Transform Content

Use transforms for migrations and bulk cleanup. Pass `at: []` when the operation
should scan the whole document.

```ts showLineNumbers title="scripts/normalize-headings.ts"
import type { Value } from 'platejs';

import {
  BaseBasicBlocksPlugin,
  BaseBasicMarksPlugin,
} from '@platejs/basic-nodes';
import { MarkdownPlugin, serializeMd } from '@platejs/markdown';
import { createSlateEditor } from 'platejs';

export function normalizeHeadings(value: Value) {
  const editor = createSlateEditor({
    plugins: [BaseBasicBlocksPlugin, BaseBasicMarksPlugin, MarkdownPlugin],
    value,
  });

  editor.tf.setNodes(
    { type: 'h2' },
    {
      at: [],
      match: (node) => 'type' in node && node.type === 'h1',
    }
  );

  editor.tf.insertNodes(
    [{ children: [{ text: 'Imported from the legacy CMS.' }], type: 'p' }],
    { at: [editor.children.length] }
  );

  return {
    markdown: serializeMd(editor),
    text: editor.api.string([]),
    value: editor.children,
  };
}
```

</Steps>

## Runtime Boundaries

| Runtime | Import from | Use for |
| --- | --- | --- |
| Node.js scripts | `platejs`, `@platejs/*` | Migration, validation, serialization, search indexing. |
| React editors | `platejs/react`, `@platejs/*/react` | Editable UI, hooks, rendered components, toolbar behavior. |
| Static rendering | `platejs/static` | Server-rendered read-only content. |

<Callout type="info">
  Plugin packages can expose both base and React entrypoints. In Node.js, choose
  the base entrypoint even when the same feature has React components for the
  browser editor.
</Callout>

## API Reference

| API | Package | Notes |
| --- | --- | --- |
| `createSlateEditor` | `platejs` | Creates a non-React editor instance. |
| `editor.api.string([])` | `platejs` | Reads text from the whole document. |
| `editor.tf.setNodes` | `platejs` | Updates matching nodes. Use `at: []` for document-wide transforms. |
| `editor.tf.insertNodes` | `platejs` | Inserts nodes at a path. |
| `deserializeMd` | `@platejs/markdown` | Converts Markdown into a Plate value. |
| `serializeMd` | `@platejs/markdown` | Converts the editor value or an explicit `value` option to Markdown. |

## Next Steps

| Task | Guide |
| --- | --- |
| Serialize to Markdown | [Markdown](/docs/markdown) |
| Serialize to HTML | [HTML](/docs/html) |
| Render read-only content | [Static Rendering](/docs/static) |
| Query editor state | [Editor API](/docs/api/slate/editor-api) |
| Apply transforms | [Editor Transforms](/docs/api/slate/editor-transforms) |

Done. You now have a server-safe Plate runtime that can power migration scripts,
validation jobs, and content serialization.


# Plate UI

Source: https://platejs.org/docs/installation/plate-ui

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Plate UI
description: Install, customize, and sync copied Plate UI components.
---

Plate UI is the copied component layer for Plate. Use the shadcn CLI for the
fastest setup, or install components manually when you need more control.

## CLI Installation (Recommended)

This is the fastest way to integrate Plate UI's core dependencies and base styles.

<Steps>

### Install Plate UI

<Callout type="info">
  If you are not using Next.js, refer to the official [shadcn/ui installation guides](https://ui.shadcn.com/docs/installation) for your specific framework before proceeding.
</Callout>

```bash
npx shadcn@latest add @plate/plate-ui
```

### Basic Usage 

With Plate UI's core installed, proceed to the guide specific to your framework:

*   **[Next.js Guide](./next)** - For server-side rendered applications (Next, Remix, etc.)
*   **[React Guide](./react)** - For single-page applications (Vite, React Router, etc.)

</Steps>

## Manual Installation

If you prefer a step-by-step approach or are not using the shadcn CLI, follow these steps:

<Steps>

### Install Plate

```bash
npm install platejs
```

<Callout type="note" title="Plugin Dependencies">
  When manually installing Plate, you'll need to add the specific packages for each plugin you want to use. For example, if you want to use the `AIMenu` component, you would need `@platejs/ai` and its dependencies. Check each component's documentation for its required packages, or use the CLI to automatically install the required packages.
</Callout>

### Configure CSS Variables

Add the following CSS variables to your global stylesheet:

```css title="app/globals.css"
:root {
  /* Base brand color for Plate UI components */
  --brand: oklch(0.623 0.214 259.815);
}

.dark {
  --brand: oklch(0.707 0.165 254.624);
}
```

### Add Components

With Plate UI's core installed, you can now add individual Plate UI components to build your editor interface. For example, to add the `FixedToolbar` and a `MarkToolbarButton`:

```bash
npx shadcn@latest add @plate/fixed-toolbar @plate/mark-toolbar-button
```

Import and use them in your editor:

```tsx showLineNumbers title="components/editor.tsx"
import { Plate } from "platejs/react";
import { FixedToolbar } from "@/components/ui/fixed-toolbar";
import { MarkToolbarButton } from "@/components/ui/mark-toolbar-button";
// ... other imports

export function MyEditor() {
  // ... editor setup
  return (
    <Plate editor={editor}>
      <FixedToolbar>
        <MarkToolbarButton nodeType="bold" tooltip="Bold">B</MarkToolbarButton>
        {/* ... other toolbar buttons ... */}
      </FixedToolbar>
      {/* ... Editor component ... */}
    </Plate>
  );
}
```

Explore the available [UI Components](/docs/components) and [Plugin Components](/docs/plugin-components) to customize your editor nodes (like paragraphs, headings, etc.) and build a feature-rich editing experience.

### Basic Usage 

With Plate UI's core installed, proceed to the guide specific to your framework:

*   **[Next.js Guide](./next)** - For server-side rendered applications (Next, Remix, etc.)
*   **[React Guide](./react)** - For single-page applications (Vite, React Router, etc.)

</Steps>

## Sync copied files

Plate UI components live in your app after installation. Use this workflow when
an agent needs to merge upstream registry file changes into local copies while
keeping app-specific edits.

For release review, use [Releases](/docs/releases). For scoped sync data, use
the raw registry JSON.

<Steps>

### Install the skill

```bash
npx skills add sync-plate-ui
```

### Pick the JSON source

Use the index for ordered update events. Use the component map when you need the
events for one copied registry item.

- [Index JSON](/registry/changelog/index.json)
- [Components JSON](/registry/changelog/components.json)

### Prompt your agent

```text
Use sync-plate-ui to sync code-block-node from:
https://platejs.org/registry/changelog/index.json
```

</Steps>

### Agent contract

- Use `/registry/changelog/index.json` for ordered Plate UI update events.
- Use `/registry/changelog/components.json` to find events by registry item.
- Open event JSON for the PR, release dependency, target files, and migration
  notes.
- Merge upstream file changes into the app copy; keep intentional local changes.

## Component Types

When installing Plate UI components, you'll encounter different types of components with consistent naming patterns. Here's what they mean:

### Feature Kits

Feature kits are the easiest way to add complete functionality to your editor. They bundle all necessary plugin configurations, UI components (including node renderers and toolbar items), and their underlying npm dependencies for a specific feature.

```bash
# Install the complete AI feature suite, including configuration and UI
npx shadcn@latest add @plate/ai-kit

# Install drag and drop functionality with all its parts
npx shadcn@latest add @plate/dnd-kit
```

<Callout type="note">
  When in doubt about what individual components you need, start with a feature kit. It's designed to provide a working feature out-of-the-box. You can always customize or remove parts later.
</Callout>

### Components

#### Node Components

These components are responsible for rendering specific types of content (elements or leaves) in your editor. If you need to create your own or customize existing ones, see the [Plugin Components guide](/docs/plugin-components).

```bash
# Install the component for rendering blockquotes
npx shadcn@latest add @plate/blockquote-node

# Install the component for rendering code text
npx shadcn@latest add @plate/code-node
```

#### Toolbar Components

Toolbar components add interactive controls like buttons and dropdowns to your editor's toolbar.

```bash
# Add an alignment dropdown for your toolbar
npx shadcn@latest add @plate/align-toolbar-button

# Add a toolbar button for AI features
npx shadcn@latest add @plate/ai-toolbar-button

# Add a color picker dropdown for your toolbar
npx shadcn@latest add @plate/font-color-toolbar-button
```

#### Other Components

Finally, Plate UI includes more advanced editor components as overlays, menus, block wrappers, etc.

```bash
# Install a menu for AI features
npx shadcn@latest add @plate/ai-menu

# Install a draggable component for reordering blocks
npx shadcn@latest add @plate/block-draggable
```

These components are typically included as part of their respective Feature Kits but can be installed individually for custom setups.

### Editor Templates

These are pre-configured editor setups, often tailored for specific use cases or as a comprehensive starting point. You can explore all available [Editor Templates](/editors).

```bash
# Install an AI-enabled editor template
npx shadcn@latest add @plate/editor-ai

# Install a basic editor template
npx shadcn@latest add @plate/editor-basic
```

### API Routes

These items provide server-side components or API route handlers necessary for certain features.

```bash
# Install AI-related API routes
npx shadcn@latest add @plate/ai-api

# Install file upload API routes (e.g., for UploadThing)
npx shadcn@latest add @plate/media-uploadthing-api
```

### Documentation

Documentation files for various Plate features, guides, and API references can also be added to your local project. This is especially useful for keeping version-specific documentation alongside your code and for providing context to AI tools through MCP. Learn more about [setting up local documentation](/docs/installation/docs).

```bash
# Add AI documentation
npx shadcn@latest add @plate/ai-docs

# Add Plate Plugin documentation
npx shadcn@latest add @plate/plugin-docs
```

These items consists of Markdown files, which can be integrated into your own documentation system or made available for local search and AI consumption.


# React

Source: https://platejs.org/docs/installation/react

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: React
description: Install and configure Plate UI for React
---

<Callout type="warning" title="Prerequisites">
  Before you begin, ensure you have installed and configured [shadcn/ui](https://ui.shadcn.com/docs/installation) (adapted for your framework, e.g., Vite) and [Plate UI](/docs/installation/plate-ui).
</Callout>

This guide walks you through incrementally building a Plate editor in your project.

<Steps>

### Create Your First Editor

Start by adding the core [Editor](/docs/components/editor) component to your project:

```bash
npx shadcn@latest add @plate/editor
```

Next, create a basic editor in your main application file (e.g. `src/App.tsx`). This example sets up a simple editor within an `EditorContainer`.

```tsx showLineNumbers title="src/App.tsx"
import { Plate, usePlateEditor } from 'platejs/react';

import { Editor, EditorContainer } from '@/components/ui/editor';

export default function App() {
  const editor = usePlateEditor(); // Initializes the editor instance

  return (
    <Plate editor={editor}>      {/* Provides editor context */}
      <EditorContainer>         {/* Styles the editor area */}
        <Editor placeholder="Type your amazing content here..." />
      </EditorContainer>
    </Plate>
  );
}
```

<Callout type="info">
  `usePlateEditor` creates a memoized editor instance, ensuring stability across re-renders. For a non-memoized version, use `createPlateEditor`.
</Callout>

[installation-next-01-editor-demo registry content](https://platejs.org/r/installation-next-01-editor-demo)

### Adding Basic Marks

Enhance your editor with text formatting. Add the **Basic Nodes Kit**, [FixedToolbar](/docs/components/fixed-toolbar) and [MarkToolbarButton](/docs/components/mark-toolbar-button) components:

```bash
npx shadcn@latest add @plate/basic-nodes-kit @plate/fixed-toolbar @plate/mark-toolbar-button
```

<Callout type="info">
  The `basic-nodes-kit` includes all the basic plugins (bold, italic, underline, headings, blockquotes, etc.) and their components that we'll use in the following steps.
</Callout>

Update your `src/App.tsx` to include these components and the basic mark plugins.
This example adds bold, italic, and underline functionality.

```tsx showLineNumbers title="src/App.tsx" {2,4-8,15-16,18-31,35-36,41-45}
import * as React from 'react';
import type { Value } from 'platejs';

import {
  BoldPlugin,
  ItalicPlugin,
  UnderlinePlugin,
} from '@platejs/basic-nodes/react';
import {
  Plate,
  usePlateEditor,
} from 'platejs/react';

import { Editor, EditorContainer } from '@/components/ui/editor';
import { FixedToolbar } from '@/components/ui/fixed-toolbar';
import { MarkToolbarButton } from '@/components/ui/mark-toolbar-button';

const initialValue: Value = [
  {
    type: 'p',
    children: [
      { text: 'Hello! Try out the ' },
      { text: 'bold', bold: true },
      { text: ', ' },
      { text: 'italic', italic: true },
      { text: ', and ' },
      { text: 'underline', underline: true },
      { text: ' formatting.' },
    ],
  },
];

export default function App() {
  const editor = usePlateEditor({
    plugins: [BoldPlugin, ItalicPlugin, UnderlinePlugin], // Add the mark plugins
    value: initialValue,         // Set initial content
  });

  return (
    <Plate editor={editor}>
      <FixedToolbar className="justify-start rounded-t-lg">
        <MarkToolbarButton nodeType="bold" tooltip="Bold (⌘+B)">B</MarkToolbarButton>
        <MarkToolbarButton nodeType="italic" tooltip="Italic (⌘+I)">I</MarkToolbarButton>
        <MarkToolbarButton nodeType="underline" tooltip="Underline (⌘+U)">U</MarkToolbarButton>
      </FixedToolbar>
      <EditorContainer>
        <Editor placeholder="Type your amazing content here..." />
      </EditorContainer>
    </Plate>
  );
}
```

[installation-next-02-marks-demo registry content](https://platejs.org/r/installation-next-02-marks-demo)

### Adding Basic Elements

Introduce block-level elements like headings and blockquotes with custom components.

```tsx showLineNumbers title="src/App.tsx" {5,7-9,18,21,23,26-33,50-53,61-65}
import * as React from 'react';
import type { Value } from 'platejs';

import {
  BlockquotePlugin,
  BoldPlugin,
  H1Plugin,
  H2Plugin,
  H3Plugin,
  ItalicPlugin,
  UnderlinePlugin,
} from '@platejs/basic-nodes/react';
import {
  Plate,
  usePlateEditor,
} from 'platejs/react';

import { BlockquoteElement } from '@/components/ui/blockquote-node';
import { Editor, EditorContainer } from '@/components/ui/editor';
import { FixedToolbar } from '@/components/ui/fixed-toolbar';
import { H1Element, H2Element, H3Element } from '@/components/ui/heading-node';
import { MarkToolbarButton } from '@/components/ui/mark-toolbar-button';
import { ToolbarButton } from '@/components/ui/toolbar'; // Generic toolbar button

const initialValue: Value = [
  {
    children: [{ text: 'Title' }],
    type: 'h3',
  },
  {
    children: [
      {
        children: [{ text: 'This is a quote.' }],
        type: 'p',
      },
    ],
    type: 'blockquote',
  },
  {
    children: [
      { text: 'With some ' },
      { bold: true, text: 'bold' },
      { text: ' text for emphasis!' },
    ],
    type: 'p',
  },
];

export default function App() {
  const editor = usePlateEditor({
    plugins: [
      BoldPlugin,
      ItalicPlugin,
      UnderlinePlugin,
      H1Plugin.withComponent(H1Element),
      H2Plugin.withComponent(H2Element),
      H3Plugin.withComponent(H3Element),
      BlockquotePlugin.withComponent(BlockquoteElement),
    ],
    value: initialValue,
  });

  return (
    <Plate editor={editor}>
      <FixedToolbar className="flex justify-start gap-1 rounded-t-lg">
        {/* Element Toolbar Buttons */}
        <ToolbarButton onClick={() => editor.tf.h1.toggle()}>H1</ToolbarButton>
        <ToolbarButton onClick={() => editor.tf.h2.toggle()}>H2</ToolbarButton>
        <ToolbarButton onClick={() => editor.tf.h3.toggle()}>H3</ToolbarButton>
        <ToolbarButton onClick={() => editor.tf.blockquote.toggle()}>Quote</ToolbarButton>
        {/* Mark Toolbar Buttons */}
        <MarkToolbarButton nodeType="bold" tooltip="Bold (⌘+B)">B</MarkToolbarButton>
        <MarkToolbarButton nodeType="italic" tooltip="Italic (⌘+I)">I</MarkToolbarButton>
        <MarkToolbarButton nodeType="underline" tooltip="Underline (⌘+U)">U</MarkToolbarButton>
      </FixedToolbar>
      <EditorContainer>
        <Editor placeholder="Type your amazing content here..." />
      </EditorContainer>
    </Plate>
  );
}
```

[installation-next-03-elements-demo registry content](https://platejs.org/r/installation-next-03-elements-demo)

<Callout type="info" title="Component Registration">
  Notice how we use `Plugin.withComponent(Component)` to register components with their respective plugins. This is the recommended approach for associating React components with Plate plugins.

  For a quicker start with common plugins and components pre-configured, use the `editor-basic` block:
  ```bash
  npx shadcn@latest add @plate/editor-basic
  ```
  This handles much of the boilerplate for you.
</Callout>

### Handling Editor Value

To make the editor content persistent, let's integrate `localStorage` to save and load the editor's value.

```tsx showLineNumbers title="src/App.tsx" {55-58,64-66,76-82}
import * as React from 'react';
import type { Value } from 'platejs';

import {
  BlockquotePlugin,
  BoldPlugin,
  H1Plugin,
  H2Plugin,
  H3Plugin,
  ItalicPlugin,
  UnderlinePlugin,
} from '@platejs/basic-nodes/react';
import {
  Plate,
  usePlateEditor,
} from 'platejs/react';

import { BlockquoteElement } from '@/components/ui/blockquote-node';
import { Editor, EditorContainer } from '@/components/ui/editor';
import { FixedToolbar } from '@/components/ui/fixed-toolbar';
import { H1Element, H2Element, H3Element } from '@/components/ui/heading-node';
import { MarkToolbarButton } from '@/components/ui/mark-toolbar-button';
import { ToolbarButton } from '@/components/ui/toolbar';

const initialValue: Value = [
  {
    children: [{ text: 'Title' }],
    type: 'h3',
  },
  {
    children: [
      {
        children: [{ text: 'This is a quote.' }],
        type: 'p',
      },
    ],
    type: 'blockquote',
  },
  {
    children: [
      { text: 'With some ' },
      { bold: true, text: 'bold' },
      { text: ' text for emphasis!' },
    ],
    type: 'p',
  },
];

export default function App() {
  const editor = usePlateEditor({
    plugins: [
      BoldPlugin,
      ItalicPlugin,
      UnderlinePlugin,
      H1Plugin.withComponent(H1Element),
      H2Plugin.withComponent(H2Element),
      H3Plugin.withComponent(H3Element),
      BlockquotePlugin.withComponent(BlockquoteElement),
    ],
    value: () => {
      const savedValue = localStorage.getItem('installation-react-demo');
      return savedValue ? JSON.parse(savedValue) : initialValue;
    },
  });

  return (
    <Plate
      editor={editor}
      onChange={({ value }) => {
        localStorage.setItem('installation-react-demo', JSON.stringify(value));
      }}
    >
      <FixedToolbar className="flex justify-start gap-1 rounded-t-lg">
        <ToolbarButton onClick={() => editor.tf.h1.toggle()}>H1</ToolbarButton>
        <ToolbarButton onClick={() => editor.tf.h2.toggle()}>H2</ToolbarButton>
        <ToolbarButton onClick={() => editor.tf.h3.toggle()}>H3</ToolbarButton>
        <ToolbarButton onClick={() => editor.tf.blockquote.toggle()}>Quote</ToolbarButton>
        <MarkToolbarButton nodeType="bold" tooltip="Bold (⌘+B)">B</MarkToolbarButton>
        <MarkToolbarButton nodeType="italic" tooltip="Italic (⌘+I)">I</MarkToolbarButton>
        <MarkToolbarButton nodeType="underline" tooltip="Underline (⌘+U)">U</MarkToolbarButton>
        <div className="flex-1" />
        <ToolbarButton
          className="px-2"
          onClick={() => editor.tf.setValue(initialValue)}
        >
          Reset
        </ToolbarButton>
      </FixedToolbar>
      <EditorContainer>
        <Editor placeholder="Type your amazing content here..." />
      </EditorContainer>
    </Plate>
  );
}
```

[installation-next-demo registry content](https://platejs.org/r/installation-next-demo)

### Next Steps

Congratulations! You've built a foundational Plate editor in your project.

To further enhance your editor:

*   **Explore Components:** Discover [Toolbars, Menus, Node components](/docs/components), and more.
*   **Add Plugins:** Integrate features like [Tables](/docs/plugins/table), [Mentions](/docs/plugins/mention), [AI](/docs/plugins/ai), or [Markdown](/docs/plugins/markdown).
*   **Use Editor Blocks:** Quickly set up pre-configured editors:
    *   Basic editor: `npx shadcn@latest add @plate/editor-basic`
    *   AI-powered editor: `npx shadcn@latest add @plate/editor-ai`
*   **Learn More:**
    *   [Editor Configuration](/docs/editor)
    *   [Plugin Configuration](/docs/plugin)
    *   [Plugin Components](/docs/plugin-components)

</Steps>


# RSC

Source: https://platejs.org/docs/installation/rsc

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: RSC
description: Install and configure Plate for React Server Components.
---

Use Plate in React Server Components when you need to render read-only editor content or generate HTML on the server. Interactive editors still belong in client components with `platejs/react`. This guide shows the server-safe static editor path, HTML serialization, and the boundary with Node-only processing.

## RSC Setup

<Callout type="warning" title="Use static imports">
  Do not import `platejs/react` or `@platejs/*/react` from a Server Component.
  Use `platejs/static`, `platejs`, and base `@platejs/*` entrypoints.
</Callout>

<Steps>

### Install the Base Kit

Install the copied base editor kit when you want Plate UI static components and
the default serializer plugins.

```bash
npx shadcn@latest add @plate/editor-base-kit
```

The `editor-base-kit` item installs `BaseEditorKit`, static node components, and
the `editor-static` UI component used by server rendering.

### Render Static Content

Create a static editor in the Server Component and render it with
`<PlateStatic>`.

```tsx title="app/documents/page.tsx" showLineNumbers
import type { Value } from 'platejs';
import { createStaticEditor, PlateStatic } from 'platejs/static';

import { BaseEditorKit } from '@/components/editor/editor-base-kit';

const value: Value = [
  {
    children: [{ text: 'Server-rendered document' }],
    type: 'h1',
  },
  {
    children: [{ text: 'This content is rendered without editor state.' }],
    type: 'p',
  },
];

export default function DocumentsPage() {
  const editor = createStaticEditor({
    plugins: BaseEditorKit,
    value,
  });

  return <PlateStatic editor={editor} />;
}
```

### Serialize HTML

Use `serializeHtml` when a route needs an HTML string instead of React output.

```tsx title="app/api/document-html/route.ts" showLineNumbers
import type { Value } from 'platejs';
import { createStaticEditor, serializeHtml } from 'platejs/static';

import { BaseEditorKit } from '@/components/editor/editor-base-kit';
import { EditorStatic } from '@/components/ui/editor-static';

const value: Value = [
  {
    children: [{ text: 'Exported document' }],
    type: 'h1',
  },
  {
    children: [{ text: 'This HTML is generated on the server.' }],
    type: 'p',
  },
];

export async function GET() {
  const editor = createStaticEditor({
    plugins: BaseEditorKit,
    value,
  });

  const html = await serializeHtml(editor, {
    editorComponent: EditorStatic,
  });

  return new Response(html, {
    headers: { 'content-type': 'text/html; charset=utf-8' },
  });
}
```

### Use Base Packages Without Plate UI

If you only need data transforms or Markdown IO, use the Node.js path instead
of static React rendering.

```bash
npm install platejs @platejs/basic-nodes @platejs/markdown
```

That path uses `createSlateEditor` from `platejs` and does not need copied UI
components.

</Steps>

## Runtime Boundaries

| Runtime | Import from | Use for |
| --- | --- | --- |
| Server Component | `platejs/static` | Read-only React output with `<PlateStatic>`. |
| Route handler | `platejs/static` | HTML export with `serializeHtml`. |
| Node script | `platejs`, `@platejs/*` | Validation, migration, Markdown IO. |
| Client editor | `platejs/react`, `@platejs/*/react` | Editable UI, hooks, toolbar interactions. |

<Callout type="info">
  `createStaticEditor` includes the static `ViewPlugin` before your plugins.
  Use it for rendered output. Use `createSlateEditor` when the script only
  reads or transforms a value.
</Callout>

## Next Steps

| Task | Guide |
| --- | --- |
| Learn the static renderer. | [Static Rendering](/docs/static) |
| Generate HTML. | [HTML](/docs/html) |
| Read or write Markdown. | [Markdown](/docs/markdown) |
| Transform content without React. | [Node.js](/docs/installation/node) |

Done. Your Server Component can render Plate content without shipping the
interactive editor runtime.


# From Slate to Plate

Source: https://platejs.org/docs/migration/slate-to-plate

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: From Slate to Plate
description: Move a Slate React editor to Plate's editor, plugin, and rendering model.
---

Plate keeps Slate'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

```bash
npm install platejs
```

Use feature packages only for the nodes, marks, or behavior you add to the
editor. Plate UI users should start with [Plate UI](/docs/installation/plate-ui)
instead of rebuilding every component by hand.

## Migration Map

| Slate surface | Plate surface |
| --- | --- |
| `createEditor()` plus `withReact()` | `usePlateEditor()` in React components, or `createPlateEditor()` in factories and tests. |
| `<Slate>` plus `<Editable>` | `<Plate>` plus `<PlateContent>`. |
| `renderElement` / `renderLeaf` switch statements | Plugin components through `.withComponent()` or `node.component`. |
| `withX(editor)` plugin functions | `.overrideEditor()` for wrappers, `.extend*()` for new APIs and transforms. |
| Top-level event handlers on `Editable` | Plugin `handlers` or `shortcuts`. |
| `Transforms.*` imports | `editor.tf.*` transforms. |
| `Editor.*` imports | `editor.api.*` queries. |

## Editor Shell

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

```tsx title="components/editor.tsx" showLineNumbers
'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.

```ts title="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.

```tsx title="components/editor/paragraph-plugin.tsx" showLineNumbers
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 Slate document stores a custom type like `paragraph`, keep that type on the plugin.

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

## Custom Behavior

Use `.overrideEditor()` when the Slate plugin wrapped an existing editor method.

```tsx title="components/editor/limit-exclamation-plugin.tsx" showLineNumbers
import { createPlatePlugin } from 'platejs/react';

export const LimitExclamationPlugin = createPlatePlugin({
  key: 'limitExclamation',
}).overrideEditor(({ tf: { insertText } }) => ({
  transforms: {
    insertText(text, options) {
      insertText(text === '!' ? '.' : text, options);
    },
  },
}));
```

Use `.extendEditorApi()` or `.extendEditorTransforms()` when the plugin adds a new method.

```tsx title="components/editor/signature-plugin.tsx" showLineNumbers
import { createPlatePlugin } from 'platejs/react';

export const SignaturePlugin = createPlatePlugin({
  key: 'signature',
}).extendEditorTransforms(({ editor }) => ({
  insertSignature() {
    editor.tf.insertText(' - Plate');
  },
}));
```

## Handlers And Shortcuts

Move editor events into the plugin that owns the behavior.

```tsx title="components/editor/tab-plugin.tsx" showLineNumbers
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.

```tsx title="components/editor/save-plugin.tsx" showLineNumbers
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 Slate-style direct methods for compatibility, but plugin code should use the namespaced API and transform surfaces.

```ts title="editor-commands.ts"
editor.tf.toggleMark('bold');
editor.tf.insertText('Hello');

const text = editor.api.string([]);

if (editor.selection) {
  const isStart = editor.api.isStart(editor.selection.anchor, []);
}
```

## Headless Code

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

```ts title="lib/headless-editor.ts"
import { createSlateEditor } from 'platejs';

export const editor = createSlateEditor({
  value: [
    {
      children: [{ text: 'Headless document.' }],
      type: 'p',
    },
  ],
});
```

## Related

- [Editor](/docs/editor) for editor creation options.
- [Plugin Components](/docs/plugin-components) for replacing `renderElement` and `renderLeaf`.
- [Plugin Methods](/docs/plugin-methods) for `.configure()`, `.extend*()`, and `.overrideEditor()`.
- [Plugin Shortcuts](/docs/plugin-shortcuts) for keyboard command wiring.


# Major Releases up to v48

Source: https://platejs.org/docs/migration/v48

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Major Releases up to v48
description: Historical upgrade notes for Plate apps on v48 and earlier.
---

This is the compatibility archive for apps still on `@udecode/*` packages
through Plate v48. Use it to identify the breaking-change family, then follow
the current docs for the target API.

## Start Here

<Callout type="info" title="Current release notes">
  Use [Releases](/docs/releases) for v49 and later. Use
  [From Slate to Plate](/docs/migration/slate-to-plate) when the source editor
  is plain Slate rather than an older Plate app.
</Callout>

# 48.0.0

## @udecode/plate-core@48.0.0

- [#4281](https://github.com/udecode/plate/pull/4281) by [@zbeyens](https://github.com/zbeyens) –

  - `PlateElement`, `PlateLeaf` and `PlateText` HTML attributes are moved from top-level props to `attributes` prop, except `className`, `style` and `as`. Migration:

  ```tsx
  // From
  <PlateElement
    {...props}
    ref={ref}
    contentEditable={false}
  >
    {children}
  </PlateElement>

  // To
  <PlateElement
    {...props}
    ref={ref}
    attributes={{
      ...props.attributes,
      contentEditable: false,
    }}
  >
    {children}
  </PlateElement>
  ```

  - Remove `nodeProps` prop from `PlateElement`, `PlateLeaf`, `PlateText`. It has been merged into `attributes` prop.
  - Plugin `node.props` should return the props directly instead of inside `nodeProps` object. Migration:

  ```ts
  // From
  node: {
    props: ({ element }) => ({
      nodeProps: {
        colSpan: element?.attributes?.colspan,
        rowSpan: element?.attributes?.rowspan,
      },
    });
  }

  // To
  node: {
    props: ({ element }) => ({
      colSpan: element?.attributes?.colspan,
      rowSpan: element?.attributes?.rowspan,
    });
  }
  ```

  - Remove `asChild` prop from `PlateElement`, `PlateLeaf`, `PlateText`. Use `as` prop instead.
  - Remove `elementToAttributes`, `leafToAttributes`, `textToAttributes` props from `PlateElement`, `PlateLeaf`, `PlateText`.
  - Remove `DefaultElement`, `DefaultLeaf`, `DefaultText`. Use `PlateElement`, `PlateLeaf`, `PlateText` instead.
  - Types: remove `PlateRenderElementProps`, `PlateRenderLeafProps`, `PlateRenderTextProps`. Use `PlateElementProps`, `PlateLeafProps`, `PlateTextProps` instead.

## @udecode/plate-utils@48.0.0

- [#4281](https://github.com/udecode/plate/pull/4281) by [@zbeyens](https://github.com/zbeyens) –
  - Moved `PlateElement`, `PlateLeaf`, `PlateText` to `@udecode/plate-core`. No migration needed if you're importing from `@udecode/plate`.

## @udecode/plate-yjs@48.0.0

- [#4225](https://github.com/udecode/plate/pull/4225) by [@bbyiringiro](<https://github.com/[bbyiringiro](https://github.com/bbyiringiro)>) –

  - Add multi-provider support for improved collaboration: now supports both Hocuspocus and WebRTC simultaneously using a shared Y.Doc.
    - **Migration**: Replace `hocuspocusProviderOptions` with the new `providers` array. See examples below.

  **Before:**

  ```tsx
  YjsPlugin.configure({
    options: {
      cursorOptions: {
        /* ... */
      },
      hocuspocusProviderOptions: {
        url: 'wss://hocuspocus.example.com',
        name: 'document-1',
        // ... other Hocuspocus options
      },
    },
  });
  ```

  **After (Hocuspocus only):**

  ```tsx
  YjsPlugin.configure({
    options: {
      cursors: {
        /* ... */
      },
      providers: [
        {
          type: 'hocuspocus',
          options: {
            url: 'wss://hocuspocus.example.com',
            name: 'document-1',
            // ... other Hocuspocus options
          },
        },
      ],
    },
  });
  ```

  **After (Hocuspocus + WebRTC):**

  ```tsx
  YjsPlugin.configure({
    options: {
      cursors: {
        /* ... */
      },
      providers: [
        {
          type: 'hocuspocus',
          options: {
            url: 'wss://hocuspocus.example.com',
            name: 'document-1',
          },
        },
        {
          type: 'webrtc',
          options: {
            roomName: 'document-1',
            // signaling: ['wss://signaling.example.com'], // Optional
          },
        },
      ],
    },
  });
  ```

  - Introduces `UnifiedProvider` interface that enables custom provider implementations (e.g., IndexedDB for offline persistence).
  - Renamed `cursorOptions` to `cursors`.
  - Merged `yjsOptions` into `options`.
    - **Migration**: Move options previously under `yjsOptions` directly into the main `options` object.
  - Removed `YjsAboveEditable`. You should now call `init` and `destroy` manually:

  ```tsx
  React.useEffect(() => {
    if (!mounted) return;

    // Initialize Yjs connection and sync
    editor.getApi(YjsPlugin).yjs.init({
      id: roomName, // Or your document identifier
      value: INITIAL_VALUE, // Your initial editor content
    });

    // Destroy connection on component unmount
    return () => {
      editor.getApi(YjsPlugin).yjs.destroy();
    };
  }, [editor, mounted, roomName]); // Add relevant dependencies
  ```

# 47.0.0

## @udecode/plate-markdown

- [#4174](https://github.com/udecode/plate/pull/4174) by [@felixfeng33](https://github.com/felixfeng33) – #### New Features

  - Added support for math type deserialization
  - Added default underline mark serialization as `<u>underline</u>`
  - Improved serialization process:
    - Now uses a two-step process: `slate nodes => MDAST nodes => markdown string`
    - Previously: direct conversion from Slate nodes to markdown string
    - Results in more reliable and robust serialization
  - New node filtering options:
    - `allowedNodes`: Whitelist specific nodes
    - `disallowedNodes`: Blacklist specific nodes
    - `allowNode`: Custom function to filter nodes
  - New `rules` option for customizing serialization and deserialization rules, including **custom mdx** support
  - New `remarkPlugins` option to use [remark plugins](https://github.com/remarkjs/remark/blob/main/doc/plugins.md#list-of-plugins)

  #### Breaking Changes

  **Plugin Options**

  Removed options:

  - `elementRules` use `rules` instead
  - `textRules` use `rules` instead
  - `indentList` now automatically detects if the IndentList plugin is used
  - `splitLineBreaks` deserialize only

  ##### Deserialization

  - Removed `elementRules` and `textRules` options
    - Use `rules.key.deserialize` instead
    - See [nodes documentation](https://platejs.org/docs/markdown)

  Example migration:

  ```tsx
  export const markdownPlugin = MarkdownPlugin.configure({
    options: {
      disallowedNodes: [SuggestionPlugin.key],
      rules: {
        // For textRules
        [BoldPlugin.key]: {
          mark: true,
          deserialize: (mdastNode) => ({
            bold: true,
            text: node.value || '',
          }),
        },
        // For elementRules
        [EquationPlugin.key]: {
          deserialize: (mdastNode, options) => ({
            children: [{ text: '' }],
            texExpression: node.value,
            type: EquationPlugin.key,
          }),
        },
      },
      remarkPlugins: [remarkMath, remarkGfm],
    },
  });
  ```

  - Removed processor in `editor.api.markdown.deserialize`
    - Use `remarkPlugins` instead

  ##### Serialization

  - Removed `serializeMdNodes`
    - Use `editor.markdown.serialize({ value: nodes })` instead
  - Removed `SerializeMdOptions` due to new serialization process
    - Previous process: `slate nodes => md`
    - New process: `slate nodes => md-ast => md`
  - Removed options:
    - `nodes`
    - `breakTag`
    - `customNodes`
    - `ignoreParagraphNewline`
    - `listDepth`
    - `markFormats`
    - `ulListStyleTypes`
    - `ignoreSuggestionType`

  Migration example for `SerializeMdOptions.customNodes` and `SerializeMdOptions.nodes`:

  ```tsx
  export const markdownPlugin = MarkdownPlugin.configure({
    options: {
      rules: {
        // Ignore all `insert` type suggestions
        [SuggestionPlugin.key]: {
          mark: true,
          serialize: (slateNode: TSuggestionText, options): mdast.Text => {
            const suggestionData = options.editor
              .getApi(SuggestionPlugin)
              .suggestion.suggestionData(node);

            return suggestionData?.type === 'insert'
              ? { type: 'text', value: '' }
              : { type: 'text', value: node.text };
          },
        },
        // For elementRules
        [EquationPlugin.key]: {
          serialize: (slateNode) => ({
            type: 'math',
            value: node.texExpression,
          }),
        },
      },
      remarkPlugins: [remarkMath, remarkGfm],
    },
  });
  ```

# 46.0.0

## @udecode/plate-code-block@46.0.0

- [#4122](https://github.com/udecode/plate/pull/4122) by [@zbeyens](https://github.com/zbeyens) – Migrated from `prismjs` to `highlight.js` + `lowlight` for syntax highlighting.

  - Fix highlighting multi-lines tokens. Before, line tokens were computed line by line. Now, it's computed once for the whole block.
  - Bundle size much lower.
  - `CodeBlockPlugin`: remove `prism` option. Use `lowlight` option instead:

  ```tsx
  import { all, createLowlight } from 'lowlight';

  const lowlight = createLowlight(all);

  CodeBlockPlugin.configure({
    options: {
      lowlight,
    },
  });
  ```

  - New option: `defaultLanguage`
  - Remove `syntax` option. Just omit `lowlight` option to disable syntax highlighting.
  - Remove `syntaxPopularFirst` option. Control this behavior in your own components.
  - Fix pasting code inside code blocks.
  - Remove `useCodeBlockCombobox`, `useCodeBlockElement`, `useCodeSyntaxLeaf`, `useToggleCodeBlockButton`. The logic has been moved to the components.

# 45.0.0

## @udecode/plate-comments@45.0.0

- [#4064](https://github.com/udecode/plate/pull/4064) by [@felixfeng33](https://github.com/felixfeng33) – This is a rewrite of the comments plugin removing UI logic (headless).

  **Plugin Options**

  - Removed configuration options from plugin options in favor of component-level control:
    - `options.comments`
    - `options.myUserId`
    - `options.users`

  **Components**

  - Removed legacy components:
    - `CommentDeleteButton`
    - `CommentEditActions`
    - `CommentEditButton`
    - `CommentEditCancelButton`
    - `CommentEditSaveButton`
    - `CommentEditTextarea`
    - `CommentNewSubmitButton`
    - `CommentNewTextarea`
    - `CommentResolveButton`
    - `CommentsPositioner`
    - `CommentUserName`

  **API**

  - Removed functions in favor of new API methods:
    - `findCommentNode` → `api.comment.node()`
    - `findCommentNodeById` → `api.comment.node({ id })`
    - `getCommentNodeEntries` → `api.comment.nodes()`
    - `getCommentNodesById` → `api.comment.nodes({ id })`
    - `removeCommentMark` → `tf.comment.remove()`
    - `unsetCommentNodesById` → `tf.comment.unsetMark({ id })`
  - Removed unused functions:
    - `getCommentFragment`
    - `getCommentUrl`
    - `getElementAbsolutePosition`
    - `getCommentPosition`
  - Updated `getCommentCount` to exclude draft comments

  **State Management**

  - Removed `CommentProvider` - users should implement their own state management – `block-discussion.tsx`
  - Moved `useHooksComments` to UI registry – `comments-plugin.tsx`
  - Removed hooks no longer needed with new UI:
    - `useActiveCommentNode`
    - `useCommentsResolved`
    - `useCommentAddButton`
    - `useCommentItemContent`
    - `useCommentLeaf`
    - `useCommentsShowResolvedButton`
    - `useFloatingCommentsContentState`
    - `useFloatingCommentsState`

  **Types**

  - Removed `CommentUser`
  - Moved `TComment` to UI registry – `comment.tsx`

## @udecode/plate-suggestion@45.0.0

- [#4064](https://github.com/udecode/plate/pull/4064) by [@felixfeng33](https://github.com/felixfeng33) – Note: This plugin is currently in an experimental phase and breaking changes may be introduced without a major version bump.

  - Add Suggestion UI
  - Remove: `findSuggestionNode` use `findSuggestionProps.ts` instead
  - Remove `addSuggestionMark.ts`
  - Remove `useHooksSuggestion.ts` as we've updated the activeId logic to no longer depend on useEditorSelector

# 44.0.1

## @udecode/plate-core@44.0.0

- [#4048](https://github.com/udecode/plate/pull/4048) by [@zbeyens](https://github.com/zbeyens) –

  - Support React 19
  - Upgraded to `zustand-x@6`
    - `eventEditorSelectors` -> `EventEditorStore.get`
    - `eventEditorActions` -> `EventEditorStore.set`
    - `useEventEditorSelectors` -> `useEventEditorValue(key)`
  - Upgraded to `jotai-x@2`
    - `usePlateEditorStore` -> `usePlateStore`
    - `usePlateActions` -> `usePlateSet`
    - Remove `editor.setPlateState`, use `usePlateSet` instead
    - `usePlateSelectors` -> `usePlateValue`
    - `usePlateStates` -> `usePlateState`
  - Moving plugin options hooks into standalone hooks to be compatible with React Compiler
    - `editor.useOption`, `ctx.useOption` -> `usePluginOption(plugin, key, ...args)`
    - `editor.useOptions`, `ctx.useOptions` -> `usePluginOption(plugin, 'state')`
    - New hook `usePluginOptions(plugin, selector)` to select plugin options (Zustand way).
  - We were supporting adding selectors to plugins using `extendOptions`. Those were mixed up with the options state, leading to potential conflicts and confusion.
    - The plugin method is renamed to `extendSelectors`
    - Selectors are now internally stored in `plugin.selectors` instead of `plugin.options`, but this does not change how you access those: using `editor.getOption(plugin, 'selectorName')`, `ctx.getOption('selectorName')` or above hooks.
    - Selector types are no longer in the 2nd generic type of `PluginConfig`, we're adding a 5th generic type for it.

  ```ts
  // Before:
  export type BlockSelectionConfig = PluginConfig<
    'blockSelection',
    { selectedIds?: Set<string>; } & BlockSelectionSelectors,
  >;

  // After:
  export type BlockSelectionConfig = PluginConfig<
    'blockSelection',
    { selectedIds?: Set<string>; },
    {}, // API
    {}, // Transforms
    BlockSelectionSelectors, // Selectors
  }>
  ```

## @udecode/plate-comments@44.0.0

- [#4048](https://github.com/udecode/plate/pull/4048) by [@zbeyens](https://github.com/zbeyens) – Upgrade to `jotai-x@2`. [Migration](https://github.com/udecode/jotai-x/blob/main/packages/jotai-x/CHANGELOG.md#211) needed only if you use `useCommentStore`

## @udecode/plate-media@44.0.0

- [#4048](https://github.com/udecode/plate/pull/4048) by [@zbeyens](https://github.com/zbeyens) – Upgrade to `zustand-x@2`. [Migration](https://github.com/udecode/zustand-x/blob/main/packages/zustand-x/CHANGELOG.md#600) needed only if you use one of these stores:

  - `ImagePreviewStore`
  - `FloatingMediaStore`

- [#4048](https://github.com/udecode/plate/pull/4048) by [@zbeyens](https://github.com/zbeyens) – Upgrade to `jotai-x@2`. [Migration](https://github.com/udecode/jotai-x/blob/main/packages/jotai-x/CHANGELOG.md#211) needed only if you use `usePlaceholderStore`

## @udecode/plate-resizable@44.0.0

- [#4048](https://github.com/udecode/plate/pull/4048) by [@zbeyens](https://github.com/zbeyens) – Upgrade to `jotai-x@2`. [Migration](https://github.com/udecode/jotai-x/blob/main/packages/jotai-x/CHANGELOG.md#211) needed only if you use `useResizableStore`

## @udecode/plate-table@44.0.0

- [#4048](https://github.com/udecode/plate/pull/4048) by [@zbeyens](https://github.com/zbeyens) – Move store state `selectedCells` and `selectedTables` from `useTableStore` to `TablePlugin` options store. This fixes the issue to get access to those state outside a table element (e.g. the toolbar)

- [#4048](https://github.com/udecode/plate/pull/4048) by [@zbeyens](https://github.com/zbeyens) – Upgrade to `jotai-x@2`. [Migration](https://github.com/udecode/jotai-x/blob/main/packages/jotai-x/CHANGELOG.md#211) needed only if you use `useTableStore`

# 43.0.0

No breaking changes. Upgraded all dependencies to the latest version.

# 42.0.1

## @udecode/plate-ai@42.0.0

- [#3920](https://github.com/udecode/plate/pull/3920) by [@zbeyens](https://github.com/zbeyens) – AI plugins are now experimental: pin the dependency to avoid breaking changes. No breaking changes for this release.

## @udecode/plate-common@42.0.0

- [#3920](https://github.com/udecode/plate/pull/3920) by [@zbeyens](https://github.com/zbeyens) – This package is now deprecated and will be renamed to `@udecode/plate`. Migration:

  - Remove `@udecode/plate-common` and install `@udecode/plate`
  - Replace all `'@udecode/plate-common'` with `'@udecode/plate'`,

## @udecode/plate-core@42.0.0

- [#3920](https://github.com/udecode/plate/pull/3920) by [@zbeyens](https://github.com/zbeyens) –

  - **Plugin `normalizeInitialValue`** now returns `void` instead of `Value`. When mutating nodes, keep their references (e.g., use `Object.assign` instead of spread).
  - **Editor methods have moved** to `editor.tf` and `editor.api`. They still exist at the top level for **slate backward compatibility**, but are no longer redundantly typed. If you truly need the top-level method types, extend your editor type with `LegacyEditorMethods` (e.g. `editor as Editor & LegacyEditorMethods`). Since these methods can be overridden by `extendEditor`, `with...`, or slate plugins, consider migrating to the following approaches:

    ```tsx
    // For overriding existing methods only:
    overrideEditor(({ editor, tf: { deleteForward }, api: { isInline } }) => ({
      transforms: {
        deleteForward(options) {
          // ...conditional override
          deleteForward(options);
        },
      },
      api: {
        isInline(element) {
          // ...conditional override
          return isInline(element);
        },
      },
    }));
    ```

  This was previously done in `extendEditor` using top-level methods, which still works but now throws a type error due to the move to `editor.tf/editor.api`. A workaround is to extend your editor with `LegacyEditorMethods`.

  **Why?** Having all methods at the top-level (next to `children`, `marks`, etc.) would clutter the editor interface. Slate splits transforms in three places (`editor`, `Editor`, and `Transforms`), which is also confusing. We've reorganized them into `tf` and `api` for better DX, but also to support transform-only middlewares in the future. This also lets us leverage `extendEditorTransforms`, `extendEditorApi`, and `overrideEditor` to modify those methods.

  Migration example:

  ```tsx
  // From:
  export const withInlineVoid: ExtendEditor = ({ editor }) => {
    const { isInline, isSelectable, isVoid, markableVoid } = editor;

    const voidTypes: string[] = [];
    const inlineTypes: string[] = [];

    editor.pluginList.forEach((plugin) => {
      if (plugin.node.isInline) {
        inlineTypes.push(plugin.node.type);
      }
      if (plugin.node.isVoid) {
        voidTypes.push(plugin.node.type);
      }
    });

    editor.isInline = (element) => {
      return inlineTypes.includes(element.type as any)
        ? true
        : isInline(element);
    };

    editor.isVoid = (element) => {
      return voidTypes.includes(element.type as any) ? true : isVoid(element);
    };

    return editor;
  };

  export const InlineVoidPlugin = createSlatePlugin({
    key: 'inlineVoid',
    extendEditor: withInlineVoid,
  });

  // After (using overrideEditor since we're only overriding existing methods):
  export const withInlineVoid: OverrideEditor = ({
    api: { isInline, isSelectable, isVoid, markableVoid },
    editor,
  }) => {
    const voidTypes: string[] = [];
    const inlineTypes: string[] = [];

    editor.pluginList.forEach((plugin) => {
      if (plugin.node.isInline) {
        inlineTypes.push(plugin.node.type);
      }
      if (plugin.node.isVoid) {
        voidTypes.push(plugin.node.type);
      }
    });

    return {
      api: {
        isInline(element) {
          return inlineTypes.includes(element.type as any)
            ? true
            : isInline(element);
        },
        isVoid(element) {
          return voidTypes.includes(element.type as any)
            ? true
            : isVoid(element);
        },
      },
    };
  };

  export const InlineVoidPlugin = createSlatePlugin({
    key: 'inlineVoid',
  }).overrideEditor(withInlineVoid);
  ```

  - Move `editor.redecorate` to `editor.api.redecorate`

  Types:

  - Rename `TRenderElementProps` to `RenderElementProps`
  - Rename `TRenderLeafProps` to `RenderLeafProps`
  - Rename `TEditableProps` to `EditableProps`

## @udecode/plate@42.0.0

- [#3920](https://github.com/udecode/plate/pull/3920) by [@zbeyens](https://github.com/zbeyens) – **This package is now the new common package**, so all plugin packages are being removed. **Migration**:

  - Add the following dependencies:

  ```json
  "@udecode/plate-alignment": "42.0.0",
  "@udecode/plate-autoformat": "42.0.0",
  "@udecode/plate-basic-elements": "42.0.0",
  "@udecode/plate-basic-marks": "42.0.0",
  "@udecode/plate-block-quote": "42.0.0",
  "@udecode/plate-break": "42.0.0",
  "@udecode/plate-code-block": "42.0.0",
  "@udecode/plate-combobox": "42.0.0",
  "@udecode/plate-comments": "42.0.0",
  "@udecode/plate-csv": "42.0.0",
  "@udecode/plate-diff": "42.0.0",
  "@udecode/plate-docx": "42.0.0",
  "@udecode/plate-find-replace": "42.0.0",
  "@udecode/plate-floating": "42.0.0",
  "@udecode/plate-font": "42.0.0",
  "@udecode/plate-heading": "42.0.0",
  "@udecode/plate-highlight": "42.0.0",
  "@udecode/plate-horizontal-rule": "42.0.0",
  "@udecode/plate-indent": "42.0.0",
  "@udecode/plate-indent-list": "42.0.0",
  "@udecode/plate-kbd": "42.0.0",
  "@udecode/plate-layout": "42.0.0",
  "@udecode/plate-line-height": "42.0.0",
  "@udecode/plate-link": "42.0.0",
  "@udecode/plate-list": "42.0.0",
  "@udecode/plate-markdown": "42.0.0",
  "@udecode/plate-media": "42.0.0",
  "@udecode/plate-mention": "42.0.0",
  "@udecode/plate-node-id": "42.0.0",
  "@udecode/plate-normalizers": "42.0.0",
  "@udecode/plate-reset-node": "42.0.0",
  "@udecode/plate-resizable": "42.0.0",
  "@udecode/plate-select": "42.0.0",
  "@udecode/plate-selection": "42.0.0",
  "@udecode/plate-slash-command": "42.0.0",
  "@udecode/plate-suggestion": "42.0.0",
  "@udecode/plate-tabbable": "42.0.0",
  "@udecode/plate-table": "42.0.0",
  "@udecode/plate-toggle": "42.0.0",
  "@udecode/plate-trailing-block": "42.0.0"
  ```

  - Either replace all `@udecode/plate` imports with the individual package imports, or export the following in a new file (e.g. `src/plate.ts`):

  ```ts
  export * from '@udecode/plate-alignment';
  export * from '@udecode/plate-autoformat';
  export * from '@udecode/plate-basic-elements';
  export * from '@udecode/plate-basic-marks';
  export * from '@udecode/plate-block-quote';
  export * from '@udecode/plate-break';
  export * from '@udecode/plate-code-block';
  export * from '@udecode/plate-combobox';
  export * from '@udecode/plate-comments';
  export * from '@udecode/plate-diff';
  export * from '@udecode/plate-find-replace';
  export * from '@udecode/plate-font';
  export * from '@udecode/plate-heading';
  export * from '@udecode/plate-highlight';
  export * from '@udecode/plate-horizontal-rule';
  export * from '@udecode/plate-indent';
  export * from '@udecode/plate-indent-list';
  export * from '@udecode/plate-kbd';
  export * from '@udecode/plate-layout';
  export * from '@udecode/plate-line-height';
  export * from '@udecode/plate-link';
  export * from '@udecode/plate-list';
  export * from '@udecode/plate-media';
  export * from '@udecode/plate-mention';
  export * from '@udecode/plate-node-id';
  export * from '@udecode/plate-normalizers';
  export * from '@udecode/plate-reset-node';
  export * from '@udecode/plate-select';
  export * from '@udecode/plate-csv';
  export * from '@udecode/plate-docx';
  export * from '@udecode/plate-markdown';
  export * from '@udecode/plate-slash-command';
  export * from '@udecode/plate-suggestion';
  export * from '@udecode/plate-tabbable';
  export * from '@udecode/plate-table';
  export * from '@udecode/plate-toggle';
  export * from '@udecode/plate-trailing-block';
  export * from '@udecode/plate-alignment/react';
  export * from '@udecode/plate-autoformat/react';
  export * from '@udecode/plate-basic-elements/react';
  export * from '@udecode/plate-basic-marks/react';
  export * from '@udecode/plate-block-quote/react';
  export * from '@udecode/plate-break/react';
  export * from '@udecode/plate-code-block/react';
  export * from '@udecode/plate-combobox/react';
  export * from '@udecode/plate-comments/react';
  export * from '@udecode/plate-floating';
  export * from '@udecode/plate-font/react';
  export * from '@udecode/plate-heading/react';
  export * from '@udecode/plate-highlight/react';
  export * from '@udecode/plate-layout/react';
  export * from '@udecode/plate-slash-command/react';
  export * from '@udecode/plate-indent/react';
  export * from '@udecode/plate-indent-list/react';
  export * from '@udecode/plate-kbd/react';
  export * from '@udecode/plate-line-height/react';
  export * from '@udecode/plate-link/react';
  export * from '@udecode/plate-list/react';
  export * from '@udecode/plate-media/react';
  export * from '@udecode/plate-reset-node/react';
  export * from '@udecode/plate-selection';
  export * from '@udecode/plate-suggestion/react';
  export * from '@udecode/plate-tabbable/react';
  export * from '@udecode/plate-table/react';
  export * from '@udecode/plate-toggle/react';
  export * from '@udecode/plate-resizable';
  ```

  - Replace all `'@udecode/plate'` and `'@udecode/plate/react'` with `'@/plate'` in your codebase.

## @udecode/plate-utils@42.0.0

- [#3920](https://github.com/udecode/plate/pull/3920) by [@zbeyens](https://github.com/zbeyens) –
  - Removed unused `moveSelectionByOffset`, `getLastBlockDOMNode`, `useLastBlock`, `useLastBlockDOMNode`

## @udecode/plate-selection@42.0.0

- [#3920](https://github.com/udecode/plate/pull/3920) by [@zbeyens](https://github.com/zbeyens) – Remove first parameter of editor.api.blockSelection.duplicate

## @udecode/slate@42.0.0

- [#3920](https://github.com/udecode/plate/pull/3920) by [@zbeyens](https://github.com/zbeyens) –

  - Remove `slate`, `slate-dom`, `slate-react`, `slate-history` and `slate-hyperscript` from your dependencies. It's now part of this package and `@udecode/plate`. All exports remain the same or have equivalents (see below).
  - Renamed `createTEditor` to `createEditor`.
  - `createEditor` now returns an editor (`Editor`) with all queries under `editor.api` and transforms under `editor.tf`. You can see or override them at a glance. For example, we now use `editor.tf.setNodes` instead of importing `setNodes`. This marks the completion of generic typing and the removal of error throws from `slate`, `slate-dom`, and `slate-history` queries/transforms, without forking implementations. We’ve also reduced the number of queries/transforms by merging a bunch of them.

  The following interfaces from `slate` and `slate-dom` are now part of `Editor`:

  - `Editor`, `EditorInterface`

  - `Transforms`

  - `HistoryEditor` (noop, unchanged), `HistoryEditorInterface`

  - `DOMEditor` (noop, unchanged), `DOMEditorInterface`

  - `editor.findPath` now returns `DOMEditor.findPath` (memo) and falls back to `findNodePath` (traversal, less performant) if not found.

  - Removed the first parameter (`editor`) from:

    - `editor.hasEditableTarget`
    - `editor.hasSelectableTarget`
    - `editor.isTargetInsideNonReadonlyVoid`
    - `editor.hasRange`
    - `editor.hasTarget`

  - `editor.api.node(options)` (previously `findNode`) `at` option is now `at ?? editor.selection` instead of `at ?? editor.selection ?? []`. That means if you want to lookup the entire document, you need to pass `[]` explicitly.

  - Removed `setNode` in favor of `setNodes` (you can now pass a `TNode` to `at` directly).

  - Removed `setElements` in favor of `setNodes`.

  - Removed unused `isWordAfterTrigger`, `setBlockAboveNode`, `setBlockAboveTexts`, `setBlockNodes`, `getPointNextToVoid`.

  - Replaced `Path` from slate with `Path` (type) and `PathApi` (static methods).

  - Replaced `Operation` from slate with `Operation` (type) and `OperationApi` (static methods).

  - Replaced `Point` from slate with `Point` (type) and `PointApi` (static methods).

  - Replaced `Text` from slate with `TText` (type) and `TextApi` (static methods). We also export `Text` type like `slate` but we don't recommend it as it's conflicting with the DOM type.

  - Replaced `Range` from slate with `TRange` (type) and `RangeApi` (static methods). We also export `Range` type like `slate` but we don't recommend it as it's conflicting with the DOM type.

  - Replaced `Location` from slate with `TLocation` (type) and `LocationApi` (static methods). We also export `Location` type like `slate` but we don't recommend it as it's conflicting with the DOM type.

  - Replaced `Span` from slate with `Span` (type) and `SpanApi` (static methods).

  - Replaced `Node` from slate with `TNode` (type) and `NodeApi` (static methods). We also export `Node` type like `slate` but we don't recommend it as it's conflicting with the DOM type.

  - Replaced `Element` from slate with `TElement` (type) and `ElementApi` (static methods). We also export `Element` type like `slate` but we don't recommend it as it's conflicting with the DOM type.

  - Signature change:

    - `editor.tf.toggle.block({ type, ...options })` -> `editor.tf.toggleBlock(type, options)`
    - `editor.tf.toggle.mark({ key, clear })` -> `editor.tf.toggleMark(key, { remove: clear })`

  - Moved editor functions:

    - `addMark` -> `editor.tf.addMark`
    - `addRangeMarks` -> `editor.tf.setNodes(props, { at, marks: true })`
    - `blurEditor` -> `editor.tf.blur`
    - `collapseSelection` -> `editor.tf.collapse`
    - `createDocumentNode` -> `editor.api.create.value` (core)
    - `createNode` -> `editor.api.create.block`
    - `createPathRef` -> `editor.api.pathRef`
    - `createPointRef` -> `editor.api.pointRef`
    - `createRangeRef` -> `editor.api.rangeRef`
    - `deleteBackward({ unit })` -> `editor.tf.deleteBackward(unit)`
    - `deleteForward({ unit })` -> `editor.tf.deleteForward(unit)`
    - `deleteFragment` -> `editor.tf.deleteFragment`
    - `deleteText` -> `editor.tf.delete`
    - `deselect` -> `editor.tf.deselect`
    - `deselectEditor` -> `editor.tf.deselectDOM`
    - `duplicateBlocks` -> `editor.tf.duplicateNodes({ nodes })`
    - `findDescendant` -> `editor.api.descendant`
    - `findEditorDocumentOrShadowRoot` -> `editor.api.findDocumentOrShadowRoot`
    - `findEventRange` -> `editor.api.findEventRange`
    - `findNode(options)` -> `editor.api.node(options)`
    - `findNodeKey` -> `editor.api.findKey`
    - `findNodePath` -> `editor.api.findPath`
    - `findPath` -> `editor.api.findPath`
    - `focusEditor` -> `editor.tf.focus({ at })`
    - `focusEditorEdge` -> `editor.tf.focus({ at, edge: 'startEditor' | 'endEditor' })`
    - `getAboveNode` -> `editor.api.above`
    - `getAncestorNode` -> `editor.api.block({ highest: true })`
    - `getBlockAbove` -> `editor.api.block({ at, above: true })` or `editor.api.block()` if `at` is not a path
    - `getBlocks` -> `editor.api.blocks`
    - `getEdgeBlocksAbove` -> `editor.api.edgeBlocks`
    - `getEdgePoints` -> `editor.api.edges`
    - `getEditorString` -> `editor.api.string`
    - `getEditorWindow` -> `editor.api.getWindow`
    - `getEndPoint` -> `editor.api.end`
    - `getFirstNode` -> `editor.api.first`
    - `getFragment` -> `editor.api.fragment`
    - `getFragmentProp(fragment, options)` -> `editor.api.prop({ nodes, ...options})`
    - `getLastNode` -> `editor.api.last`
    - `getLastNodeByLevel(level)` -> `editor.api.last([], { level })`
    - `getLeafNode` -> `editor.api.leaf`
    - `getLevels` -> `editor.api.levels`
    - `getMark` -> `editor.api.mark`
    - `getMarks` -> `editor.api.marks`
    - `getNextNode` -> `editor.api.next`
    - `getNextNodeStartPoint` -> `editor.api.start(at, { next: true })`
    - `getNodeEntries` -> `editor.api.nodes`
    - `getNodeEntry` -> `editor.api.node(at, options)`
    - `getNodesRange` -> `editor.api.nodesRange`
    - `getParentNode` -> `editor.api.parent`
    - `getPath` -> `editor.api.path`
    - `getPathRefs` -> `editor.api.pathRefs`
    - `getPoint` -> `editor.api.point`
    - `getPointAfter` -> `editor.api.after`
    - `getPointBefore` -> `editor.api.before`
    - `getPointBeforeLocation` -> `editor.api.before`
    - `getPointRefs` -> `editor.api.pointRefs`
    - `getPositions` -> `editor.api.positions`
    - `getPreviousBlockById` -> `editor.api.previous({ id, block: true })`
    - `getPreviousNode` -> `editor.api.previous`
    - `getPreviousNodeEndPoint` -> `editor.api.end({ previous: true })`
    - `getPreviousSiblingNode` -> `editor.api.previous({ at, sibling: true })`
    - `getRange` -> `editor.api.range`
    - `getRangeBefore` -> `editor.api.range('before', to, { before })`
    - `getRangeFromBlockStart` -> `editor.api.range('start', to)`
    - `getRangeRefs` -> `editor.api.rangeRefs`
    - `getSelectionFragment` -> `editor.api.fragment(editor.selection, { structuralTypes })`
    - `getSelectionText` -> `editor.api.string()`
    - `getStartPoint` -> `editor.api.start`
    - `getVoidNode` -> `editor.api.void`
    - `hasBlocks` -> `editor.api.hasBlocks`
    - `hasEditorDOMNode` -> `editor.api.hasDOMNode`
    - `hasEditorEditableTarget` -> `editor.api.hasEditableTarget`
    - `hasEditorSelectableTarget` -> `editor.api.hasSelectableTarget`
    - `hasEditorTarget` -> `editor.api.hasTarget`
    - `hasInlines` -> `editor.api.hasInlines`
    - `hasTexts` -> `editor.api.hasTexts`
    - `insertBreak` -> `editor.tf.insertBreak`
    - `insertData` -> `editor.tf.insertData`
    - `insertElements` -> `editor.tf.insertNodes<TElement>`
    - `insertEmptyElement` -> `editor.tf.insertNodes(editor.api.create.block({ type }))`
    - `insertFragment` -> `editor.tf.insertFragment`
    - `insertNode` -> `editor.tf.insertNode`
    - `insertNodes` -> `editor.tf.insertNodes`
    - `insertText` -> `editor.tf.insertText({ at })` or `editor.tf.insertText({ marks: false })` without `at`
    - `isAncestorEmpty` -> `editor.api.isEmpty`
    - `isBlock` -> `editor.api.isBlock`
    - `isBlockAboveEmpty` -> `editor.api.isEmpty(editor.selection, { block: true })`
    - `isBlockTextEmptyAfterSelection` -> `editor.api.isEmpty(editor.selection, { after: true })`
    - `isCollapsed(editor.selection)` -> `editor.api.isCollapsed()`
    - `isComposing` -> `editor.api.isComposing`
    - `isDocumentEnd` -> `editor.api.isEditorEnd`
    - `isEdgePoint` -> `editor.api.isEdge`
    - `isEditorEmpty` -> `editor.api.isEmpty()`
    - `isEditorFocused` -> `editor.api.isFocused`
    - `isEditorNormalizing` -> `editor.api.isNormalizing`
    - `isEditorReadOnly` -> `editor.api.isReadOnly`
    - `isElementEmpty` -> `editor.api.isEmpty`
    - `isElementReadOnly` -> `editor.api.elementReadOnly`
    - `isEndPoint` -> `editor.api.isEnd`
    - `isExpanded(editor.selection)` -> `editor.api.isCollapsed()`
    - `isInline` -> `editor.api.isInline`
    - `isMarkableVoid` -> `editor.api.markableVoid`
    - `isMarkActive` -> `editor.api.hasMark(key)`
    - `isPointAtWordEnd` -> `editor.api.isAt({ at, word: true, end: true })`
    - `isRangeAcrossBlocks` -> `editor.api.isAt({ at, blocks: true })`
    - `isRangeInSameBlock` -> `editor.api.isAt({ at, block: true })`
    - `isRangeInSingleText` -> `editor.api.isAt({ at, text: true })`
    - `isSelectionAtBlockEnd` -> `editor.api.isAt({ end: true })`
    - `isSelectionAtBlockStart` -> `editor.api.isAt({ start: true })`
    - `isSelectionCoverBlock` -> `editor.api.isAt({ block: true, start: true, end: true })`
    - `isSelectionExpanded` -> `editor.api.isExpanded()`
    - `isStartPoint` -> `editor.api.isStart`
    - `isTargetinsideNonReadonlyVoidEditor` -> `editor.api.isTargetInsideNonReadonlyVoid`
    - `isTextByPath` -> `editor.api.isText(at)`
    - `isVoid` -> `editor.api.isVoid`
    - `liftNodes` -> `editor.tf.liftNodes`
    - `mergeNodes` -> `editor.tf.mergeNodes`
    - `moveChildren` -> `editor.tf.moveNodes({ at, to, children: true, fromIndex, match: (node, path) => boolean })`
    - `moveNodes` -> `editor.tf.moveNodes`
    - `moveSelection` -> `editor.tf.move`
    - `normalizeEditor` -> `editor.tf.normalize`
    - `removeEditorMark` -> `editor.tf.removeMark`
    - `removeEditorText` -> `editor.tf.removeNodes({ text: true, empty: false })`
    - `removeEmptyPreviousBlock` -> `editor.tf.removeNodes({ previousEmptyBlock: true })`
    - `removeMark(options)` -> `editor.tf.removeMarks(keys, options)`
    - `removeNodeChildren` -> `editor.tf.removeNodes({ at, children: true })`
    - `removeNodes` -> `editor.tf.removeNodes`
    - `removeSelectionMark` -> `editor.tf.removeMarks()`
    - `replaceNode(editor, { nodes, insertOptions, removeOptions })` -> `editor.tf.replaceNodes(nodes, { removeNodes, ...insertOptions })`
    - `select` -> `editor.tf.select`
    - `selectEndOfBlockAboveSelection` -> `editor.tf.select(editor.selection, { edge: 'end' })`
    - `selectNodes` -> `editor.tf.select(editor.api.nodesRange(nodes))`
    - `setFragmentData` -> `editor.tf.setFragmentData`
    - `setMarks(marks, clear)` -> `editor.tf.addMarks(marks, { remove: string | string[] })`
    - `setNodes` -> `editor.tf.setNodes`
    - `setPoint` -> `editor.tf.setPoint`
    - `setSelection` -> `editor.tf.setSelection`
    - `someNode` -> `editor.api.some(options)`
    - `splitNodes` -> `editor.tf.splitNodes`
    - `toDOMNode` -> `editor.api.toDOMNode`
    - `toDOMPoint` -> `editor.api.toDOMPoint`
    - `toDOMRange` -> `editor.api.toDOMRange`
    - `toggleWrapNodes` -> `editor.tf.toggleBlock(type, { wrap: true })`
    - `toSlateNode` -> `editor.api.toSlateNode`
    - `toSlatePoint` -> `editor.api.toSlatePoint`
    - `toSlateRange` -> `editor.api.toSlateRange`
    - `unhangCharacterRange` -> `editor.api.unhangRange(range, { character: true })`
    - `unhangRange` -> `editor.api.unhangRange`
    - `unsetNodes` -> `editor.tf.unsetNodes`
    - `unwrapNodes` -> `editor.tf.unwrapNodes`
    - `withoutNormalizing` -> `editor.tf.withoutNormalizing`
    - `wrapNodeChildren` -> `editor.tf.wrapNodes(element, { children: true })`
    - `wrapNodes` -> `editor.tf.wrapNodes`
    - `replaceNodeChildren` -> `editor.tf.replaceNodes({ at, children: true })`
    - `resetEditor` -> `editor.tf.reset`
    - `resetEditorChildren` -> `editor.tf.reset({ children: true })`
    - `selectEditor` -> `editor.tf.select([], { focus, edge })`
    - `selectSiblingNodePoint` -> `editor.tf.select(at, { next, previous })`

  - Moved to `NodeApi.`:

    - `getNextSiblingNodes(parentEntry, path)` -> `NodeApi.children(editor, path, { from: path.at(-1) + 1 })`
    - `getFirstNodeText` -> `NodeApi.firstText`
    - `getFirstChild([node, path])` -> `NodeApi.firstChild(editor, path)`
    - `getLastChild([node, path])` -> `NodeApi.lastChild(editor, path)`
    - `getLastChildPath([node, path])` -> `NodeApi.lastChild(editor, path)`
    - `isLastChild([node, path], childPath)` -> `NodeApi.isLastChild(editor, childPath)`
    - `getChildren([node, path])` -> `Array.from(NodeApi.children(editor, path))`
    - `getCommonNode` -> `NodeApi.common`
    - `getNode` -> `NodeApi.get`
    - `getNodeAncestor` -> `NodeApi.ancestor`
    - `getNodeAncestors` -> `NodeApi.ancestors`
    - `getNodeChild` -> `NodeApi.child`
    - `getNodeChildren` -> `NodeApi.children`
    - `getNodeDescendant` -> `NodeApi.descendant`
    - `getNodeDescendants` -> `NodeApi.descendants`
    - `getNodeElements` -> `NodeApi.elements`
    - `getNodeFirstNode` -> `NodeApi.first`
    - `getNodeFragment` -> `NodeApi.fragment`
    - `getNodeLastNode` -> `NodeApi.last`
    - `getNodeLeaf` -> `NodeApi.leaf`
    - `getNodeLevels` -> `NodeApi.levels`
    - `getNodeParent` -> `NodeApi.parent`
    - `getNodeProps` -> `NodeApi.extractProps`
    - `getNodes` -> `NodeApi.nodes`
    - `getNodeString` -> `NodeApi.string`
    - `getNodeTexts` -> `NodeApi.texts`
    - `hasNode` -> `NodeApi.has`
    - `hasSingleChild` -> `NodeApi.hasSingleChild`
    - `isAncestor` -> `NodeApi.isAncestor`
    - `isDescendant` -> `NodeApi.isDescendant`
    - `isEditor` -> `NodeApi.isEditor`
    - `isNode` -> `NodeApi.isNode`
    - `isNodeList` -> `NodeApi.isNodeList`
    - `nodeMatches` -> `NodeApi.matches`

  - Moved to `ElementApi.`:

    - `elementMatches` -> `ElementApi.matches`
    - `isElement` -> `ElementApi.isElement`
    - `isElementList` -> `ElementApi.isElementList`

  - Moved to `TextApi.`:

    - `isText` -> `TextApi.isText(at)`

  - Moved to `RangeApi.`:

    - `isCollapsed` -> `RangeApi.isCollapsed`
    - `isExpanded` -> `RangeApi.isExpanded`

  - Moved to `PathApi.`:

    - `isFirstChild` -> `!PathApi.hasPrevious`
    - `getPreviousPath` -> `PathApi.previous`

  - Moved to `PointApi.`:

    - `getPointFromLocation({ at, focus })` -> `PointApi.get(at, { focus })`

  - Moved from `@udecode/plate/react` to `@udecode/plate`:

    - `Hotkeys`

  - Upgraded to `zustand@5` and `zustand-x@5`:
    - Replace `createZustandStore('name')(initialState)` with `createZustandStore(initialState, { mutative: true, name: 'name' })`
    - All plugin stores now use [zustand-mutative](https://github.com/mutativejs/zustand-mutative) for immutable state updates, which is faster than `immer`.

  Types:

  - Rename the following types:
    - `TEditor` -> `Editor`
    - `TOperation` -> `Operation`
    - `TPath` -> `Path`
    - `TNodeProps` -> `NodeProps`
    - `TNodeChildEntry` -> `NodeChildEntry`
    - `TNodeEntry` -> `NodeEntry`
    - `TDescendant` -> `Descendant`
    - `TDescendantEntry` -> `DescendantEntry`
    - `TAncestor` -> `Ancestor`
    - `TAncestorEntry` -> `AncestorEntry`
    - `TElementEntry` -> `ElementEntry`
    - `TTextEntry` -> `TextEntry`
  - Query/transform options now use generic `V extends Value` instead of `E extends Editor`.
  - `getEndPoint`, `getEdgePoints`, `getFirstNode`, `getFragment`, `getLastNode`, `getLeafNode`, `getPath`, `getPoint`, `getStartPoint` can return `undefined` if not found (suppressing error throws).
  - `NodeApi.ancestor`, `NodeApi.child`, `NodeApi.common`, `NodeApi.descendant`, `NodeApi.first`, `NodeApi.get`, `NodeApi.last`, `NodeApi.leaf`, `NodeApi.parent`, `NodeApi.getIf`, `PathApi.previous` return `undefined` if not found instead of throwing
  - Replace `NodeOf` type with `DescendantOf` in `editor.tf.setNodes` `editor.tf.unsetNodes`, `editor.api.previous`, `editor.api.node`, `editor.api.nodes`, `editor.api.last`
  - Enhanced `editor.tf.setNodes`:
    - Added `marks` option to handle mark-specific operations
    - When `marks: true`:
      - Only applies to text nodes in non-void nodes or markable void nodes
      - Automatically sets `split: true` and `voids: true`
      - Handles both expanded ranges and collapsed selections in markable voids
    - Replaces `addRangeMarks` functionality

## @udecode/slate-utils@42.0.0

- [#3920](https://github.com/udecode/plate/pull/3920) by [@zbeyens](https://github.com/zbeyens) – This package is now deprecated. Use `@udecode/slate` or `@udecode/plate` instead.

## @udecode/slate-react@42.0.0

- [#3920](https://github.com/udecode/plate/pull/3920) by [@zbeyens](https://github.com/zbeyens) – This package is now deprecated. Use `@udecode/slate` or `@udecode/plate` instead.

## @udecode/plate-table@42.0.0

- [#3920](https://github.com/udecode/plate/pull/3920) by [@zbeyens](https://github.com/zbeyens) – **Major performance improvement**: all table cells were re-rendering when a single cell changed. This is now fixed.

  - `TablePlugin` now depends on `NodeIdPlugin`.
  - Table merging is now enabled by default:
    - Renamed `enableMerging` to `disableMerge`.
    - **Migration**:
      - `enableMerging: true` → remove the option.
      - otherwise → `TablePlugin.configure({ options: { disableMerge: true } })`
  - Renamed `unmergeTableCells` to `splitTableCell`.
  - Renamed `editor.api.create.cell` to `editor.api.create.tableCell`.
  - In `useTableMergeState`, renamed `canUnmerge` to `canSplit`.
  - `insertTableRow` and `insertTableColumn`: removed `disableSelect` in favor of `select`. **Migration**: replace it with the opposite boolean.
  - `getTableCellBorders`: params `(element, options)` → `(editor, options)`; removed `isFirstCell` and `isFirstRow`.
  - Merged `useTableCellElementState` into `useTableCellElement`:
    - Removed its parameter.
    - Removed `hovered` and `hoveredLeft` returns (use CSS instead).
    - Renamed `rowSize` to `minHeight`.
    - Computes column sizes and returns `width`.
  - Merged `useTableCellElementResizableState` into `useTableCellElementResizable`:
    - Removed `onHover` and `onHoverEnd` props (use CSS instead).
  - Merged `useTableElementState` into `useTableElement`:
    - Removed its parameter.
    - No longer computes and returns `colSizes`, `minColumnWidth`, and `colGroupProps`.

# 41.0.2

## @udecode/slate-react@41.0.0

- [#3830](https://github.com/udecode/plate/pull/3830) by [@felixfeng33](https://github.com/felixfeng33) – Rename `findNodePath` to `findPath` since the addition of `findNodePath` in the headless lib.

  We recommend using `findPath` mostly when subscribing to its value (e.g. in a React component) as it has O(path.length) complexity, compared to O(n) for the traversal-based `findNodePath`. This optimization is particularly important in:

  - Render functions of Plate components where using `findNodePath` would increase the initial render time by O(n²)
  - Key press handlers where using `findNodePath` would increase the handling time by O(n)

  where n is the number of nodes in the editor.

## @udecode/plate-dnd@41.0.2

- [#3861](https://github.com/udecode/plate/pull/3861) by [@zbeyens](https://github.com/zbeyens) –

  - Removed `useDndBlock`, `useDragBlock`, and `useDropBlock` hooks in favor of `useDndNode`, `useDragNode`, and `useDropNode`.
  - Removed `DndProvider` and `useDraggableStore`. Drop line state is now managed by `DndPlugin` as a single state object `dropTarget` containing both `id` and `line`.
  - `useDropNode`: removed `onChangeDropLine` and `dropLine` options

  Migration steps:

  - Remove `DndProvider` from your draggable component (e.g. `draggable.tsx`)
  - Replace `useDraggableStore` with `useEditorPlugin(DndPlugin).useOption`
  - Remove `useDraggableState`. Use `const { isDragging, previewRef, handleRef } = useDraggable`
  - Remove `useDraggableGutter`. Set `contentEditable={false}` to your gutter element
  - Remove `props` from `useDropLine`. Set `contentEditable={false}` to your drop line element
  - Remove `withDraggable`, `useWithDraggable`. Use [`DraggableAboveNodes`](https://github.com/udecode/plate/pull/3878/files#diff-493c12ebed9c3ef9fd8c3a723909b18ad439a448c0132d2d93e5341ee0888ad2) instead

## @udecode/plate-indent-list@41.0.0

- [#3830](https://github.com/udecode/plate/pull/3830) by [@felixfeng33](https://github.com/felixfeng33) –
  - Move `render.belowNodes` from `IndentListPlugin` to `BaseIndentListPlugin`. Props type for `listStyleTypes.liComponent` and `listStyleTypes.markerComponent` options is now `SlateRenderElementProps` instead of `PlateRenderElementProps`
  - Move `someIndentList`, `someIndentTodo` from `@udecode/plate-indent-list/react` to `@udecode/plate-indent-list`

## @udecode/plate-layout@41.0.2

- [#3878](https://github.com/udecode/plate/pull/3878) by [@zbeyens](https://github.com/zbeyens) –

  - `insertColumnGroup`: rename `layout` to `columns`
  - Remove `setColumnWidth`, `useColumnState`. Use `setColumns` instead

## @udecode/plate-table@41.0.0

- [#3830](https://github.com/udecode/plate/pull/3830) by [@felixfeng33](https://github.com/felixfeng33) – Move from `@udecode/plate-table/react` to `@udecode/plate-table`:

  - `deleteColumn`
  - `deleteColumnWhenExpanded`
  - `deleteRow`
  - `deleteRowWhenExpanded`
  - `getTableColumn`
  - `getTableGridAbove`
  - `getTableGridByRange`
  - `getTableRow`
  - `insertTable`
  - `mergeTableCells`
  - `moveSelectionFromCell`
  - `overrideSelectionFromCell`
  - `unmergeTableCells`
  - `withDeleteTable`
  - `withGetFragmentlable`
  - `withInsertFragmentTable`
  - `withInsertTextTable`
  - `withMarkTable`
  - `withSelectionTable`
  - `withSetFragmentDataTable`
  - `withTable`

# 40.0.0

## @udecode/slate-react@40.0.0

- [#3744](https://github.com/udecode/plate/pull/3744) by [@zbeyens](https://github.com/zbeyens) –
  - Add `slate-dom` as a peer dependency.
  - Update `slate-react` peer dependency to `>=0.111.0`

## @udecode/plate-ai@40.0.0

- [#3744](https://github.com/udecode/plate/pull/3744) by [@zbeyens](https://github.com/zbeyens) –
  - Remove `scrollContainerSelector` option in favor of `useEditorContainerRef`

## @udecode/plate-heading@40.0.0

- [#3744](https://github.com/udecode/plate/pull/3744) by [@zbeyens](https://github.com/zbeyens) –
  - Remove `scrollContainerSelector` option in favor of `useEditorContainerRef`

## @udecode/plate-layout@40.0.0

- [#3744](https://github.com/udecode/plate/pull/3744) by [@zbeyens](https://github.com/zbeyens) –
  - Remove `toggleColumns` in favor of `toggleColumnGroup`
  - Remove `insertEmptyColumn` in favor of `insertColumn`

# 39.0.0

## @udecode/plate-dnd@39.0.0

- [#3597](https://github.com/udecode/plate/pull/3597) by [@zbeyens](https://github.com/zbeyens) – The following changes were made to improve performance:

  - Refactored `useDraggable` hook to focus on core dragging functionality:
    - Removed `dropLine`. Use `useDropLine().dropLine` instead.
    - Removed `groupProps` from the returned object – `isHovered`, and `setIsHovered` from the returned state. Use CSS instead.
    - Removed `droplineProps`, and `gutterLeftProps` from the returned object. Use `useDropLine().props`, `useDraggableGutter().props` instead.

## @udecode/plate-selection@39.0.0

- [#3597](https://github.com/udecode/plate/pull/3597) by [@zbeyens](https://github.com/zbeyens) – The following changes were made to improve performance:

  - Removed `useHooksBlockSelection` in favor of `BlockSelectionAfterEditable`
  - Removed `slate-selected` class from `BlockSelectable`. You can do it on your components using `useBlockSelected()` instead, or by using our new `block-selection.tsx` component.
  - Introduced `useBlockSelectableStore` for managing selectable state.

# 38.0.1

## @udecode/plate-core@38.0.1

- [#3506](https://github.com/udecode/plate/pull/3506) by [@zbeyens](https://github.com/zbeyens) –

  - Change `plugin.options` merging behavior from deep merge to shallow merge.
  - This affects `.extend()`, `.configure()`, and other methods that modify plugin options.
  - This update addresses a **performance regression** introduced in v37 that affected editor creation.

  Before:

  ```ts
  const plugin = createSlatePlugin({
    key: 'test',
    options: { nested: { a: 1 } },
  }).extend({
    options: { nested: { b: 1 } },
  });

  // Result: { nested: { a: 1, b: 1 } }
  ```

  After:

  ```ts
  const plugin = createSlatePlugin({
    key: 'test',
    options: { nested: { a: 1 } },
  }).extend(({ getOptions }) => ({
    options: {
      ...getOptions(),
      nested: { ...getOptions().nested, b: 1 },
    },
  }));

  // Result: { nested: { a: 1, b: 1 } }
  ```

  Migration:

  - If you're using nested options and want to preserve the previous behavior, you need to manually spread both the top-level options and the nested objects.
  - If you're not using nested options, no changes are required.

- Rename all base plugins that have a React plugin counterpart to be prefixed with `Base`. This change improves clarity and distinguishes base implementations from potential React extensions. Use base plugins only for server-side environments or to extend your own DOM layer.
- Import the following plugins from `/react` entry: `AlignPlugin`, `CalloutPlugin`, `EquationPlugin`, `FontBackgroundColorPlugin`, `FontColorPlugin`, `FontFamilyPlugin`, `FontSizePlugin`, `FontWeightPlugin`, `InlineEquationPlugin`, `LineHeightPlugin`, `TextIndentPlugin`, `TocPlugin`

# 37.0.0

Migration example: https://github.com/udecode/plate/pull/3480

We recommend to upgrade to `@udecode/plate-core@38.1.0` in one-go.

## @udecode/plate-alignment@37.0.0

- [#3420](https://github.com/udecode/plate/pull/3420) by [@zbeyens](https://github.com/zbeyens) –
  - `createAlignPlugin` -> `AlignPlugin`
  - `setAlign`: remove `key` option

## @udecode/plate-autoformat@37.0.0

- [#3420](https://github.com/udecode/plate/pull/3420) by [@zbeyens](https://github.com/zbeyens) –
  - `createAutoformatPlugin` -> `AutoformatPlugin`

## @udecode/plate-basic-elements@37.0.0

- [#3420](https://github.com/udecode/plate/pull/3420) by [@zbeyens](https://github.com/zbeyens) –
  - `createBasicElementPlugins` -> `BasicElementsPlugin`
  - `createBlockquotePlugin` -> `BlockquotePlugin`
  - `createCodeBlockPlugin` -> `CodeBlockPlugin`
  - `createHeadingPlugin` -> `HeadingPlugin`
  - Move paragraph plugin to `@udecode/plate-core`

## @udecode/plate-basic-marks@37.0.0

- [#3420](https://github.com/udecode/plate/pull/3420) by [@zbeyens](https://github.com/zbeyens) –
  - `createBasicMarksPlugins` -> `BasicMarksPlugin`
  - `createBoldPlugin` -> `BoldPlugin`
  - `createCodePlugin` -> `CodePlugin`
  - `createItalicPlugin` -> `ItalicPlugin`
  - `createStrikethroughPlugin` -> `StrikethroughPlugin`
  - `createSubscriptPlugin` -> `SubscriptPlugin`
  - `createSuperscriptPlugin` -> `SuperscriptPlugin`
  - `createUnderlinePlugin` -> `UnderlinePlugin`
  - All mark plugins removed `hotkey` option. Use `plugin.shortcuts` instead (see plate-core)

## @udecode/plate-block-quote@37.0.0

- [#3420](https://github.com/udecode/plate/pull/3420) by [@zbeyens](https://github.com/zbeyens) –
  - `createBlockquotePlugin` -> `BlockquotePlugin`

## @udecode/plate-break@37.0.0

- [#3420](https://github.com/udecode/plate/pull/3420) by [@zbeyens](https://github.com/zbeyens) –
  - `createSoftBreakPlugin` -> `SoftBreakPlugin`
  - `createExitBreakPlugin` -> `ExitBreakPlugin`
  - `createSingleLinePlugin` -> `SingleLinePlugin`

## @udecode/plate-caption@37.0.0

- [#3420](https://github.com/udecode/plate/pull/3420) by [@zbeyens](https://github.com/zbeyens) –
  - `createCaptionPlugin` -> `CaptionPlugin`
  - `CaptionPlugin` options:
    - Rename `pluginKeys` to `plugins`
    - Rename `focusEndCaptionPath` to `focusEndPath`
    - Rename `focusStartCaptionPath` to `focusStartPath`
    - Rename `showCaptionId` to `visibleId`
    - Rename `isShow` to `isVisible`
  - Move `captionGlobalStore` to `CaptionPlugin`

## @udecode/plate-cloud@37.0.0

- [#3420](https://github.com/udecode/plate/pull/3420) by [@zbeyens](https://github.com/zbeyens) –
  - `createCloudPlugin` -> `CloudPlugin`

## @udecode/plate-code-block@37.0.0

- [#3420](https://github.com/udecode/plate/pull/3420) by [@zbeyens](https://github.com/zbeyens) –
  - `createCodeBlockPlugin` -> `CodeBlockPlugin`
  - NEW `CodeLinePlugin`
  - NEW `CodeSyntaxPlugin`
  - Remove `getCodeLineType`, use `editor.getType(CodeLinePlugin)` instead

## @udecode/plate-combobox@37.0.0

- [#3420](https://github.com/udecode/plate/pull/3420) by [@zbeyens](https://github.com/zbeyens) –
  - Split build into `@udecode/plate-combobox` and `@udecode/plate-combobox/react`.

## @udecode/plate-comments@37.0.0

- [#3420](https://github.com/udecode/plate/pull/3420) by [@zbeyens](https://github.com/zbeyens) –
  - `createCommentsPlugin` -> `CommentsPlugin`
  - Move `commentsStore` to `CommentsPlugin`
  - Remove `CommentsProvider` and its hooks
  - Remove `useCommentsStates` (replaced by direct option access)
  - Remove `useCommentsSelectors` (replaced by option selectors)
  - Remove `useCommentsActions` (replaced by api methods)
  - Replace `useUpdateComment` with `api.comment.updateComment`
  - Replace `useAddRawComment` with `api.comment.addRawComment`
  - Replace `useAddComment` with `api.comment.addComment`
  - Replace `useRemoveComment` with `api.comment.removeComment`
  - Replace `useResetNewCommentValue` with `api.comment.resetNewCommentValue`
  - Replace `useNewCommentText` with `options.newText`
  - Replace `useMyUser` with `options.myUser`
  - Replace `useUserById` with `options.userById`
  - Replace `useCommentById` with `options.commentById`
  - Replace `useActiveComment` with `options.activeComment`
  - Replace `useAddCommentMark` with `insert.comment`

## @udecode/plate-common@37.0.0

- [#3420](https://github.com/udecode/plate/pull/3420) by [@zbeyens](https://github.com/zbeyens) –
  - Split build into `@udecode/plate-common` and `@udecode/plate-common/react`.
  - NEW `/react` exports `@udecode/react-hotkeys`

## @udecode/plate-core@37.0.0

- [#3420](https://github.com/udecode/plate/pull/3420) by [@zbeyens](https://github.com/zbeyens) – **Plugin System**:

  Decoupling React in all packages:

  - Split build into `@udecode/plate-core` and `@udecode/plate-core/react`
  - NEW `SlatePlugin` as the foundation for all plugins
  - `PlatePlugin` extends `SlatePlugin` with React-specific plugin features

  **Plugin Creation**:

  - Remove `createPluginFactory`
  - NEW `createSlatePlugin`: vanilla
  - NEW `createTSlatePlugin`: vanilla explicitly typed
  - NEW `createPlatePlugin`: React
  - NEW `createTPlatePlugin`: React explicitly typed
  - NEW `toPlatePlugin`: extend a vanilla plugin into a React plugin
  - NEW `toTPlatePlugin`: extend a vanilla plugin into a React plugin explicitly typed
  - Rename all plugins starting with `createNamePlugin()` to `NamePlugin`

  Before:

  ```typescript
  const MyPluginFactory = createPluginFactory({
    key: 'myPlugin',
    isElement: true,
    component: MyComponent,
  });
  const plugin = MyPluginFactory();
  ```

  After:

  ```typescript
  const plugin = createSlatePlugin({
    key: 'myPlugin',
    node: {
      isElement: true,
      component: MyComponent,
    },
  });
  const reactPlugin = toPlatePlugin(plugin);
  ```

  **Plugin Configuration**:

  - Remove all `NamePlugin` option types, use `NameConfig` instead.
  - `NameConfig` as the new naming convention for plugin configurations.

  Before:

  ```typescript
  createPluginFactory<HotkeyPlugin>({
    handlers: {
      onKeyDown: onKeyDownToggleElement,
    },
    options: {
      hotkey: ['mod+opt+0', 'mod+shift+0'],
    },
  });
  ```

  After:

  ```typescript
  export const ParagraphPlugin = createPlatePlugin({
    key: 'p',
    node: { isElement: true },
  }).extend({ editor, type }) => ({
    shortcuts: {
      toggleParagraph: {
        handler: () => {
          editor.tf.toggle.block({ type });
        },
        keys: [
          [Key.Mod, Key.Alt, '0'],
          [Key.Mod, Key.Shift, '0'],
        ],
        preventDefault: true,
      },
    },
  })
  ```

  - `toggleParagraph` is now a shortcut for `editor.tf.toggle.block({ type: 'p' })` for the given keys
  - Multiple shortcuts can be defined per plugin, and any shortcut can be disabled by setting `shortcuts.toggleParagraph = null`
  - Note the typing support using `Key`

  **Plugin Properties**:

  Rename `SlatePlugin` / `PlatePlugin` properties:

  - `type` -> `node.type`
  - `isElement` -> `node.isElement`
  - `isLeaf` -> `node.isLeaf`
  - `isInline` -> `node.isInline`
  - `isMarkableVoid` -> `node.isMarkableVoid`
  - `isVoid` -> `node.isVoid`
  - `component` -> `node.component` or `render.node`
  - `props` -> `node.props`
  - `overrideByKey` -> `override.plugins`
  - `renderAboveEditable` -> `render.aboveEditable`
  - `renderAboveSlate` -> `render.aboveSlate`
  - `renderAfterEditable` -> `render.afterEditable`
  - `renderBeforeEditable` -> `render.beforeEditable`
  - `inject.props` -> `inject.nodeProps`
  - `inject.props.validTypes` -> `inject.targetPlugins`
  - `inject.aboveComponent` -> `render.aboveNodes`
  - `inject.belowComponent` -> `render.belowNodes`
  - `inject.pluginsByKey` -> `inject.plugins`
  - `editor.insertData` -> `parser`
    - NEW `parser.format` now supports `string[]`
    - NEW `parser.mimeTypes: string[]`
  - `deserializeHtml` -> `parsers.html.deserializer`
  - `deserializeHtml.getNode` -> `parsers.html.deserializer.parse`
  - `serializeHtml` -> `parsers.htmlReact.serializer`
  - `withOverride` -> `extendEditor`
  - All methods now have a single parameter: `SlatePluginContext<C>` or `PlatePluginContext<C>`, in addition to the method specific options. Some of the affected methods are:
    - `decorate`
    - `handlers`, including `onChange`. Returns `({ event, ...ctx }) => void` instead of `(editor, plugin) => (event) => void`
    - `handlers.onChange`: `({ value, ...ctx }) => void` instead of `(editor, plugin) => (value) => void`
    - `normalizeInitialValue`
    - `editor.insertData.preInsert`
    - `editor.insertData.transformData`
    - `editor.insertData.transformFragment`
    - `deserializeHtml.getNode`
    - `deserializeHtml.query`
    - `inject.props.query`
    - `inject.props.transformProps`
    - `useHooks`
    - `withOverrides`

  NEW `SlatePlugin` properties:

  - `api`: API methods provided by this plugin
  - `dependencies`: An array of plugin keys that this plugin depends on
  - `node`: Node-specific configuration for this plugin
  - `parsers`: Now accept `string` keys to add custom parsers
  - `priority`: Plugin priority for registration and execution order
  - `shortcuts`: Plugin-specific hotkeys
  - `inject.targetPluginToInject`: Function to inject plugin config into other plugins specified by `inject.targetPlugins`

  Before:

  ```typescript
  export const createAlignPlugin = createPluginFactory({
    key: KEY_ALIGN,
    inject: {
      props: {
        defaultNodeValue: 'start',
        nodeKey: KEY_ALIGN,
        styleKey: 'textAlign',
        validNodeValues: ['start', 'left', 'center', 'right', 'end', 'justify'],
        validTypes: ['p'],
      },
    },
    then: (_, plugin) =>
      mapInjectPropsToPlugin(editor, plugin, {
        deserializeHtml: {
          getNode: (el, node) => {
            if (el.style.textAlign) {
              node[plugin.key] = el.style.textAlign;
            }
          },
        },
      }),
  });
  ```

  After:

  ```typescript
  export const AlignPlugin = createSlatePlugin({
    inject: {
      nodeProps: {
        defaultNodeValue: 'start',
        nodeKey: 'align',
        styleKey: 'textAlign',
        validNodeValues: ['start', 'left', 'center', 'right', 'end', 'justify'],
      },
      targetPluginToInject: ({ editor, plugin }) => ({
        parsers: {
          html: {
            deserializer: {
              parse: ({ element, node }) => {
                if (element.style.textAlign) {
                  node[editor.getType(plugin)] = element.style.textAlign;
                }
              },
            },
          },
        },
      }),
      targetPlugins: [ParagraphPlugin.key],
    },
    key: 'align',
  });
  ```

  **Plugin Shortcuts**:

  - NEW `shortcuts` to add custom hotkeys to a plugin.
  - Remove `hotkey` option from all plugins

  Before:

  ```typescript
  type LinkPlugin = {
    hotkey?: string;
  };
  ```

  After:

  ```typescript
  type LinkConfig = PluginConfig<
    // key
    'p',
    // options
    { defaultLinkAttributes?: any },
    // api
    { link: { getAttributes: (editor: PlateEditor) => LinkAttributes } },
    // transforms
    { floatingLink: { hide: () => void } }
  >;
  ```

  Shortcuts API:

  - `handler` is called with the editor, event, and event details.
  - `keys` is an array of keys to trigger the shortcut.
  - `priority` is the priority of the shortcut over other shortcuts.
  - `...HotkeysOptions` from `@udecode/react-hotkeys`

  **Plugin Types**:

  - Update `SlatePlugin`, `PlatePlugin` generics. `P, V, E` -> `C extends AnyPluginConfig = PluginConfig`
  - Remove `PluginOptions`
  - Remove `PlatePluginKey`
  - Remove `HotkeyPlugin`, `ToggleMarkPlugin` in favor of `plugin.shortcuts`
  - `WithPlatePlugin` -> `EditorPlugin`, `EditorPlatePlugin`
  - `PlatePluginComponent` -> `NodeComponent`
  - `InjectComponent*` -> `NodeWrapperComponent*`
  - `PlatePluginInsertData` -> `Parser`
  - `PlatePluginProps` -> `NodeProps`
  - `RenderAfterEditable` -> `EditableSiblingComponent`
  - `WithOverride` -> `ExtendEditor`
  - `SerializeHtml` -> `HtmlReactSerializer`

  **Plugin Store**:

  - NEW each plugin has its own store, accessible via `plugin.optionsStore` and `plugin.useOptionsStore`
  - `editor` has many methods to get, set and subscribe to plugin options

  **Plugin Methods**:

  - All plugin methods return a new plugin instance with the extended types.
  - Remove `then`, use `extend` instead
  - NEW `extend` method to deep merge a plugin configuration
    - If you pass an object, it will be directly merged with the plugin config.
    - If you pass a function, it will be called with the plugin config once the editor is resolved and should return the new plugin config.
    - Object extensions always have the priority over function extensions.
    - Extend multiple times to derive from the result of the previous extension.
  - NEW `configure` method to configure the properties of existing plugins. The difference with `extend` is that `configure` with not add new properties to the plugin, it will only modify existing ones.
  - NEW `extendPlugin` method to extend a nested plugin configuration.
  - NEW `configurePlugin` method to configure the properties of a nested plugin.
  - NEW `extendApi` method to extend the plugin API. The API is then merged into `editor.api[plugin.key]`.
  - NEW `extendTransforms` method to extend the plugin transforms. The transforms is then merged into `editor.transforms[plugin.key]`.
  - NEW `extendEditorApi` method to extend the editor API. The API is then merged into `editor.api`. Use this to add or override top-level methods to the editor.
  - NEW `extendEditorTransforms` method to extend the editor transforms. The transforms is then merged into `editor.transforms`.
  - NEW `extendOptions` method to extend the plugin options with selectors. Use `editor.useOption(plugin, 'optionKey')` to subscribe to an (extended) option.
  - NEW `withComponent` to replace `plugin.node.component`

  **Plugin Context**

  Each plugin method now receive the plugin context created with `getEditorPlugin(editor, plugin)` as parameter:

  - `api`
  - `editor`
  - `getOption`
  - `getOptions`
  - `plugin`
  - `setOption`
  - `setOptions`
  - `tf`
  - `type`
  - `useOption`

  **Core Plugins**:

  - NEW `ParagraphPlugin` is now part of `core`
  - NEW `DebugPlugin` is now part of `core`
    - NEW `api.debug.log`, `api.debug.info`, `api.debug.warn`, `api.debug.error` methods
    - `options.isProduction` to control logging in production environments
    - `options.logLevel` to set the minimum log level
    - `options.logger` to customize logging behavior
    - `options.throwErrors` to control error throwing behavior, by default a `PlateError` will be thrown on `api.debug.error`
  - NEW - You can now override a core plugin by adding it to `editor.plugins`. Last plugin wins.
  - `createDeserializeHtmlPlugin` -> `HtmlPlugin`
    - NEW `api.html.deserialize`
  - `createEventEditorPlugin` -> `EventEditorPlugin`
    - `eventEditorStore` -> `EventEditorStore`
  - `createDeserializeAstPlugin` -> `AstPlugin`
  - `createEditorProtocolPlugin` -> `SlateNextPlugin`
    - NEW `editor.tf.toggle.block`
    - NEW `editor.tf.toggle.mark`
    - Remove `createNodeFactoryPlugin`, included in `SlateNextPlugin`.
    - Remove `createPrevSelectionPlugin`, included in `SlateNextPlugin`.
  - `createHistoryPlugin` -> `HistoryPlugin`
  - `createInlineVoidPlugin` -> `InlineVoidPlugin`
  - `createInsertDataPlugin` -> `ParserPlugin`
  - `createLengthPlugin` -> `LengthPlugin`
  - `createReactPlugin` -> `ReactPlugin`

  **Editor Creation**:

  NEW `withSlate`:

  - Extends an editor into a vanilla Plate editor
  - NEW `rootPlugin` option for configuring the root plugin

  NEW `withPlate`:

  - Extends an editor into a React Plate editor
  - Now extends `withSlate` with React-specific enhancements
  - NEW `useOptions` and `useOption` methods to the editor

  NEW `createSlateEditor`:

  - Create a vanilla Plate editor with server-side support

  `createPlateEditor`:

  - Plugin replacement mechanism: using `plugins`, any plugin with the same key that a previous plugin will **replace** it. That means you can now override core plugins that way, like `ReactPlugin`
  - `root` plugin is now created from `createPlateEditor` option as a quicker way to configure the editor than passing `plugins`. Since plugins can have nested plugins (think as a recursive tree), `plugins` option will be passed to `root` plugin `plugins` option.
  - Centralized editor resolution. Before, both `createPlateEditor` and `Plate` component were resolving the editor. Now, only `createPlateEditor` takes care of that. That means `id`, `value`, and other options are now controlled by `createPlateEditor`.
  - Remove `createPlugins`, pass plugins directly:

    - `components` -> `override.components`
    - `overrideByKey` -> `override.plugins`

  `createPlateEditor` options:

  - Rename `normalizeInitialValue` option to `shouldNormalizeEditor`
  - Move `components` to `override.components` to override components by key
  - Move `overrideByKey` to `override.plugins` to override plugins by key
  - Remove `disableCorePlugins`, use `override.enabled` instead
  - NEW `value` to set the initial value of the editor.
  - NEW `autoSelect?: 'end' | 'start' | boolean` to auto select the start of end of the editor. This is decoupled from `autoFocus`.
  - NEW `selection` to control the initial selection.
  - NEW `override.enabled` to disable plugins by key
  - NEW `rootPlugin?: (plugin: AnyPlatePlugin) => AnyPlatePlugin` to configure the root plugin. From here, you can for example call `configurePlugin` to configure any plugin.
  - NEW `api`, `decorate`, `extendEditor`, `handlers`, `inject`, `normalizeInitialValue`, `options`, `override`, `priority`, `render`, `shortcuts`, `transforms`, `useHooks`. These options will be passed to the very first `rootPlugin`.

  NEW `usePlateEditor()` hook to create a `PlateEditor` in a React component:

  - Uses `createPlateEditor` and `useMemo` to avoid re-creating the editor on every render.
  - Dependencies can be added to the hook to re-create the editor on demand. `id` option is always used as dependency.

  **Editor Methods**:

  `editor: PlateEditor`:

  - Move `redecorate` to `editor.api.redecorate`
  - Move `reset` to `editor.tf.reset`
  - Move `plate.set` to `editor.setPlateState`
  - Move `blockFactory` to `editor.api.create.block`
  - Move `childrenFactory` to `editor.api.create.value`
  - Rename `plugins` to `pluginList`
  - Rename `pluginsByKey` to `plugins`
  - NEW `getApi()` to get the editor API
  - NEW `getTransforms()` to get the editor transforms
  - Remove `getPlugin(editor, key)`, use `editor.getPlugin(plugin) or editor.getPlugin({ key })`
  - Remove `getPluginType`, use `editor.getType(plugin)` to get node type
  - Remove `getPluginInjectProps(editor, key)`, use `editor.getPlugin(plugin).inject.props`
  - NEW `getOptionsStore()` to get a plugin options store
  - Remove `getPluginOptions`, use `getOptions()`
  - NEW `getOption()` to get a plugin option
  - NEW `setOption()` to set a plugin option
  - NEW `setOptions()` to set multiple plugin options. Pass a function to use Immer. Pass an object to merge the options.
  - NEW `useOption` to subscribe to a plugin option in a React component
  - NEW `useOptions` to subscribe to a plugin options store in a React component
  - Remove `getPlugins`, use `editor.pluginList`
  - Remove `getPluginsByKey`, use `editor.plugins`
  - Remove `mapInjectPropsToPlugin`

  **Editor Types**:

  The new generic types are:

  - `V extends Value = Value`, `P extends AnyPluginConfig = PlateCorePlugin`
  - That means this function will **infer all plugin configurations** from the options passed to it:
    - `key`
    - `options`
    - `api`
    - `transforms`
  - Can't infer for some reason? Use `createTPlateEditor` for explicit typing.

  ```ts
  const editor = createPlateEditor({ plugins: [TablePlugin] });
  editor.api.htmlReact.serialize(); // core plugin is automatically inferred
  editor.tf.insert.tableRow(); // table plugin is automatically inferred
  ```

  **Plate Component**

  `PlateProps`:

  - `editor` is now required. If `null`, `Plate` will not render anything. As before, `Plate` remounts on `id` change.
  - Remove `id`, `plugins`, `maxLength`, pass these to `createPlateEditor` instead
  - Remove `initialValue`, `value`, pass `value` to `createPlateEditor` instead
  - Remove `editorRef`
  - Remove `disableCorePlugins`, override `plugins` in `createPlateEditor` instead

  Utils:

  - Remove `useReplaceEditor` since `editor` is now always controlled
  - NEW `useEditorPlugin` to get the editor and the plugin context.

  Types:

  - `PlateRenderElementProps`, `PlateRenderLeafProps` generics: `V, N` -> `N, C`

  **Plate Store**:

  - Remove `plugins` and `rawPlugins`, use `useEditorRef().plugins` instead, or listen to plugin changes with `editor.useOption(plugin, <optionKey>)`
  - Remove `value`, use `useEditorValue()` instead
  - Remove `editorRef`, use `useEditorRef()` instead

  **Miscellaneous Changes**

  - `slate >=0.103.0` peer dependency
  - `slate-react >=0.108.0` peer dependency
  - New dependency `@udecode/react-hotkeys`
  - Remove `ELEMENT_`, `MARK_` and `KEY_` constants. Use `NamePlugin.key` instead.
  - Replace `ELEMENT_DEFAULT` with `ParagraphPlugin.key`.
  - Remove `getTEditor`
  - Rename `withTReact` to `withPlateReact`
  - Rename `withTHistory` to `withPlateHistory`
  - Rename `usePlateId` to `useEditorId`
  - Remove `usePlateSelectors().id()`, `usePlateSelectors().value()`, `usePlateSelectors().plugins()`, use instead `useEditorRef().<key>`
  - Rename `toggleNodeType` to `toggleBlock`
  - `toggleBlock` options:
    - Rename `activeType` to `type`
    - Rename `inactiveType` to `defaultType`
  - Remove `react-hotkeys-hook` re-exports. Use `@udecode/react-hotkeys` instead.

  Types:

  - Move `TEditableProps`, `TRenderElementProps` to `@udecode/slate-react`
  - Remove `<V extends Value>` generic in all functions where not used
  - Remove `PlatePluginKey`
  - Remove `OverrideByKey`
  - Remove `PlateId`

## @udecode/plate-csv@37.0.0

- [#3420](https://github.com/udecode/plate/pull/3420) by [@zbeyens](https://github.com/zbeyens) –
  - `createDeserializeCsvPlugin` -> `CsvPlugin`

## @udecode/plate-cursor@37.0.0

- [#3420](https://github.com/udecode/plate/pull/3420) by [@zbeyens](https://github.com/zbeyens) –
  - `createCursorPlugin` -> `CursorPlugin`

## @udecode/plate-date@37.0.0

- [#3420](https://github.com/udecode/plate/pull/3420) by [@zbeyens](https://github.com/zbeyens) –
  - `createDatePlugin` -> `DatePlugin`

## @udecode/plate-diff@37.0.0

- [#3420](https://github.com/udecode/plate/pull/3420) by [@zbeyens](https://github.com/zbeyens) –
  - `createDiffPlugin` -> `DiffPlugin`

## @udecode/plate-dnd@37.0.0

- [#3420](https://github.com/udecode/plate/pull/3420) by [@zbeyens](https://github.com/zbeyens) –
  - `createDndPlugin` -> `DndPlugin`
  - Remove `editor.isDragging`, use `editor.getOptions(DndPlugin).isDragging` instead
  - Move `dndStore` to `DndPlugin`

## @udecode/plate-docx@37.0.0

- [#3420](https://github.com/udecode/plate/pull/3420) by [@zbeyens](https://github.com/zbeyens) –
  - `createDeserializeDocxPlugin` -> `DocxPlugin`

## @udecode/plate-emoji@37.0.0

- [#3420](https://github.com/udecode/plate/pull/3420) by [@zbeyens](https://github.com/zbeyens) –
  - `createEmojiPlugin` -> `EmojiPlugin`
  - NEW `EmojiInputPlugin`

## @udecode/plate-excalidraw@37.0.0

- [#3420](https://github.com/udecode/plate/pull/3420) by [@zbeyens](https://github.com/zbeyens) –
  - `createExcalidrawPlugin` -> `ExcalidrawPlugin`
  - `insertExcalidraw` remove `key` option

## @udecode/plate-find-replace@37.0.0

- [#3420](https://github.com/udecode/plate/pull/3420) by [@zbeyens](https://github.com/zbeyens) –
  - `createFindReplacePlugin` -> `FindReplacePlugin`

## @udecode/plate-floating@37.0.0

- [#3420](https://github.com/udecode/plate/pull/3420) by [@zbeyens](https://github.com/zbeyens) –
  - Remove unused generics

## @udecode/plate-font@37.0.0

- [#3420](https://github.com/udecode/plate/pull/3420) by [@zbeyens](https://github.com/zbeyens) –
  - `createFontBackgroundColorPlugin` -> `FontBackgroundColorPlugin`
  - `createFontColorPlugin` -> `FontColorPlugin`
  - `createFontSizePlugin` -> `FontSizePlugin`
  - `createFontFamilyPlugin` -> `FontFamilyPlugin`
  - `createFontWeightPlugin` -> `FontWeightPlugin`

## @udecode/plate-heading@37.0.0

- [#3420](https://github.com/udecode/plate/pull/3420) by [@zbeyens](https://github.com/zbeyens) –
  - `createHeadingPlugin` -> `HeadingPlugin`
  - Replace `ELEMENT_H1` with `HEADING_KEYS.H1`
  - Replace `KEYS_HEADING` with `HEADING_LEVELS`

## @udecode/plate-highlight@37.0.0

- [#3420](https://github.com/udecode/plate/pull/3420) by [@zbeyens](https://github.com/zbeyens) –
  - `createHighlightPlugin` -> `HighlightPlugin`

## @udecode/plate-horizontal-rule@37.0.0

- [#3420](https://github.com/udecode/plate/pull/3420) by [@zbeyens](https://github.com/zbeyens) –
  - `createHorizontalRulePlugin` -> `HorizontalRulePlugin`

## @udecode/plate-html@37.0.0

- [#3420](https://github.com/udecode/plate/pull/3420) by [@zbeyens](https://github.com/zbeyens) –
  - `createDeserializeHtmlPlugin` -> `HtmlPlugin`
  - Rename `deserializeHtml` plugin to `html`
  - Rename `deserializeHtml.getNode` to `parse`

## @udecode/plate-indent@37.0.0

- [#3420](https://github.com/udecode/plate/pull/3420) by [@zbeyens](https://github.com/zbeyens) –
  - `createIndentPlugin` -> `IndentPlugin`

## @udecode/plate-indent-list@37.0.0

- [#3420](https://github.com/udecode/plate/pull/3420) by [@zbeyens](https://github.com/zbeyens) –
  - `createIndentListPlugin` -> `IndentListPlugin`
  - Rename `injectIndentListComponent` to `renderIndentListBelowNodes`
  - Replace `normalizeIndentList` with `withNormalizeIndentList`
  - Replace `deleteBackwardIndentList` with `withDeleteBackwardIndentList`
  - Replace `insertBreakIndentList` with `withInsertBreakIndentList`
  - Remove types: `LiFC` (use `PlateRenderElementProps`), `MarkerFC` (use `Omit<PlateRenderElementProps, 'children'>`)

## @udecode/plate-juice@37.0.0

- [#3420](https://github.com/udecode/plate/pull/3420) by [@zbeyens](https://github.com/zbeyens) –
  - `createJuicePlugin` -> `JuicePlugin`

## @udecode/plate-kbd@37.0.0

- [#3420](https://github.com/udecode/plate/pull/3420) by [@zbeyens](https://github.com/zbeyens) –
  - `createKbdPlugin` -> `KbdPlugin`

## @udecode/plate-layout@37.0.0

- [#3420](https://github.com/udecode/plate/pull/3420) by [@zbeyens](https://github.com/zbeyens) –
  - `createColumnPlugin` -> `ColumnPlugin`
  - NEW `ColumnItemPlugin`

## @udecode/plate-line-height@37.0.0

- [#3420](https://github.com/udecode/plate/pull/3420) by [@zbeyens](https://github.com/zbeyens) –
  - `createLineHeightPlugin` -> `LineHeightPlugin`

## @udecode/plate-link@37.0.0

- [#3420](https://github.com/udecode/plate/pull/3420) by [@zbeyens](https://github.com/zbeyens) –
  - `createLinkPlugin` -> `LinkPlugin`
  - Move `floatingLinkStore` to `LinkPlugin`

## @udecode/plate-list@37.0.0

- [#3420](https://github.com/udecode/plate/pull/3420) by [@zbeyens](https://github.com/zbeyens) –
  - `createListPlugin` -> `ListPlugin`
  - NEW `BulletedListPlugin`
  - NEW `NumberedListPlugin`
  - NEW `ListItemPlugin`
  - NEW `ListItemContentPlugin`
  - NEW list transforms: `toggle.list`, `toggle.bulletedList`, `toggle.numberedList`
  - Remove type utils: `getListItemType`, `getUnorderedListType`, `getOrderedListType`, `getListItemContentType`
  - Replace `insertBreakList(editor)` with `withInsertBreakList(ctx)`
  - Replace `insertFragmentList(editor)` with `withInsertFragmentList(ctx)`
  - Replace `insertBreakTodoList(editor)` with `withInsertBreakTodoList(ctx)`
  - Replace `deleteForwardList(editor)` with `withdeleteForwardList(ctx)`
  - Replace `deleteBackwardList(editor)` with `withdeleteBackwardList(ctx)`
  - Move list options from `ul` and `ol` to `list` plugin
  - `toggleList` options are now `{ type: string }`

## @udecode/plate-markdown@37.0.0

- [#3420](https://github.com/udecode/plate/pull/3420) by [@zbeyens](https://github.com/zbeyens) –
  - `createDeserializeMdPlugin` -> `MarkdownPlugin`

## @udecode/plate-math@37.0.0

- [#3420](https://github.com/udecode/plate/pull/3420) by [@zbeyens](https://github.com/zbeyens) –
  - `createMathPlugin` -> `MathPlugin`

## @udecode/plate-media@37.0.0

- [#3420](https://github.com/udecode/plate/pull/3420) by [@zbeyens](https://github.com/zbeyens) –
  - `createMediaPlugin` -> `MediaPlugin`
  - `FloatingMediaUrlInput`, `submitFloatingMedia` rename option `pluginKey` -> `plugin`
  - `insertMediaEmbed` remove `key` option

## @udecode/plate-mention@37.0.0

- [#3420](https://github.com/udecode/plate/pull/3420) by [@zbeyens](https://github.com/zbeyens) –
  - `createMentionPlugin` -> `MentionPlugin`
  - NEW `MentionInputPlugin`
  - Remove `createMentionNode` option, override `api.insert.mention` instead

## @udecode/plate-node-id@37.0.0

- [#3420](https://github.com/udecode/plate/pull/3420) by [@zbeyens](https://github.com/zbeyens) –
  - `createNodeIdPlugin` -> `NodeIdPlugin`

## @udecode/plate-normalizers@37.0.0

- [#3420](https://github.com/udecode/plate/pull/3420) by [@zbeyens](https://github.com/zbeyens) –
  - `createNormalizersPlugin` -> `NormalizersPlugin`

## @udecode/plate@37.0.0

- [#3420](https://github.com/udecode/plate/pull/3420) by [@zbeyens](https://github.com/zbeyens) –
  - NEW `@udecode/plate-layout`
  - NEW `/react` exports `@udecode/react-hotkeys`
  - Split build into `@udecode/plate` and `@udecode/plate/react`.
  - Remove `@udecode/plate-paragraph`
  - All stores now start with a capital letter

## @udecode/plate-utils@37.0.0

- [#3420](https://github.com/udecode/plate/pull/3420) by [@zbeyens](https://github.com/zbeyens) –
  - Remove `onKeyDownToggleElement`, use shortcuts instead.
  - Remove `onKeyDownToggleMark`, use shortcuts instead.

## @udecode/plate-playwright@37.0.0

- [#3473](https://github.com/udecode/plate/pull/3473) by [@12joan](https://github.com/12joan) – New package for integrating Plate with Playwright tests

## @udecode/plate-reset-node@37.0.0

- [#3420](https://github.com/udecode/plate/pull/3420) by [@zbeyens](https://github.com/zbeyens) –
  - `createResetNodePlugin` -> `ResetNodePlugin`

## @udecode/plate-resizable@37.0.0

- [#3420](https://github.com/udecode/plate/pull/3420) by [@zbeyens](https://github.com/zbeyens) –
  - Peer dependencies updated

## @udecode/plate-select@37.0.0

- [#3420](https://github.com/udecode/plate/pull/3420) by [@zbeyens](https://github.com/zbeyens) –
  - `createSelectOnBackspacePlugin` -> `SelectOnBackspacePlugin`
  - `createDeletePlugin` -> `DeletePlugin`

## @udecode/plate-selection@37.0.0

- [#3420](https://github.com/udecode/plate/pull/3420) by [@zbeyens](https://github.com/zbeyens) –
  - Rename `createSelectionPlugin` to `BlockSelectionPlugin`
  - Remove `isNodeBlockSelected`, `isBlockSelected`, `hasBlockSelected`, `useBlockSelected` functions
    - Use `editor.getOptions(BlockSelectionPlugin)` or `editor.useOptions(BlockSelectionPlugin)` instead
  - Remove `addSelectedRow` function
    - Use `editor.api.blockSelection.addSelectedRow` instead
  - Remove `withSelection` HOC
  - Rename `onCloseBlockSelection` to `onChangeBlockSelection`
  - Moved `blockSelectionStore` to `BlockSelectionPlugin`
  - Moved `blockContextMenuStore` to `BlockContextMenuPlugin`
  - Remove `BlockStartArea` and `BlockSelectionArea` components
    - Use `areaOptions` in `BlockSelectionPlugin` for configuration instead
  - Remove dependency on `@viselect/vanilla` package
    - Forked and integrated selection functionality locally
  - Add `BlockContextMenuPlugin`, which is now used by `BlockSelectionPlugin`
    - No need to add it manually
  - Fix scroll-related bugs in the selection functionality
  - Improve performance and reliability of block selection

## @udecode/plate-slash-command@37.0.0

- [#3420](https://github.com/udecode/plate/pull/3420) by [@zbeyens](https://github.com/zbeyens) –
  - `createSlashPlugin` -> `SlashPlugin`
  - NEW `SlashInputPlugin`

## @udecode/slate@37.0.0

- [#3420](https://github.com/udecode/plate/pull/3420) by [@zbeyens](https://github.com/zbeyens) – `createTEditor`:

  - Implement default methods for `slate-react` and `slate-history` in `createTEditor`
  - Add `noop` function to provide default implementations for unimplemented editor methods

  Types:

  - Merge `ReactEditor` and `HistoryEditor` interfaces into `TEditor`, removing `TReactEditor` and `THistoryEditor`
  - Remove `Value` generic type parameter from function signatures and type definitions
  - Replace `V extends Value` with `E extends TEditor` for improved type inference
  - Simplify `TEditor<V>` to `TEditor` in many places
  - Refactor element-related types, where `E extends TEditor` in all cases:
    - `EElement<V>` to `ElementOf<E>`
    - `EText<V>` to `TextOf<E>`
    - `ENode<V>` to `NodeOf<E>`
    - `EDescendant<V>` to `DescendantOf<E>`
    - `EAncestor<V>` to `AncestorOf<E>`
    - `EElementOrText<V>` to `ElementOrTextOf<E>`
  - Update `TNodeEntry` related types:
    - `ENodeEntry<V>` to `NodeEntryOf<E>`
    - `EElementEntry<V>` to `ElementEntryOf<E>`
    - `ETextEntry<V>` to `TextEntryOf<E>`
    - `EAncestorEntry<V>` to `AncestorEntryOf<E>`
    - `EDescendantEntry<V>` to `DescendantEntryOf<E>`
  - Remove unused types:
    - `EElementEntry<V>`
    - `ETextEntry<V>`
    - `EDescendantEntry<V>`

## @udecode/slate-react@37.0.0

- [#3420](https://github.com/udecode/plate/pull/3420) by [@zbeyens](https://github.com/zbeyens) – Types:

  - Remove `TReactEditor` type, as it's now integrated into the main `TEditor` type in `@udecode/slate`. Use `TEditor` instead.
  - Replace `V extends Value` with `E extends TEditor` for improved type inference
  - NEW `TEditableProps`, `TRenderElementProps`

## @udecode/slate-utils@37.0.0

- [#3420](https://github.com/udecode/plate/pull/3420) by [@zbeyens](https://github.com/zbeyens) – Types:

  - Replace `V extends Value` with `E extends TEditor` for improved type inference

## @udecode/plate-suggestion@37.0.0

- [#3420](https://github.com/udecode/plate/pull/3420) by [@zbeyens](https://github.com/zbeyens) –
  - `createSuggestionPlugin` -> `SuggestionPlugin`
  - Move `suggestionStore` to `SuggestionPlugin`
  - Remove `SuggestionProvider` and its hooks
  - Remove `useSuggestionStates` (replaced by direct option access)
  - Remove `useSuggestionSelectors` (replaced by option selectors)
  - Remove `useSuggestionActions` (replaced by api methods)
  - Replace `useUpdateSuggestion` with `api.suggestion.updateSuggestion`
  - Replace `useAddSuggestion` with `api.suggestion.addSuggestion`
  - Replace `useRemoveSuggestion` with `api.suggestion.removeSuggestion`
  - Replace `useSuggestionById` with `options.suggestionById`
  - Replace `useSuggestionUserById` with `options.suggestionUserById`
  - Replace `useCurrentSuggestionUser` with `options.currentSuggestionUser`
  - Remove `editor.activeSuggestionId`, use plugin option
  - Remove `useSetIsSuggesting`, use `editor.setOption`
  - Remove `useSetActiveSuggestionId`, use `editor.setOption`
  - Remove `editor.isSuggesting`, use plugin option
  - Remove `SuggestionEditorProps` type

## @udecode/plate-tabbable@37.0.0

- [#3420](https://github.com/udecode/plate/pull/3420) by [@zbeyens](https://github.com/zbeyens) –
  - `createTabbablePlugin` -> `TabbablePlugin`
  - `TabbablePlugin` option `isTabbable`: remove first `editor` parameter

## @udecode/plate-table@37.0.0

- [#3420](https://github.com/udecode/plate/pull/3420) by [@zbeyens](https://github.com/zbeyens) –
  - `createTablePlugin` -> `TablePlugin`
  - NEW `TableRowPlugin`, `TableCellPlugin`, `TableCellHeaderPlugin`
  - Replace `insertTableColumn` with `editor.insert.tableColumn`
  - Replace `insertTableRow` with `editor.insert.tableRow`
  - Move `cellFactory` option to `create.cell` api
  - Move `getCellChildren` option to `table.getCellChildren` api

## @udecode/plate-toggle@37.0.0

- [#3420](https://github.com/udecode/plate/pull/3420) by [@zbeyens](https://github.com/zbeyens) –
  - `createTogglePlugin` -> `TogglePlugin`
  - Move `toggleControllerStore` to `TogglePlugin`
  - Remove `setOpenIds` option
  - Replace `isToggleOpen` with option `isOpen`
  - Rename `injectToggle` to `renderToggleAboveNodes`

## @udecode/plate-trailing-block@37.0.0

- [#3420](https://github.com/udecode/plate/pull/3420) by [@zbeyens](https://github.com/zbeyens) –
  - `createTrailingBlockPlugin` -> `TrailingBlockPlugin`

## @udecode/plate-yjs@37.0.0

- [#3420](https://github.com/udecode/plate/pull/3420) by [@zbeyens](https://github.com/zbeyens) –
  - `createYjsPlugin` -> `YjsPlugin`
  - Move `yjsStore` to `YjsPlugin`
  - Move `editor.yjs.provider` to `options.provider`
  - Rename `RenderAboveEditableYjs` to `YjsAboveEditable`

# 36.0.0

No breaking changes

# 35.0.0

## @udecode/plate-code-block@35.0.0

- [#3282](https://github.com/udecode/plate/pull/3282) by [@12joan](https://github.com/12joan) – Make the dependency on prismjs optional

  New usage:

  ```ts
  // Import Prism with your supported languages
  import Prism from 'prismjs';

  import 'prismjs/components/prism-antlr4.js';
  import 'prismjs/components/prism-bash.js';
  import 'prismjs/components/prism-c.js';
  // ...

  const plugins = createPlugins([
    createCodeBlockPlugin({
      options: {
        prism: Prism,
      },
    }),
  ]);
  ```

# 34.0.0

## @udecode/plate-selection@34.0.0

- Breaking Change: The `selectedColor` option for `BlockSelectable` has been deprecated. Please use `useBlockSelected` to customize the style of each node component.

- [#3241](https://github.com/udecode/plate/pull/3241) by [@felixfeng33](https://github.com/felixfeng33) – Add logic for the `block-context-menu` and improved the user experience for `block-selection`, such as interactions related to keyboard shortcuts, bug fixes.
- Starting from this version, a single Cmd+A will no longer select the entire document but will select the entire block instead. Double Cmd+A will use the blockSelection plugin to select all blocks. To disable this behavior, pass handlers: `{ onKeyDown: null }`.

# 33.0.0

## @udecode/plate-serializer-md@33.0.0

- [#3125](https://github.com/udecode/plate/pull/3125) by [@zbeyens](https://github.com/zbeyens) –
  - `serializeMd`: remove `nodes` option. `editor.children` is now serialized

# 32.0.0

None (CI release issue)

# 31.0.0

None (CI release issue)

# 30.0.0

## @udecode/plate-table@30.0.0

- [#2867](https://github.com/udecode/plate/pull/2867) by [@12joan](https://github.com/12joan) – Fix: in v28, `TableProvider` was incorrectly shared by all tables in the editor. `TableProvider` must now be rendered as part of `TableElement`.

# 29.0.0

## @udecode/plate-utils@29.0.0

- [#2829](https://github.com/udecode/plate/pull/2829) by [@zbeyens](https://github.com/zbeyens) –
  - Moved `withProps` to `@udecode/cn`
  - Moved `PortalBody`, `Text`, `Box`, `createPrimitiveComponent`, `createSlotComponent`, `withProviders` to `@udecode/react-utils`
  - Removed `getRootProps` (unused)

# 28.0.0

## @udecode/plate-core@28.0.0

- [`822f6f56b`](https://github.com/udecode/plate/commit/822f6f56be526a6e26f904b9e767c0bc09f1e28b) by [@12joan](https://github.com/12joan) –
  - Remove `{ fn: ... }` workaround for jotai stores that contain functions
  - Breaking change: `usePlateSelectors`, `usePlateActions` and `usePlateStates` no longer accept generic type arguments. If custom types are required, cast the resulting values at the point of use, or use hooks like `useEditorRef` that still provide generics.

# 27.0.0

## @udecode/plate-comments@27.0.0

- [#2763](https://github.com/udecode/plate/pull/2763) by [@12joan](https://github.com/12joan) –
  - Migrate store to `jotai@2`
  - Revert the breaking changes to `@udecode/plate-comments` made in 26.0.0

## @udecode/plate-core@27.0.0

- [#2763](https://github.com/udecode/plate/pull/2763) by [@12joan](https://github.com/12joan) –
  - Migrate store from `jotai@1` to `jotai@2`
    - New dependency: `jotai-x`. See https://github.com/udecode/jotai-x
    - Accessing a store without an explicit provider component is no longer supported. Attempting to do so will result in a warning in the console: `Tried to access jotai store '${storeName}' outside of a matching provider.`
  - Upgraded from `zustand@3` to `zustand@4`
    - See https://github.com/udecode/zustand-x
  - Rename `zustand-x` exports
    - `StateActions` -> `ZustandStateActions`
    - `StoreApi` -> `ZustandStoreApi`
    - `createStore` -> `createZustandStore`
    - Note that these exports are deprecated and should not be used in new code. They may be removed in a future version of Plate.

## @udecode/plate-resizable@27.0.0

- [#2763](https://github.com/udecode/plate/pull/2763) by [@12joan](https://github.com/12joan) –
  - Migrate store to `jotai@2`
  - Resizable components must now be wrapped inside a `ResizableProvider`

# 26.0.0

## @udecode/plate-comments@26.0.0

- [#2760](https://github.com/udecode/plate/pull/2760) by [@12joan](https://github.com/12joan) –
  - Renamed the `comments` prop on CommentsProvider to `initialComments` to reflect the fact that updating its value after the initial render has no effect
  - Removed the following props from CommentsProvider, since they represent the internal state of the comments plugin and should not be controlled externally:
    - `activeCommentId`
    - `addingCommentId`
    - `newValue`
    - `focusTextarea`
  - The following props on CommentsProvider can now be updated after the initial render (whereas prior to this version, doing so had no effect):
    - `myUserId`
    - `users`
    - `onCommentAdd`
    - `onCommentUpdate`
    - `onCommentDelete`

## @udecode/plate-serializer-html@26.0.0

- [#2733](https://github.com/udecode/plate/pull/2733) by [@dimaanj](https://github.com/dimaanj) –
  - [Breaking] `serializeHtml`: replaced option `slateProps` by `plateProps`.

# 25.0.1

## @udecode/plate-core@25.0.1

- [#2729](https://github.com/udecode/plate/pull/2729) by [@12joan](https://github.com/12joan) – **This is a breaking change meant to be part of v25, hence the patch.**
  On `deserializeHtml`, replace `stripWhitespace` with `collapseWhiteSpace`, defaulting to true. The `collapseWhiteSpace` option aims to parse white space in HTML according to the HTML specification, ensuring greater accuracy when pasting HTML from browsers.

## @udecode/plate-comments@25.0.0

- [#2725](https://github.com/udecode/plate/pull/2725) by [@EandrewJones](https://github.com/EandrewJones) – Remove `useCommentValue`, which was redundant with the hooks applied automatically in `CommentEditTextarea.tsx`.

# 24.0.0

## @udecode/plate-core@24.0.0

- [#2629](https://github.com/udecode/plate/pull/2629) by [@zbeyens](https://github.com/zbeyens) –

  - [**Breaking**] Rename `Plate` to `PlateContent`.
  - [**Breaking**] Rename `PlateProvider` to `Plate`.
  - [**Breaking**] Rendering `PlateContent` is now required in `Plate`. This allows you to choose where to render the editor next to other components like toolbar. Example:

  ```tsx
  // Before
  <Plate />
  // or
  <PlateProvider>
    <Plate />
  </PlateProvider>

  // After
  <Plate>
    <PlateContent />
  </Plate>
  ```

  - [**Breaking**] Remove provider props such as `plugins` from `PlateContent`. These props should be passed to `Plate`.
  - [**Breaking**] Remove `editableProps` prop from `PlateContent`. Move these as`PlateContent` props.
  - [**Breaking**] Remove `children` prop from `PlateContent`. Render instead these components after `PlateContent`.
  - [**Breaking**] Remove `firstChildren` prop from `PlateContent`. Render instead these components before `PlateContent`.
  - [**Breaking**] Remove `editableRef` prop from `PlateContent`. Use `ref` instead.
  - [**Breaking**] Remove `withPlateProvider`.
  - [**Breaking**] Rename `usePlateEditorRef` to `useEditorRef`.
  - [**Breaking**] Rename `usePlateEditorState` to `useEditorState`.
  - [**Breaking**] Rename `usePlateReadOnly` to `useEditorReadOnly`. This hook can be used below `Plate` while `useReadOnly` can only be used in node components.
  - [**Breaking**] Rename `usePlateSelection` to `useEditorSelection`.
  - [**Breaking**] Rename store attributes `keyDecorate`, `keyEditor` and `keySelection` to `versionDecorate`, `versionEditor` and `versionSelection`. These are now numbers incremented on each change.
  - [**Breaking**] Rename store attribute `isRendered` to `isMounted`.

# 23.0.0

## @udecode/plate-media@23.0.0

- [#2537](https://github.com/udecode/plate/pull/2537) by [@haydencarlson](https://github.com/haydencarlson) – `MediaEmbedElement` is now more headless with a smaller bundle size.
  Update the following components:

  - `npx shadcn@canary add media-embed-element`
    - now uses `react-lite-youtube-embed` for YouTube videos.
    - now uses `react-tweet` for Twitter tweets.
  - `npx shadcn@canary add image-element`

  Breaking changes:

  - Moved `Resizable` to `@udecode/plate-resizable`
  - Moved `Caption`, `CaptionTextarea` to `@udecode/plate-caption`
  - Removed `useMediaEmbed`, `MediaEmbedVideo`, `MediaEmbedTweet`, `Tweet`, `parseMediaUrl`, `mediaStore`
  - Removed `@udecode/resizable`, `scriptjs`, `react-textarea-autosize` dependencies
  - `MediaPlugin`
    - removed `rules`. Use `parsers` option instead.
    - removed `disableCaption`. Use `createCaptionPlugin` instead.
  - Caption is now a separate plugin. Install `@udecode/plate-caption` and add it to your plugins:

  ```ts
  import { ELEMENT_IMAGE, ELEMENT_MEDIA_EMBED } from '@udecode/plate-media';

  createCaptionPlugin({
    options: { pluginKeys: [ELEMENT_IMAGE, ELEMENT_MEDIA_EMBED] },
  });
  ```

## @udecode/plate-resizable@23.0.0

- [#2541](https://github.com/udecode/plate/pull/2541) by [@zbeyens](https://github.com/zbeyens) –
  - Package renamed to `@udecode/plate-resizable`.
  - `ResizeHandle` is now fully headless: no style is applied by default. Add your own `Resizable`, `ResizeHandle` components:
    - `npx shadcn@canary add resizable`

## @udecode/plate-table@23.0

- Removed `TableCellElementResizable`. Use `useTableCellElementResizableState` and `useTableCellElementResizable` instead.

# 22.0.0

Headless UI.

## @udecode/plate-ui@22.0.0

- [#2471](https://github.com/udecode/plate/pull/2471) by [@zbeyens](https://github.com/zbeyens) – This package is now a CLI to generate components. Install it as a dev dependency. See https://platejs.org/docs/components/cli.

Migration:

- [Manual installation](https://platejs.org/docs/components/installation/manual).
- For each unresolved import not listed in the following major changes (components from `@udecode/plate-ui-x`), generate the component using the [CLI](https://platejs.org/docs/components/cli).

## @udecode/plate-comments@22.0.0

- [#2471](https://github.com/udecode/plate/pull/2471) by [@zbeyens](https://github.com/zbeyens) – Removed:
  - `AccountCircleIcon`
  - `CheckIcon`
  - `MoreVertIcon`
  - `RefreshIcon`
  - `AvatarImage`
  - `CommentLinkButton`
  - `CommentLinkDialog`
  - `CommentLinkDialogCloseButton`
  - `CommentLinkDialogCopyLink`
  - `CommentLinkDialogInput`
  - `PlateCommentLeaf` for `useCommentLeafState`

## @udecode/plate-dnd@22.0.0

- [#2471](https://github.com/udecode/plate/pull/2471) by [@zbeyens](https://github.com/zbeyens) – Removed:
  - `Draggable`
  - `DraggableBlock`
  - `DraggableBlockToolbar`
  - `DraggableBlockToolbarWrapper`
  - `DraggableDropline`
  - `DraggableGutterLeftProps`
  - `DraggableRoot`
  - `DragHandle`

## @udecode/plate-link@22.0.0

- [#2471](https://github.com/udecode/plate/pull/2471) by [@zbeyens](https://github.com/zbeyens) – Removed:
  - `FloatingLink`
  - `FloatingLinkEditButton`
  - `FloatingLinkTextInput`
  - `UnlinkButton`
  - `LaunchIcon`
  - `Link`
  - `LinkIcon`
  - `LinkOffIcon`
  - `ShortTextIcon`

## @udecode/plate-media@22.0.0

- [#2471](https://github.com/udecode/plate/pull/2471) by [@zbeyens](https://github.com/zbeyens) – Removed:
  - `MediaEmbed`

## @udecode/plate@22.0.0

- [#2471](https://github.com/udecode/plate/pull/2471) by [@zbeyens](https://github.com/zbeyens) – Plate 2.0 – Headless UI.
  Read the docs about the new UI pattern: https://platejs.org/docs/components.

  - Removed `@udecode/plate-ui` dependency.
  - Removed `@udecode/plate-emoji` dependency. You can install it separately.
  - Removed `styled-components` peerDependency.

  Replaced `@udecode/plate-headless` dependency (deprecated) by:

  - `@udecode/plate-alignment`
  - `@udecode/plate-autoformat`
  - `@udecode/plate-basic-elements`
  - `@udecode/plate-basic-marks`
  - `@udecode/plate-block-quote`
  - `@udecode/plate-break`
  - `@udecode/plate-code-block`
  - `@udecode/plate-combobox`
  - `@udecode/plate-comments`
  - `@udecode/plate-common`
  - `@udecode/plate-find-replace`
  - `@udecode/plate-floating`
  - `@udecode/plate-font`
  - `@udecode/plate-heading`
  - `@udecode/plate-highlight`
  - `@udecode/plate-horizontal-rule`
  - `@udecode/plate-indent`
  - `@udecode/plate-indent-list`
  - `@udecode/plate-kbd`
  - `@udecode/plate-line-height`
  - `@udecode/plate-link`
  - `@udecode/plate-list`
  - `@udecode/plate-media`
  - `@udecode/plate-mention`
  - `@udecode/plate-node-id`
  - `@udecode/plate-normalizers`
  - `@udecode/plate-paragraph`
  - `@udecode/plate-reset-node`
  - `@udecode/plate-select`
  - `@udecode/plate-serializer-csv`
  - `@udecode/plate-serializer-docx`
  - `@udecode/plate-serializer-html`
  - `@udecode/plate-serializer-md`
  - `@udecode/plate-suggestion`
  - `@udecode/plate-tabbable`
  - `@udecode/plate-table`
  - `@udecode/plate-trailing-block`
  - `@udecode/resizable`

## @udecode/plate-utils@22.0.0

- [#2471](https://github.com/udecode/plate/pull/2471) by [@zbeyens](https://github.com/zbeyens) – Upgraded peer dependencies:
  - `slate-react: >=0.95.0`
    Removed:
  - `useElementPrpos`
  - `useWrapElement`
  - `createComponentAs`
  - `createElementAs`

## @udecode/plate-table@22.0.0

- [#2471](https://github.com/udecode/plate/pull/2471) by [@zbeyens](https://github.com/zbeyens) – Removed:
  - `TableCellElement`
  - `TableCellElementResizableWrapper`
  - `TableCellElementRoot`
  - `TableElement`
  - `TableElementCol`
  - `TableElementColGroup`
  - `TableElementRoot`
  - `TableElementTBody`
  - `TableRowElement`
  - `ArrowDropDownCircleIcon`
  - `BorderAllIcon`
  - `BorderBottomIcon`
  - `BorderLeftIcon`
  - `BorderNoneIcon`
  - `BorderOuterIcon`
  - `BorderRightIcon`
  - `BorderTopIcon`

# 21.0.0

## @udecode/slate@21.0.0

- [#2369](https://github.com/udecode/plate/pull/2369) by [@zbeyens](https://github.com/zbeyens) – Support `slate@0.94.0`, `slate-react@0.94.0` and `slate-history@0.93.0` by upgrading the peer dependencies.

# 20.0.0

## @udecode/plate-core@20.0.0

- [`0077402`](https://github.com/udecode/plate/commit/00774029236d37737abdadf49b074e613e290792) by [@zbeyens](https://github.com/zbeyens) –
  - This package has been split into multiple packages for separation of concerns and decoupled versioning:
    - `@udecode/utils` is a collection of miscellaneous utilities. Can be used by any project.
    - `@udecode/slate` is a collection of `slate` experimental features and bug fixes that may be moved into `slate` one day. It's essentially composed of the generic types. Can be used by vanilla `slate` consumers without plate.
    - `@udecode/slate-react` is a collection of `slate-react` experimental features and bug fixes that that may be moved into `slate-react` one day. It's essentially composed of the generic types. Can be used by vanilla `slate-react` consumers without plate.
    - `@udecode/plate-core` is the minimalistic core of plate. It essentially includes `Plate`, `PlateProvider` and their dependencies. Note this package is not dependent on the `*-utils` packages.
    - `@udecode/slate-utils` is a collection of utils depending on `@udecode/slate`. Can be used by vanilla `slate` consumers without plate.
    - `@udecode/plate-utils` is a collection of utils depending on `@udecode/slate-react` and `@udecode/plate-core`
    - `@udecode/plate-common` re-exports the 6 previous packages and is a dependency of all the other packages. It's basically replacing `@udecore/plate-core` as a bundle.
  - Removed `getPreventDefaultHandler` since it is no longer needed.
    **Migration**:
    - If using `@udecode/plate` or `@udecode/plate-headless`: none
    - Else: find & replace `@udecode/plate-core` by `@udecode/plate-common`

## @udecode/plate-link@20.0.0

- [#2240](https://github.com/udecode/plate/pull/2240) by [@OliverWales](https://github.com/OliverWales) –
  - Add `allowedSchemes` plugin option
    - Any URL schemes other than `http(s)`, `mailto` and `tel` must be added to `allowedSchemes`, otherwise they will not be included in links

## @udecode/plate-table@20.0.0

- [#2251](https://github.com/udecode/plate/pull/2251) by [@zbeyens](https://github.com/zbeyens) –
  - `TablePlugin` option `disableUnsetSingleColSize` has been renamed and inverted into `enableUnsetSingleColSize`. New default is disabled. **Migration**:
    - if using `disableUnsetSingleColSize: true`, the option can be removed
    - if using `disableUnsetSingleColSize: false`, use `enableUnsetSingleColSize: true`
  - `getTableColumnIndex` second parameter type is now: `cellNode: TElement`

## @udecode/plate-ui-dnd@20.0.0

- [#2237](https://github.com/udecode/plate/pull/2237) by [@tmorane](https://github.com/tmorane) – Unstyled logic has been moved to `@udecode/plate-dnd`

  ```ts
  // before
  import { createDndPlugin } from '@udecode/plate-ui-dnd';

  // after
  import { createDndPlugin } from '@udecode/plate-dnd';
  ```

  Only `withPlateDraggable`, `withPlateDraggables` and `PlateDraggable` are left in `@udecode/plate-ui-dnd`.
  Renamed:

  - `withDraggables` -> `withPlateDraggables`. In the second parameter, draggable props options have been moved under `draggableProps`:

  ```tsx
  // before
  {
    onRenderDragHandle: () => {}
    styles,
  }

  // after
  {
    draggableProps: {
      onRenderDragHandle: () => {}
      styles,
    },
  }
  ```

## @udecode/plate-ui-table@20.0.0

- [#2251](https://github.com/udecode/plate/pull/2251) by [@zbeyens](https://github.com/zbeyens) – Headless components and hooks moved to `@udecode/plate-table`, so the following components have been renamed:
  - `TableElement` -> `PlateTableElement`
    - removed table border to set it at the cell level
    - `margin-left: 1px` to support cell borders
    - if all columns have a fixed size, the table will have a dynamic width instead of always 100%
  - `TableRowElement` -> `PlateTableRowElement`
  - `TableCellElement` -> `PlateTableCellElement`
    - removed td border in favor of td::before. The latter is responsible of having the border and the selected background color.
    - z-index: td is 0, td::before is 10, td::before in selected state is 20, handle is 30, handle resize is 40.
    - removed `selectedCell` div in favor of `::before`
  - `TablePopover` -> `PlateTablePopover`
    Styled props have been removed.

# 19.0.0

## @udecode/plate-core@19.0.0

- [#2097](https://github.com/udecode/plate/pull/2097) by [@zbeyens](https://github.com/zbeyens) –
  - upgrade deps, including typescript support for the new editor methods:
  ```json
  // from
  "slate": "0.78.0",
  "slate-history": "0.66.0",
  "slate-react": "0.79.0"
  // to
  "slate": "0.87.0",
  "slate-history": "0.86.0",
  "slate-react": "0.88.0"
  ```

## @udecode/plate@19.0.0

- [#2097](https://github.com/udecode/plate/pull/2097) by [@zbeyens](https://github.com/zbeyens) –
  - due to esm issues, dnd plugin is not part of plate package anymore. To use it, install `@udecode/plate-ui-dnd`
  ```ts
  // before
  import { createDndPlugin } from '@udecode/plate';
  // after
  import { createDndPlugin } from '@udecode/plate-ui-dnd';
  ```
  - upgrade peerDeps:
  ```json
  // from
  "slate": ">=0.78.0",
  "slate-history": ">=0.66.0",
  "slate-react": ">=0.79.0"
  // to
  "slate": ">=0.87.0",
  "slate-history": ">=0.86.0",
  "slate-react": ">=0.88.0"
  ```

# 18.0.0

## @udecode/plate-headless@18.0.0

- [#1889](https://github.com/udecode/plate/pull/1889) by [@zbeyens](https://github.com/zbeyens) –
  - `@udecode/plate-selection` package moved out from `@udecode/plate` because of https://github.com/Simonwep/selection/issues/124
  - Migration:
    - If not using `createBlockSelectionPlugin`, no migration is needed.
    - Otherwise, install `@udecode/plate-selection` and import `createBlockSelectionPlugin` from that package.

# 17.0.0

## @udecode/plate-core@17.0.0

- [#1871](https://github.com/udecode/plate/pull/1871) by [@zbeyens](https://github.com/zbeyens) –

  - `usePlateStore`:
    - Plate no longer has a global store containing all the editor states (zustand). Each editor store is now defined in a React context tree ([jotai](https://github.com/pmndrs/jotai)). If you need to access all the editor states at once (as you could do before), you'll need to build that layer yourself.
    - Plate store is now accessible only below `PlateProvider` or `Plate` (provider-less mode). It means it's no longer accessible outside of a Plate React tree. If you have such use-case, you'll need to build your own layer to share the state between your components.
    - You can nest many `PlateProvider` with different scopes (`id` prop). Default scope is `PLATE_SCOPE`
    - Hook usage:
      - `const value = usePlateSelectors(id).value()`
      - `const setValue = usePlateActions(id).value()`
      - `const [value, setValue] = usePlateStates(id).value()`
    - removed from the store:
      - `editableProps`, use the props instead
      - `enabled`, use conditional rendering instead
      - `isReady`, no point anymore as it's now directly ready
    - `useEventPlateId` is still used to get the last focused editor id.
    - Functions are stored in an object `{ fn: <here> }`
      - `const setOnChange = usePlateActions(id).onChange()`
      - `setOnChange({ fn: newOnChange })`
  - `Plate`
    - if rendered below `PlateProvider`, it will render `PlateSlate > PlateEditable`
    - if rendered without `PlateProvider`, it will render `PlateProvider > PlateSlate > PlateEditable`
    - default `id` is no longer `main`, it's now `PLATE_SCOPE`
  - `PlateProvider`
    - Each provider has an optional `scope`, so you can have multiple providers in the same React tree and use the plate hooks with the corresponding `scope`.
    - Plate effects are now run in `PlateProvider`
      - `initialValue, value, editor, normalizeInitialValue, normalizeEditor` are no longer defined in an effect (SSR support)
    - Props:
      - now extends the previous `Plate` props
      - if using `PlateProvider`, set the provider props on it instead of `Plate`. `Plate` would only need `editableProps` and `PlateEditableExtendedProps`
      - if not using it, set the provider props on `Plate`

  ```tsx
  // Before
  <PlateProvider>
    <Toolbar>
      <AlignToolbarButtons />
    </Toolbar>

    <Plate<MyValue> editableProps={editableProps} <MyValue> initialValue={alignValue} plugins={plugins} />
  </PlateProvider>

  // After
  <PlateProvider<MyValue> initialValue={alignValue} plugins={plugins}>
    <Toolbar>
      <AlignToolbarButtons />
    </Toolbar>

    <Plate<MyValue> editableProps={editableProps} />
  </PlateProvider>

  // After (provider-less mode)
  <Plate<MyValue> editableProps={editableProps} initialValue={alignValue} plugins={plugins} />
  ```

  - types:
    - store `editor` is no longer nullable
    - store `value` is no longer nullable
    - `id` type is now `PlateId`
  - renamed:
    - `SCOPE_PLATE` to `PLATE_SCOPE`
    - `getEventEditorId` to `getEventPlateId`
    - `getPlateActions().resetEditor` to `useResetPlateEditor()`
  - removed:
    - `plateIdAtom`
    - `usePlateId` for `usePlateSelectors().id()`
    - `EditablePlugins` for `PlateEditable`
    - `SlateChildren`
    - `PlateEventProvider` for `PlateProvider`
    - `withPlateEventProvider` for `withPlateProvider`
    - `usePlate`
    - `usePlatesStoreEffect`
    - `useEventEditorId` for `useEventPlateId`
    - `platesStore, platesActions, platesSelectors, usePlatesSelectors`
    - `getPlateActions` for `usePlateActions`
    - `getPlateSelectors` for `usePlateSelectors`
    - `getPlateEditorRef` for `usePlateEditorRef`
    - `getPlateStore, usePlateStore`
    - `EditorId` for `PlateId`

## @udecode/plate-code-block@17.0.0

- [#1871](https://github.com/udecode/plate/pull/1871) by [@zbeyens](https://github.com/zbeyens) –
  - Removed these imports because of build errors:
    - `prismjs/components/prism-django`
    - `prismjs/components/prism-ejs`
    - `prismjs/components/prism-php`

## @udecode/plate-ui@17.0.0

- [#1871](https://github.com/udecode/plate/pull/1871) by [@zbeyens](https://github.com/zbeyens) –
  - Removed `[ELEMENT_CODE_BLOCK]: CodeBlockElement` from Plate UI. You can define it in your app.

# 16.0.0

## @udecode/plate@16.0.0

## @udecode/plate-headless@16.0.0

- [#1721](https://github.com/udecode/plate/pull/1721) by [@zbeyens](https://github.com/zbeyens) –
  - deprecate `@udecode/plate-image` and `@udecode/plate-media-embed`, those got merged into `@udecode/plate-media`

## @udecode/plate-media@16.0.0

- [#1721](https://github.com/udecode/plate/pull/1721) by [@zbeyens](https://github.com/zbeyens) –
  - removed:
    - `useImageElement` for `useElement`
    - `MediaEmbedUrlInput` for `FloatingMediaUrlInput`
    - `parseEmbedUrl` for `parseMediaUrl`
    - `EmbedProviders`
  - renamed:
    - `ImageImg` to `Image`
    - `ImageCaptionTextarea` to `CaptionTextarea`
    - `useImageCaptionString` to `useCaptionString`
    - `ImageResizable` to `Resizable`

## @udecode/plate-ui-table@16.0.0

- [#1721](https://github.com/udecode/plate/pull/1721) by [@zbeyens](https://github.com/zbeyens) –
- `TableElementBase` props:
  - replace `onRenderContainer` by `floatingOptions` or by replacing `ELEMENT_TABLE` in the `createPlateUI` function.
- `TablePopover` is now a floating instead of tippy
- deps:
  - replaced `plate-ui-popover` by `plate-floating`

## @udecode/plate-ui@16.0.0

- [#1721](https://github.com/udecode/plate/pull/1721) by [@zbeyens](https://github.com/zbeyens) –
- deprecate `@udecode/plate-ui-popover` for `@udecode/plate-floating`

# 15.0.0

## @udecode/plate-combobox@15.0.0

- [#1677](https://github.com/udecode/plate/pull/1677) by [@zbeyens](https://github.com/zbeyens) –
  - deps:
    - replaced `@udecode/plate-ui-popper` by `@udecode/plate-floating`
  - `comboboxStore`:
    - removed `popperContainer`, use `floatingOptions` instead
    - removed `popperOptions`, use `floatingOptions` instead

## @udecode/plate-link@15.0.0

- [#1677](https://github.com/udecode/plate/pull/1677) by [@zbeyens](https://github.com/zbeyens) –
  - `createLinkPlugin`
    - removed `onKeyDownLink` for floating link
    - removed `hotkey` for `triggerFloatingLinkHotkeys`
  - removed:
    - `getAndUpsertLink` for `upsertLink`
    - `upsertLinkAtSelection` for `upsertLink`
  - `LinkToolbarButton`:
    - `onClick` now calls `triggerFloatingLink`

## @udecode/plate-table@15.0.0

- [#1677](https://github.com/udecode/plate/pull/1677) by [@zbeyens](https://github.com/zbeyens) –
- remove `addRow` for `insertTableRow`
- remove `addColumn` for `insertTableColumn`

## @udecode/plate@15.0.0

- [#1677](https://github.com/udecode/plate/pull/1677) by [@zbeyens](https://github.com/zbeyens) –
  - remove `@udecode/plate-ui-popper` dep for `@udecode/plate-floating`

## @udecode/plate-ui-button@15.0.0

- [#1677](https://github.com/udecode/plate/pull/1677) by [@zbeyens](https://github.com/zbeyens) –
  - moved `Button` to `@udecode/plate-button`
  - `Button` is now unstyled

## @udecode/plate-ui-popper@15.0.0

- [#1677](https://github.com/udecode/plate/pull/1677) by [@zbeyens](https://github.com/zbeyens) –
- deprecated, use instead `@udecode/plate-floating`

## @udecode/plate-ui-toolbar@15.0.0

- [#1677](https://github.com/udecode/plate/pull/1677) by [@zbeyens](https://github.com/zbeyens) –
- remove `@udecode/plate-ui-popper` and `react-popper` deps for `@udecode/plate-floating`
- `BalloonToolbarProps`:
  - removed `popperOptions` for `floatingOptions`
- remove `useBalloonToolbarPopper` for `useFloatingToolbar`

# 14.0.0

## @udecode/plate-core@14.0.0

- [#1633](https://github.com/udecode/plate/pull/1633) by [@tjramage](https://github.com/tjramage) – Moved `serializeHtml` and its utils to `@udecode/plate-serializer-html` as it has a new dependency: [html-entities](https://www.npmjs.com/package/html-entities).
  - If you're using `@udecode/plate`, no migration is needed
  - Otherwise, import it from `@udecode/plate-serializer-html`

# 13.0.0

## @udecode/plate-core@13.1.0

- `Plate` children are now rendered as last children of `Slate` (previously first children). To reproduce the previous behavior, move `children` to `firstChildren`

## @udecode/plate@13.0.0

## @udecode/plate-headless@13.0.0

- [#1585](https://github.com/udecode/plate/pull/1585) by [@zbeyens](https://github.com/zbeyens) – Removed `@udecode/plate-juice` from `@udecode/plate`. Install it if using `@udecode/plate-serializer-docx`:
  ```bash
  pnpm install @udecode/plate-juice
  ```

## @udecode/plate@13.0.0

## @udecode/plate-ui@13.0.0

## @udecode/plate-ui-dnd@13.0.0

- [#1585](https://github.com/udecode/plate/pull/1585) by [@zbeyens](https://github.com/zbeyens) – Moved `react-dnd react-dnd-html5-backend` deps to peer-dependencies. Install these if using `@udecode/plate-ui-dnd`:
  ```bash
  pnpm install react-dnd react-dnd-html5-backend
  ```

# 12.0.0

## @udecode/plate-ui-dnd@12.0.0

- [#1579](https://github.com/udecode/plate/pull/1579) by [@zbeyens](https://github.com/zbeyens) – renamed:
- `useDndBlock` options:
  - `blockRef` -> `nodeRef`
  - `removePreview` -> `preview.disable`
- `useDropBlockOnEditor` -> `useDropBlock`
- `useDropBlock` options:
  - `blockRef` -> `nodeRef`
  - `setDropLine` -> `onChangeDropLine`
    signature change:
- `getHoverDirection`:

```tsx
// before
(
  dragItem: DragItemBlock,
  monitor: DropTargetMonitor,
  ref: any,
  hoverId: string
)
// after
{
  dragItem,
  id,
  monitor,
  nodeRef,
}: GetHoverDirectionOptions
```

# 11.0.0

## @udecode/plate-core@11.0.6

- [#1500](https://github.com/udecode/plate/pull/1500) by [@zbeyens](https://github.com/zbeyens) – Thanks @ianstormtaylor for the initial work on https://github.com/ianstormtaylor/slate/pull/4177.

  This release includes major changes to plate and slate types:

  - Changing the `TEditor` type to be `TEditor<V>` where `V` represents the "value" being edited by Slate. In the most generic editor, `V` would be equivalent to `TElement[]` (since that is what is accepted as children of the editor). But in a custom editor, you might have `TEditor<Array<Paragraph | Quote>>`.
  - Other `TEditor`-and-`TNode`-related methods have been also made generic, so for example if you use `getLeafNode(editor, path)` it knows that the return value is a `TText` node. But more specifically, it knows that it is the text node of the type you've defined in your custom elements (with any marks you've defined).
  - This replaces the declaration merging approach, and provides some benefits. One of the drawbacks to declaration merging was that it was impossible to know whether you were dealing with an "unknown" or "known" element, since the underlying type was changed. Similarly, having two editors on the page with different schemas wasn't possible to represent. Hopefully this approach with generics will be able to smoothly replace the declaration merging approach. (While being easy to migrate to, since you can pass those same custom element definitions into `TEditor` still.)

**Define your custom types**

- Follow https://platejs.org/docs/typescript example.

**Slate types**

Those Slate types should be replaced by the new types:

- `Editor` -> `TEditor<V extends Value = Value>`
  - Note that `TEditor` methods are not typed based on `Value` as it would introduce a circular dependency. You can use `getTEditor(editor)` to get the editor with typed methods.
- `ReactEditor` -> `TReactEditor<V extends Value = Value>`
- `HistoryEditor` -> `THistoryEditor<V extends Value = Value>`
- `EditableProps` -> `TEditableProps<V extends Value = Value>`
- `Node` -> `TNode`
- `Element` -> `TElement`
- `Text` -> `TText`
- `NodeEntry` -> `TNodeEntry`
- `NodeProps` -> `TNodeProps`

**Slate functions**

Those Slate functions should be replaced by the new typed ones:

- As the new editor type is not matching the slate ones, all `Transforms`, `Editor`, `Node`, `Element`, `Text`, `HistoryEditor`, `ReactEditor` functions should be replaced: The whole API has been typed into Plate core. See https://github.com/udecode/plate/packages/core/src/slate
- `createEditor` -> `createTEditor`
- `withReact` -> `withTReact`
- `withHistory` -> `withTHistory`

**Generic types**

- `<T = {}>` could be used to extend the editor type. It is now replaced by `<E extends PlateEditor<V> = PlateEditor<V>>` to customize the whole editor type.
- When the plugin type is customizable, these generics are used: `<P = PluginOptions, V extends Value = Value, E extends PlateEditor<V> = PlateEditor<V>>`, where `P` is the plugin options type.
- `Editor` functions are using `<V extends Value>` generic, where `V` can be a custom editor value type used in `PlateEditor<V>`.
- `Editor` functions returning a node are using `<N extends ENode<V>, V extends Value = Value>` generics, where `N` can be a custom returned node type.
- `Editor` callbacks (e.g. a plugin option) are using `<V extends Value = Value, E extends PlateEditor<V> = PlateEditor<V>>` generics, where `E` can be a custom editor type.
- `Node` functions returning a node are using `<N extends Node, R extends TNode = TNode>` generics.
- These generics are used by `<V extends Value, K extends keyof EMarks<V>>`: `getMarks`, `isMarkActive`, `removeMark`, `setMarks`, `ToggleMarkPlugin`, `addMark`, `removeEditorMark`
- `WithOverride` is a special type case as it can return a new editor type:

  ```tsx
  // before
  export type WithOverride<T = {}, P = {}> = (
    editor: PlateEditor<T>,
    plugin: WithPlatePlugin<T, P>
  ) => PlateEditor<T>;

  // after - where E is the Editor type (input), and EE is the Extended Editor type (output)
  export type WithOverride<
    P = PluginOptions,
    V extends Value = Value,
    E extends PlateEditor<V> = PlateEditor<V>,
    EE extends E = E,
  > = (editor: E, plugin: WithPlatePlugin<P, V, E>) => EE;
  ```

- `type TEditor<V extends Value>`
- `type PlateEditor<V extends Value>`

**Renamed functions**

- `getAbove` -> `getAboveNode`
- `getParent` -> `getParentNode`
- `getText` -> `getEditorString`
- `getLastNode` -> `getLastNodeByLevel`
- `getPointBefore` -> `getPointBeforeLocation`
- `getNodes` -> `getNodeEntries`
- `isStart` -> `isStartPoint`
- `isEnd` -> `isEndPoint`

**Replaced types**

Removing node props types in favor of element types (same props + extends `TElement`). You can use `TNodeProps` to get the node data (props).

- `LinkNodeData` -> `TLinkElement`
- `ImageNodeData` -> `TImageElement`
- `TableNodeData` -> `TTableElement`
- `MentionNodeData` -> `TMentionElement`
- `MentionNode` -> `TMentionElement`
- `MentionInputNodeData` -> `TMentionInputElement`
- `MentionInputNode` -> `TMentionInputElement`
- `CodeBlockNodeData` -> `TCodeBlockElement`
- `MediaEmbedNodeData` -> `TMediaEmbedElement`
- `TodoListItemNodeData` -> `TTodoListItemElement`
- `ExcalidrawNodeData` -> `TExcalidrawElement`

**Utils**

- `match` signature change:

```
<T extends TNode>(
  obj: T,
  path: TPath,
  predicate?: Predicate<T>
)
```

- `deleteFragment` is now using `Editor.deleteFragment`

## @udecode/plate-table@11.0.0

- `getEmptyTableNode` default options changed. Migration:

```tsx
// From (0 row count and col count, previously it was 2)
getEmptyTableNode(editor);
// To
getEmptyTableNode(editor, { rowCount: 2, colCount: 2 });
```

## @udecode/plate-styled-components@11.0.0

**Generic types**

- `type StyledElementProps<V extends Value, N extends TElement = EElement<V>, TStyles = {}>`

# 10.0.0

## @udecode/plate-ui-toolbar@10.0.0

- [#1377](https://github.com/udecode/plate/pull/1377) by [@zbeyens](https://github.com/zbeyens) – Before, `BalloonToolbar` could be outside `Plate`. Now, `BallonToolbar` should be a child of `Plate` to support multiple editors.

# 9.0.0

## @udecode/plate-core@9.0.0

- [#1303](https://github.com/udecode/plate/pull/1303) by [@zbeyens](https://github.com/zbeyens) –
  - `Plate`
    - `editor` prop can now be fully controlled: Plate is not applying `withPlate` on it anymore
  - `PlatePlugin.deserializeHtml`
    - can't be an array anymore
    - moved `validAttribute`, `validClassName`, `validNodeName`, `validStyle` to `deserializeHtml.rules` property
  - renamed `plateStore` to `platesStore`
  - `platesStore` is now a zustood store
  - `eventEditorStore` is now a zustood store
  - `getPlateId` now gets the last editor id if not focused or blurred
    - used by `usePlateEditorRef` and `usePlateEditorState`
  - removed:
    - `usePlateEnabled` for `usePlateSelectors(id).enabled()`
    - `usePlateValue` for `usePlateSelectors(id).value()`
    - `usePlateActions`:
      - `resetEditor` for `getPlateActions(id).resetEditor()`
      - `clearState` for `platesActions.unset()`
      - `setInitialState` for `platesActions.set(id)`
      - `setEditor` for `getPlateActions(id).editor(value)`
      - `setEnabled` for `getPlateActions(id).enabled(value)`
      - `setValue` for `getPlateActions(id).value(value)`
    - `getPlateState`
    - `usePlateState`
    - `usePlateKey`

## @udecode/plate@9.0.0

- [#1303](https://github.com/udecode/plate/pull/1303) by [@zbeyens](https://github.com/zbeyens) –
- renamed `plate-x-ui` to `plate-ui-x`: all packages depending on `styled-components` has `plate-ui` prefix
- renamed `plate-x-serializer` to `plate-serializer-x`
- is now exporting only these (new) packages:
  - `@udecode/plate-headless`: all unstyled packages
  - `@udecode/plate-ui`: all styled packages
- renamed `PlateState` to `PlateStoreState`

# 8.0.0

## @udecode/plate-indent-list@8.0.0

- [#1234](https://github.com/udecode/plate/pull/1234) by [@zbeyens](https://github.com/zbeyens) – Removed:

  - `IndentListPluginOptions` for `PlatePlugin`

  Rename:

  - `getIndentListInjectComponent` to `injectIndentListComponent`

## @udecode/plate-core@8.0.0

- [#1234](https://github.com/udecode/plate/pull/1234) by [@zbeyens](https://github.com/zbeyens) – Breaking changes:

  ### `Plate`

  - removed `components` prop:

  ```tsx
  // Before
  <Plate plugins={plugins} components={components} />;

  // After
  // option 1: use the plugin factory
  let plugins = [
    createParagraphPlugin({
      component: ParagraphElement,
    }),
  ];

  // option 2: use createPlugins
  plugins = createPlugins(plugins, {
    components: {
      [ELEMENT_PARAGRAPH]: ParagraphElement,
    },
  });

  <Plate plugins={plugins} />;
  ```

  - removed `options` prop:

  ```tsx
  // Before
  <Plate plugins={plugins} options={options} />;

  // After
  // option 1: use the plugin factory
  let plugins = [
    createParagraphPlugin({
      type: 'paragraph',
    }),
  ];

  // option 2: use createPlugins
  plugins = createPlugins(plugins, {
    overrideByKey: {
      [ELEMENT_PARAGRAPH]: {
        type: 'paragraph',
      },
    },
  });

  <Plate plugins={plugins} />;
  ```

  ### `PlatePlugin`

  - `key`
    - replacing `pluginKey`
    - is now required: each plugin needs a key to be retrieved by key.
  - all handlers have `plugin` as a second parameter:

  ```tsx
  // Before
  export type X<T = {}> = (editor: PlateEditor<T>) => Y;

  // After
  export type X<T = {}, P = {}> = (
    editor: PlateEditor<T>,
    plugin: WithPlatePlugin<T, P>
  ) => Y;
  ```

  - `serialize` no longer has `element` and `leaf` properties:

  ```ts
  type SerializeHtml = RenderFunction<
    PlateRenderElementProps | PlateRenderLeafProps
  >;
  ```

  Renamed:

  - `injectParentComponent` to `inject.aboveComponent`
  - `injectChildComponent` to `inject.belowComponent`
  - `overrideProps` to `inject.props`
    - `transformClassName`, `transformNodeValue`, `transformStyle` first parameter is no longer `editor` as it's provided by `then` if needed.
    - the previously `getOverrideProps` is now the core behavior if `inject.props` is defined.
  - `serialize` to `serializeHtml`
  - `deserialize` to `deserializeHtml`
    - can be an array
    - the old deserializer options are merged to `deserializeHtml`

  ```tsx
  type DeserializeHtml = {
    /** List of HTML attribute names to store their values in `node.attributes`. */
    attributeNames?: string[];

    /**
     * Deserialize an element. Use this instead of plugin.isElement if you don't
     * want the plugin to renderElement.
     *
     * @default plugin.isElement
     */
    isElement?: boolean;

    /**
     * Deserialize a leaf. Use this instead of plugin.isLeaf if you don't want the
     * plugin to renderLeaf.
     *
     * @default plugin.isLeaf
     */
    isLeaf?: boolean;

    /** Deserialize html element to slate node. */
    getNode?: (element: HTMLElement) => AnyObject | undefined;

    query?: (element: HTMLElement) => boolean;

    /**
     * Deserialize an element:
     *
     * - If this option (string) is in the element attribute names.
     * - If this option (object) values match the element attributes.
     */
    validAttribute?: string | { [key: string]: string | string[] };

    /** Valid element `className`. */
    validClassName?: string;

    /** Valid element `nodeName`. Set '*' to allow any node name. */
    validNodeName?: string | string[];

    /**
     * Valid element style values. Can be a list of string (only one match is
     * needed).
     */
    validStyle?: Partial<
      Record<keyof CSSStyleDeclaration, string | string[] | undefined>
    >;

    /** Whether or not to include deserialized children on this node */
    withoutChildren?: boolean;
  };
  ```

  - handlers starting by `on...` are moved to `handlers` property.

  ```ts
  // Before
  onDrop: handler;

  // After
  handlers: {
    onDrop: handler;
  }
  ```

  Removed:

  - `renderElement` is favor of:
    - `isElement` is a boolean that enables element rendering.
    - the previously `getRenderElement` is now the core behavior.
  - `renderLeaf` is favor of:
    - `isLeaf` is a boolean that enables leaf rendering.
    - the previously `getRenderLeaf` is now the core behavior.
  - `inlineTypes` and `voidTypes` for:
    - `isInline` is a boolean that enables inline rendering.
    - `isVoid` is a boolean that enables void rendering.

  ### General

  - the following plugins are now part of the core plugins, so you need to remove these from your `plugins` prop:

  ```ts
  const corePlugins = [
    createReactPlugin(),
    createHistoryPlugin(),
    createEventEditorPlugin(),
    createInlineVoidPlugin(),
    createInsertDataPlugin(),
    createDeserializeAstPlugin(),
    createDeserializeHtmlPlugin(),
  ];
  ```

  - `plugins` is not a parameter anymore as it can be retrieved in `editor.plugins`
  - `withInlineVoid` is now using plugins `isInline` and `isVoid` plugin properties.

  Renamed:

  - `getPlatePluginType` to `getPluginType`
  - `getEditorOptions` to `getPlugins`
  - `getPlatePluginOptions` to `getPlugin`
  - `pipeOverrideProps` to `pipeInjectProps`
  - `getOverrideProps` to `pluginInjectProps`
  - `serializeHTMLFromNodes` to `serializeHtml`
    - `getLeaf` to `leafToHtml`
    - `getNode` to `elementToHtml`
  - `xDeserializerId` to `KEY_DESERIALIZE_X`
  - `deserializeHTMLToText` to `htmlTextNodeToString`
  - `deserializeHTMLToMarks` to `htmlElementToLeaf` and `pipeDeserializeHtmlLeaf`
  - `deserializeHTMLToElement` to `htmlElementToElement` and `pipeDeserializeHtmlElement`
  - `deserializeHTMLToFragment` to `htmlBodyToFragment`
  - `deserializeHTMLToDocumentFragment` to `deserializeHtml`
  - `deserializeHTMLToBreak` to `htmlBrToNewLine`
  - `deserializeHTMLNode` to `deserializeHtmlNode`
  - `deserializeHTMLElement` to `deserializeHtmlElement`

  Removed:

  - `usePlateKeys`, `getPlateKeys`
  - `usePlateOptions` for `getPlugin`
  - `getPlateSelection` for `getPlateEditorRef().selection`
  - `flatMapByKey`
  - `getEditableRenderElement` and `getRenderElement` for `pipeRenderElement` and `pluginRenderElement`
  - `getEditableRenderLeaf` and `getRenderLeaf` for `pipeRenderLeaf` and `pluginRenderLeaf`
  - `getInlineTypes`
  - `getVoidTypes`
  - `getPlatePluginTypes`
  - `getPlatePluginWithOverrides`
  - `mapPlatePluginKeysToOptions`
  - `withDeserializeX` for `PlatePlugin.editor.insertData`

  Changed types:

  - `PlateEditor`:
    - removed `options` for `pluginsByKey`
  - `WithOverride` is not returning an extended editor anymore (input and output editors are assumed to be the same types for simplicity).
  - `PlateState`
    - renamed `keyChange` to `keyEditor`
    - removed `plugins` for `editor.plugins`
    - removed `pluginKeys`
    - removed `selection` for `editor.selection`
    - actions:
      - removed `setSelection`, `setPlugins`, `setPluginKeys`
      - removed `incrementKeyChange` for

  Renamed types:

  - `XHTMLY` to `XHtmlY`
  - `Deserialize` to `DeseralizeHtml`

  Removed types:

  - `PlatePluginOptions`:
    - `type` to `PlatePlugin.type`
    - `component` to `PlatePlugin.component`
    - `deserialize` to `PlatePlugin.deserializeHtml`
    - `getNodeProps` to `PlatePlugin.props.nodeProps`
    - `hotkey` to `HotkeyPlugin`
    - `clear` to `ToggleMarkPlugin`
    - `defaultType` is hardcoded to `p.type`
  - `OverrideProps` for `PlatePlugin.inject.props`
  - `Serialize` for `PlatePlugin.serializeHtml`
  - `NodeProps` for `AnyObject`
  - `OnKeyDownElementOptions` for `HotkeyPlugin`
  - `OnKeyDownMarkOptions` for `ToggleMarkPlugin`
  - `WithInlineVoidOptions`
  - `GetNodeProps` for `PlatePluginProps`
  - `DeserializeOptions`, `GetLeafDeserializerOptions`, `GetElementDeserializerOptions`, `GetNodeDeserializerOptions`, `GetNodeDeserializerRule`, `DeserializeNode` for `PlatePlugin.deserializeHtml`
  - `PlateOptions`
  - `RenderNodeOptions`
  - `DeserializedHTMLElement`

## @udecode/plate-find-replace@8.0.0

- [#1234](https://github.com/udecode/plate/pull/1234) by [@zbeyens](https://github.com/zbeyens) – Removed:
  - `useFindReplacePlugin` for `createFindReplacePlugin`

## @udecode/plate-alignment@8.0.0

- [#1234](https://github.com/udecode/plate/pull/1234) by [@zbeyens](https://github.com/zbeyens) –
  - `setAlign`
    - moved param 3 to param 2 as `setNodesOptions`

## @udecode/plate-basic-elements@8.0.0

- [#1234](https://github.com/udecode/plate/pull/1234) by [@zbeyens](https://github.com/zbeyens) –
  - renamed `createBasicElementPlugins` to `createBasicElementsPlugin`

## @udecode/plate-code-block@8.0.0

- [#1234](https://github.com/udecode/plate/pull/1234) by [@zbeyens](https://github.com/zbeyens) – Removed:
  - `getCodeBlockPluginOptions` for `getPlugin`
  - `getCodeLinePluginOptions` for `getPlugin`

## @udecode/plate-heading@8.0.0

- [#1234](https://github.com/udecode/plate/pull/1234) by [@zbeyens](https://github.com/zbeyens) – Renamed:
  - `HeadingPluginOptions` to `HeadingsPlugin`

## @udecode/plate-mention@8.0.0

- [#1234](https://github.com/udecode/plate/pull/1234) by [@zbeyens](https://github.com/zbeyens) – Removed:
  - `getMentionInputPluginOptions` for `getPlugin`
  - `getMentionInputType` for `getPluginType`
  - `COMBOBOX_TRIGGER_MENTION`

## @udecode/plate-basic-marks@8.0.0

- [#1234](https://github.com/udecode/plate/pull/1234) by [@zbeyens](https://github.com/zbeyens) –
  - renamed `createBasicMarkPlugins` to `createBasicMarksPlugin`

## @udecode/plate@8.0.0

- [#1234](https://github.com/udecode/plate/pull/1234) by [@zbeyens](https://github.com/zbeyens) – Breaking changes:

  - all plugins options are now defined in the plugin itself
  - plugins which now have nested plugins instead of array:
    - `createBasicElementsPlugin`
    - `createCodeBlockPlugin`
    - `createHeadingPlugin`
    - `createListPlugin`
    - `createTablePlugin`
    - `createBasicMarksPlugin`

  Removed:

  - `createEditorPlugins` for `createPlateEditor` (without components) and `createPlateEditorUI` (with Plate components)
  - `createPlateOptions` for `createPlugins`
  - all `DEFAULTS_X`: these are defined in the plugins
  - all `getXDeserialize`: these are defined in the plugins
  - all `WithXOptions` for extended plugins
  - all `getXRenderElement`
  - some plugin option types are removed for `PlatePlugin`

  Renamed:

  - `createPlateComponents` to `createPlateUI`
  - all `getXY` handlers to `yX` (e.g. `getXOnKeyDown` to `onKeyDownX`)
  - all `XPluginOptions` to `XPlugin`
  - all `pluginKey` parameter to `key` except in components

  Renamed types:

  - `DecorateSearchHighlightOptions` to `FindReplacePlugin`

  Updated deps:

  - `"slate": "0.70.0"`
  - `"slate-react": "0.70.1"`

  Removed deps (merged to core):

  - `plate-common`
  - `plate-ast-serializer`
  - `plate-html-serializer`
  - `plate-serializer`

## @udecode/plate-serializer-csv@8.0.0

- [#1234](https://github.com/udecode/plate/pull/1234) by [@zbeyens](https://github.com/zbeyens) – Renamed:
  - `createDeserializeCSVPlugin` to `createDeserializeCsvPlugin`
  - `deserializeCSV` to `deserializeCsv`

## @udecode/plate-serializer-md@8.0.0

- [#1234](https://github.com/udecode/plate/pull/1234) by [@zbeyens](https://github.com/zbeyens) –

  - `createDeserializeMdPlugin`:
    - is now disabled if there is html data in the data transfer.

  Renamed:

  - `createDeserializeMDPlugin` to `createDeserializeMdPlugin`
  - `deserializeMD` to `deserializeMd`

# 7.0.0

## `@udecode/plate-core`

- renamed:
  - `SPEditor` to `PEditor` (note that `PlateEditor` is the new default)
  - `SPRenderNodeProps` to `PlateRenderNodeProps`
  - `SPRenderElementProps` to `PlateRenderElementProps`
  - `SPRenderLeafProps` to `PlateRenderLeafProps`
  - `useEventEditorId` to `usePlateEventId`
  - `useStoreEditorOptions` to `usePlateOptions`
  - `useStoreEditorRef` to `usePlateEditorRef`
  - `useStoreEditorSelection` to `usePlateSelection`
  - `useStoreEditorState` to `usePlateEditorState`
  - `useStoreEditorValue` to `usePlateValue`
  - `useStoreEnabled` to `usePlateEnabled`
  - `useStorePlate` to `usePlatePlugins`
  - `useStorePlatePluginKeys` to `usePlateKeys`
  - `useStoreState` to `usePlateState`
- `getPlateId`: Get the last focused editor id, else get the last blurred editor id, else get the first editor id, else `null`
- `getPlateState`:
  - removed first parameter `state`
  - previously when giving no parameter, it was returning the first editor. Now it's returning the editor with id = `getPlateId()`. It means `useEventEditorId('focus')` is no longer needed for
    - `usePlateEditorRef`
    - `usePlateEditorState`
    - `usePlateX`...

## `@udecode/plate-alignment`

- `setAlign`: option `align` renamed to `value`
- removed `getAlignOverrideProps()` in favor of `getOverrideProps(KEY_ALIGN)`

## `@udecode/plate-indent`

- removed `getIndentOverrideProps()` in favor of `getOverrideProps(KEY_INDENT)`
- rename `onKeyDownHandler` to `getIndentOnKeyDown()`
- `IndentPluginOptions`
  - rename `types` to `validTypes`
  - rename `cssPropName` to `styleKey`
  - rename `transformCssValue` to `transformNodeValue`

## `@udecode/plate-line-height`

- `setLineHeight`: option `lineHeight` renamed to `value`
- removed `getLineHeightOverrideProps` in favor of `getOverrideProps(KEY_LINE_HEIGHT)`

## `@udecode/plate-mention`

- `getMentionOnSelectItem`:
  - removed `createMentionNode` in favor of plugin options
  - removed `insertSpaceAfterMention` in favor of plugin options

## `@udecode/plate-mention-ui`

- `MentionCombobox` props:
  - removed `trigger` in favor of plugin options
  - removed `insertSpaceAfterMention` in favor of plugin options
  - removed `createMentionNode` in favor of plugin options

## `@udecode/plate-x-ui`

- renamed `ToolbarAlign` to `AlignToolbarButton`
- renamed `ToolbarCodeBlock` to `CodeBlockToolbarButton`
- renamed `ToolbarElement` to `BlockToolbarButton`
- renamed `ToolbarImage` to `ImageToolbarButton`
- renamed `ToolbarLink` to `LinkToolbarButton`
- renamed `ToolbarList` to `ListToolbarButton`
- renamed `ToolbarLineHeight` to `LineHeightToolbarDropdown`
- renamed `ToolbarMark` to `MarkToolbarButton`
- renamed `ToolbarMediaEmbed` to `MediaEmbedToolbarButton`
- renamed `ToolbarSearchHighlight` to `SearchHighlightToolbar`
- renamed `ToolbarTable` to `TableToolbarButton`

# 6.0.0

## `@udecode/plate-alignment`

The align plugin is no longer wrapping a block, but instead setting an `align` property to an existing block.

- `createAlignPlugin`:
  - removed `pluginKeys`, `renderElement` and `deserialize`
- removed:
  - `ELEMENT_ALIGN_LEFT`
  - `ELEMENT_ALIGN_CENTER`
  - `ELEMENT_ALIGN_RIGHT`
  - `ELEMENT_ALIGN_JUSTIFY`
  - `KEYS_ALIGN` in favor of `KEY_ALIGN`
  - `getAlignDeserialize`
  - `upsertAlign` in favor of `setAlign`

Migration (normalizer):

- for each node:
  - run `parent = getParent(editor, path)`, if `parent[0].type` is one of the alignment values:
    - run `setAlign(editor, { align }, { at: path })`
    - run `unwrapNodes(editor, { at: path })`

## `@udecode/plate-alignment-ui`

- `ToolbarAlignProps`:
  - removed `type` in favor of `align`
  - removed `unwrapTypes`
  - added `align`

# 5.0.0

## `@udecode/plate-mention`

The mention plugin is now using the combobox.

- removed `useMentionPlugin` in favor of `createMentionPlugin`
  - migration: replace `useMentionPlugin().plugin` by `createMentionPlugin()`
- removed options:
  - `mentionableSearchPattern`
  - `insertSpaceAfterMention`
  - `maxSuggestions`: moved to `comboboxStore`
  - `trigger`: moved to `comboboxStore`
  - `mentionables`: moved to `items` in `comboboxStore`
  - `mentionableFilter`: moved to `filter` in `comboboxStore`
- removed `matchesTriggerAndPattern` in favor of `getTextFromTrigger`
- removed `MentionNodeData` in favor of `ComboboxItemData`

```ts
export interface ComboboxItemData {
  /** Unique key. */
  key: string;
  /** Item text. */
  text: any;
  /**
   * Whether the item is disabled.
   *
   * @default false
   */
  disabled?: boolean;
  /** Data available to `onRenderItem`. */
  data?: unknown;
}
```

## `@udecode/plate-mention-ui`

- removed `MentionSelect` in favor of `MentionCombobox`

## `@udecode/plate-toolbar`

- removed `setPositionAtSelection` in favor of `useBalloonToolbarPopper`
- removed `useBalloonMove` in favor of `useBalloonToolbarPopper`
- removed `usePopupPosition` in favor of `useBalloonToolbarPopper`
- removed `useBalloonShow` in favor of `useBalloonToolbarPopper`
  `BalloonToolbar` props:
- removed `direction` in favor of `popperOptions.placement`
- renamed `scrollContainer` to `popperContainer`

# 4.0.0

## `@udecode/plate-toolbar`

- `BalloonToolbar`: removed `hiddenDelay` prop.

# 3.0.0

## All UI packages

There was multiple instances of `styled-components` across all the packages.
So we moved `styled-components` from dependencies to peer dependencies.

### Before

`styled-components` was not listed in your dependencies

### After

Add `styled-components` to your dependencies

# 2.0.0

## `@udecode/plate-autoformat`

- `autoformatBlock`:
  - signatude changed

```ts
// Before
(
  editor: TEditor,
  type: string,
  at: Location,
  options: Pick<AutoformatRule, 'preFormat' | 'format'>
)
```

```ts
// After
(editor: TEditor, options: AutoformatBlockOptions)
```

- moved the checks from `withAutoformat`
- `autoformatInline`:
  - renamed to `autoformatMark`
  - signatured changed

```ts
// Before
(
  editor: TEditor,
  options: Pick<AutoformatRule, 'type' | 'between' | 'markup' | 'ignoreTrim'>
)
```

```ts
// After
(
  editor: TEditor,
  options: AutoformatMarkOptions
)
```

- `AutoformatRule` is now `AutoformatBlockRule
| AutoformatMarkRule
| AutoformatTextRule;`
  - `mode: 'inline'` renamed to `mode: 'mark'`
  - `markup` and `between` have been replaced by `match: string | string[] | MatchRange | MatchRange[]`: The rule applies when the trigger and the text just before the cursor matches. For `mode: 'block'`: lookup for the end match(es) before the cursor. For `mode: 'text'`: lookup for the end match(es) before the cursor. If `format` is an array, also lookup for the start match(es). For `mode: 'mark'`: lookup for the start and end matches. Note: `'_*'`, `['_*']` and `{ start: '_*', end: '*_' }` are equivalent.
  - `trigger` now defaults to the last character of `match` or `match.end` (previously `' '`)
- the plugin now checks that there is no character before the start match to apply autoformatting. For example, nothing will happen by typing `a*text*`.


# Releases

Source: https://platejs.org/docs/releases

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Releases
---

<ReleaseIndex />


# AI

Source: https://platejs.org/docs/ai

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: AI
description: AI-powered writing assistance.
docs:
  - route: https://pro.platejs.org/docs/examples/ai
    title: Plus
---

[ai-demo registry content](https://platejs.org/r/ai-demo)

<PackageInfo>

## Features

- **Context-aware command menu** that adapts to cursor, text selection, and block selection workflows.
- **Streaming Markdown/MDX insertion** with table, column, and code block support powered by `streamInsertChunk`.
- **Insert and chat review modes** with localized insert previews plus undo-safe batching via `withAIBatch` and `tf.ai.undo()`.
- **Block selection aware transforms** to replace or append entire sections using `tf.aiChat.replaceSelection` and `tf.aiChat.insertBelow`.
- **Direct integration with `@ai-sdk/react`** so `api.aiChat.submit` can stream responses from Vercel AI SDK helpers.
- **Suggestion and comment utilities** that diff AI edits, accept/reject changes, and map AI feedback back to document ranges.

</PackageInfo>

## Kit Usage

<Steps>

### Installation

The fastest way to add AI functionality is with the `AIKit`. It ships the configured `AIPlugin`, `AIChatPlugin`, Markdown streaming helpers, cursor overlay, and their [Plate UI](/docs/installation/plate-ui) components.

[ai-kit registry content](https://platejs.org/r/ai-kit)

- [`AIMenu`](/docs/components/ai-menu): Floating command surface for prompts, tool shortcuts, and chat review.
- [`AILoadingBar`](/docs/components/ai-loading-bar): Displays streaming status at the editor container.
- [`AIAnchorElement`](/docs/components/ai-anchor-element): Invisible anchor node used to position the floating menu during streaming.
- [`AILeaf`](/docs/components/ai-leaf): Renders AI-marked text with subtle styling.

### Add Kit

```tsx
import { createPlateEditor } from 'platejs/react';
import { AIKit } from '@/components/editor/plugins/ai-kit';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    ...AIKit,
  ],
});
```

### Add API Route

Expose a streaming command endpoint that proxies your model provider:

[ai-api registry content](https://platejs.org/r/ai-api)

### Configure Environment

Set your AI Gateway key locally (replace with your provider secret if you are not using a gateway):

```bash title=".env.local"
AI_GATEWAY_API_KEY="your-api-key"
```

</Steps>

## Manual Usage

<Steps>

### Installation

```bash
npm install @platejs/ai @platejs/markdown @platejs/selection @ai-sdk/react ai
```

`@platejs/suggestion` is optional but required for diff-based edit suggestions.

### Add Plugins

```tsx
import { createPlateEditor } from 'platejs/react';
import { AIChatPlugin, AIPlugin } from '@platejs/ai/react';
import { BlockSelectionPlugin } from '@platejs/selection/react';
import { MarkdownPlugin } from '@platejs/markdown';

export const editor = createPlateEditor({
  plugins: [
    BlockSelectionPlugin,
    MarkdownPlugin,
    AIPlugin,
    AIChatPlugin, // extended in the next step
  ],
});
```

- `BlockSelectionPlugin`: Enables multi-block selections that `AIChatPlugin` relies on for insert/replace transforms.
- `MarkdownPlugin`: Provides Markdown serialization used by streaming utilities.
- `AIPlugin`: Adds the AI mark and transforms for undoing AI batches.
- `AIChatPlugin`: Supplies the AI combobox, API helpers, and transforms.

Use `AIPlugin.withComponent` with your own element (or [`AILeaf`](/docs/components/ai-leaf)) to highlight AI-generated text.

### Configure AIChatPlugin

Extend `AIChatPlugin` to hook streaming and edits. The example mirrors the core logic from `AIKit` while keeping the UI headless.

```tsx
import cloneDeep from 'lodash/cloneDeep';
import { BaseAIPlugin, withAIBatch } from '@platejs/ai';
import {
  AIChatPlugin,
  applyAISuggestions,
  getInsertPreviewStart,
  streamInsertChunk,
  useChatChunk,
} from '@platejs/ai/react';
import { ElementApi, getPluginType, KEYS, PathApi } from 'platejs';
import { usePluginOption } from 'platejs/react';

export const aiChatPlugin = AIChatPlugin.extend({
  options: {
    chatOptions: {
      api: '/api/ai/command',
      body: {
        model: 'openai/gpt-4o-mini',
      },
    },
    trigger: ' ',
    triggerPreviousCharPattern: /^\s?$/,
  },
  useHooks: ({ editor, getOption }) => {
    const mode = usePluginOption(AIChatPlugin, 'mode');
    const toolName = usePluginOption(AIChatPlugin, 'toolName');

    useChatChunk({
      onChunk: ({ chunk, isFirst, text }) => {
        if (isFirst && mode === 'insert') {
          const { startBlock, startInEmptyParagraph } =
            getInsertPreviewStart(editor);

          editor.getTransforms(BaseAIPlugin).ai.beginPreview({
            originalBlocks:
              startInEmptyParagraph &&
              startBlock &&
              ElementApi.isElement(startBlock)
                ? [cloneDeep(startBlock)]
                : [],
          });

          editor.setOption(AIChatPlugin, 'streaming', true);

          editor.tf.withoutSaving(() => {
            editor.tf.insertNodes(
              {
                children: [{ text: '' }],
                type: getPluginType(editor, KEYS.aiChat),
              },
              {
                at: PathApi.next(editor.selection!.focus.path.slice(0, 1)),
              }
            );
          });
        }

        if (mode === 'insert') {
          editor.tf.withoutSaving(() => {
            if (!getOption('streaming')) return;

            editor.tf.withScrolling(() => {
              streamInsertChunk(editor, chunk, {
                textProps: {
                  [getPluginType(editor, KEYS.ai)]: true,
                },
              });
            });
          });
        }

        if (toolName === 'edit' && mode === 'chat') {
          withAIBatch(
            editor,
            () => {
              applyAISuggestions(editor, text);
            },
            { split: isFirst }
          );
        }
      },
      onFinish: () => {
        editor.setOption(AIChatPlugin, 'streaming', false);
        editor.setOption(AIChatPlugin, '_blockChunks', '');
        editor.setOption(AIChatPlugin, '_blockPath', null);
        editor.setOption(AIChatPlugin, '_mdxName', null);
      },
    });
  },
});
```

- `useChatChunk`: Watches `UseChatHelpers` status and yields incremental chunks.
- `tf.ai.beginPreview`: Captures the rollback slice and selection for insert-mode preview before the first streamed chunk is written.
- `streamInsertChunk`: Streams Markdown/MDX into the document, reusing the existing block when possible.
- `applyAISuggestions`: Converts responses into transient suggestion nodes when `toolName === 'edit'`.
- `withAIBatch`: Marks saved AI batches so suggestion review and accepted AI changes stay undo-safe.

Provide your own `render` components (toolbar button, floating menu, etc.) when you extend the plugin.

### Build API Route

Handle `api.aiChat.submit` requests on the server. Each request includes the chat `messages` from `@ai-sdk/react` and a `ctx` payload that contains the editor `children`, current `selection`, and last `toolName`.
[Complete API example](https://github.com/udecode/plate-playground-template/blob/main/src/app/api/ai/command/route.ts)

```ts title="app/api/ai/command/route.ts"
import {
  convertToModelMessages,
  createGateway,
  createUIMessageStreamResponse,
  streamText,
  toUIMessageStream,
} from 'ai';
import { createSlateEditor } from 'platejs';

import { BaseEditorKit } from '@/registry/components/editor/editor-base-kit';
import { markdownJoinerTransform } from '@/registry/lib/markdown-joiner-transform';

export async function POST(req: Request) {
  const { apiKey, ctx, messages, model } = await req.json();

  const editor = createSlateEditor({
    plugins: BaseEditorKit,
    selection: ctx.selection,
    value: ctx.children,
  });

  const gateway = createGateway({
    apiKey: apiKey ?? process.env.AI_GATEWAY_API_KEY!,
  });

  const result = streamText({
    experimental_transform: markdownJoinerTransform(),
    instructions:
      ctx.toolName === 'edit'
        ? 'You are an editor that rewrites user text.'
        : undefined,
    messages: await convertToModelMessages(messages),
    model: gateway(model ?? 'openai/gpt-4o-mini'),
  });

  return createUIMessageStreamResponse({
    stream: toUIMessageStream({
      originalMessages: messages,
      stream: result.stream,
    }),
  });
}
```

- `ctx.children` and `ctx.selection` are rehydrated into a Slate editor so you can build rich prompts (see [Prompt Templates](#prompt-templates)).
- Forward provider settings (model, apiKey, temperature, gateway flags, etc.) through `chatOptions.body`; everything you add is passed verbatim in the JSON payload and can be read before calling `createGateway`.
- Always read secrets from the server. The client should only send opaque identifiers or short-lived tokens.
- Return a streaming response so `useChat` and `useChatChunk` can process tokens incrementally.

### Connect `useChat`

Bridge the editor and your model endpoint with `@ai-sdk/react`. Store helpers on the plugin so transforms can reload, stop, or show chat state.

```tsx
import { useEffect } from 'react';

import { type UIMessage, DefaultChatTransport } from 'ai';
import { type UseChatHelpers, useChat } from '@ai-sdk/react';
import { AIChatPlugin } from '@platejs/ai/react';
import { useEditorPlugin } from 'platejs/react';

type ChatMessage = UIMessage<{}, { toolName: 'comment' | 'edit' | 'generate'; comment?: unknown }>;

export const useEditorAIChat = () => {
  const { editor, setOption } = useEditorPlugin(AIChatPlugin);

  const chat = useChat<ChatMessage>({
    id: 'editor',
    api: '/api/ai/command',
    transport: new DefaultChatTransport(),
    onData(data) {
      if (data.type === 'data-toolName') {
        editor.setOption(AIChatPlugin, 'toolName', data.data);
      }
    },
  });

  useEffect(() => {
    setOption('chat', chat as UseChatHelpers<ChatMessage>);
  }, [chat, setOption]);

  return chat;
};
```

Combine the helper with `useEditorChat` to keep the floating menu anchored correctly:

```tsx
import { useEditorChat } from '@platejs/ai/react';

useEditorChat({
  onOpenChange: (open) => {
    if (!open) chat.stop?.();
  },
});
```

Now you can submit prompts programmatically:

```tsx
import { AIChatPlugin } from '@platejs/ai/react';

editor.getApi(AIChatPlugin).aiChat.submit('', {
  prompt: {
    default: 'Continue the document after {block}',
    selecting: 'Rewrite {selection} with a clearer tone',
  },
  toolName: 'generate',
});
```

</Steps>

## Prompt Templates

### Client Prompting

- `api.aiChat.submit` accepts an `EditorPrompt`. Provide a string, an object with `default`/`selecting`/`blockSelecting`, or a function that receives `{ editor, isSelecting, isBlockSelecting }`. The helper `getEditorPrompt` in the client turns that value into the final string.
- Combine it with `replacePlaceholders(editor, template, { prompt })` to expand `{editor}`, `{block}`, `{blockSelection}`, and `{prompt}` using Markdown generated by `@platejs/ai`.

```tsx
import { replacePlaceholders } from '@platejs/ai';

editor.getApi(AIChatPlugin).aiChat.submit('Improve tone', {
  prompt: ({ isSelecting }) =>
    isSelecting
      ? replacePlaceholders(editor, 'Rewrite {blockSelection} using a friendly tone.')
      : replacePlaceholders(editor, 'Continue {block} with two more sentences.'),
  toolName: 'generate',
});
```

### Server Prompting

The demo backend in `apps/www/src/app/api/ai/command` reconstructs the editor from `ctx` and builds structured prompts:

- `getChooseToolPrompt` decides whether the request is `generate`, `edit`, or `comment`.
- `getGeneratePrompt`, `getEditPrompt`, and `getCommentPrompt` transform the current editor state into instructions tailored to each mode.
- Utility helpers like `getMarkdown`, `getMarkdownWithSelection`, and `buildStructuredPrompt` (see `apps/www/src/app/api/ai/command/prompts.ts`) make it easy to embed block ids, selections, and MDX tags into the LLM request.

Augment the payload you send from the client to fine-tune server prompts:

```ts
editor.setOption(aiChatPlugin, 'chatOptions', {
  api: '/api/ai/command',
  body: {
    model: 'openai/gpt-4o-mini',
    tone: 'playful',
    temperature: 0.4,
  },
});
```

Everything under `chatOptions.body` arrives in the route handler, letting you swap providers, pass user-specific metadata, or branch into different prompt templates.

## Keyboard Shortcuts

<KeyTable>
  <KeyTableItem hotkey="Space">Open the AI menu in an empty block (cursor mode)</KeyTableItem>
  <KeyTableItem hotkey="Cmd + J">Show the AI menu (set via `shortcuts.show`)</KeyTableItem>
  <KeyTableItem hotkey="Escape">Hide the AI menu and stop streaming</KeyTableItem>
</KeyTable>

## Streaming

The streaming utilities keep complex layouts intact while responses arrive:

- `streamInsertChunk(editor, chunk, options)` deserializes Markdown chunks, updates the current block in place, and appends new blocks as needed. Use `textProps`/`elementProps` to tag streamed nodes (e.g., mark AI text).
- `streamDeserializeMd` and `streamDeserializeInlineMd` provide lower-level access if you need to control streaming for custom node types.
- `streamSerializeMd` mirrors the editor state so you can detect drift between streamed content and the response buffer.

Reset the internal `_blockChunks`, `_blockPath`, and `_mdxName` options when streaming finishes to start the next response from a clean slate.

## Streaming Example

[markdown-streaming-demo registry content](https://platejs.org/r/markdown-streaming-demo)

## Plate Plus

[ai-pro registry content](https://platejs.org/r/ai-pro)

## API Reference

### `AIPlugin`

Adds an `ai` mark to streamed text and exposes transforms to remove AI nodes or undo the last AI batch. Use `.withComponent` to render AI-marked text with a custom component.

<API name="AIPlugin">
  <APIOptions>
    <APIItem name="node.isLeaf" type="true">AI content is stored on text nodes.</APIItem>
    <APIItem name="node.isDecoration" type="false">AI marks are regular text properties, not decorations.</APIItem>
  </APIOptions>
</API>

### `AIChatPlugin`

Main plugin that powers the AI menu, chat state, and transforms.

<API name="AIChatPlugin">
  <APIOptions>
    <APIItem name="trigger" type="RegExp | string | string[]" optional>Character(s) that open the command menu. Defaults to `' '`.</APIItem>
    <APIItem name="triggerPreviousCharPattern" type="RegExp" optional>Pattern that must match the character before the trigger. Defaults to `/^\s?$/`.</APIItem>
    <APIItem name="triggerQuery" type="(editor: SlateEditor) => boolean" optional>Return `false` to cancel opening in specific contexts.</APIItem>
    <APIItem name="chat" type="UseChatHelpers&lt;ChatMessage&gt;" optional>Store helpers from `useChat` so API calls can access them.</APIItem>
    <APIItem name="chatNodes" type="TIdElement[]" optional>Snapshot of nodes used to diff edit suggestions (managed internally).</APIItem>
    <APIItem name="chatSelection" type="TRange | null" optional>Selection captured before submitting a prompt (managed internally).</APIItem>
    <APIItem name="mode" type="'chat' | 'insert'">Controls whether responses stream directly into the document or open a review panel. Defaults to `'insert'`.</APIItem>
    <APIItem name="open" type="boolean" optional>Whether the AI menu is visible. Defaults to `false`.</APIItem>
    <APIItem name="streaming" type="boolean" optional>True while a response is streaming. Defaults to `false`.</APIItem>
    <APIItem name="toolName" type="'comment' | 'edit' | 'generate' | null" optional>Active tool used to interpret the response.</APIItem>
  </APIOptions>
</API>

### `api.aiChat.submit(input, options?)`

Submits a prompt to your model provider. When `mode` is omitted it defaults to `'insert'` for a collapsed cursor and `'chat'` otherwise.

<API name="submit">
<APIParameters>
  <APIItem name="input" type="string">Raw input from the user.</APIItem>
  <APIItem name="options" type="object" optional>Fine-tune submission behaviour.</APIItem>
</APIParameters>
<APIOptions type="object">
  <APIItem name="mode" type="'chat' | 'insert'" optional>Override the response mode.</APIItem>
  <APIItem name="options" type="ChatRequestOptions" optional>Forwarded to `chat.sendMessage` (model, headers, etc.).</APIItem>
  <APIItem name="prompt" type="EditorPrompt" optional>String, config, or function processed by `getEditorPrompt`.</APIItem>
  <APIItem name="toolName" type="'comment' | 'edit' | 'generate' | null" optional>Tags the submission so hooks can react differently.</APIItem>
</APIOptions>
</API>

### `api.aiChat.reset(options?)`

Clears chat state, removes AI nodes, and optionally undoes the last AI batch.

<API name="reset">
<APIParameters>
  <APIItem name="options" type="{ undo?: boolean }" optional>Pass `undo: false` to keep streamed content.</APIItem>
</APIParameters>
</API>

### `api.aiChat.node(options?)`

Retrieves the first AI node that matches the specified criteria.

<API name="node">
<APIParameters>
  <APIItem name="options" type="EditorNodesOptions &amp; { anchor?: boolean; streaming?: boolean }" optional>Set `anchor: true` to get the anchor node or `streaming: true` to retrieve the node currently being streamed into.</APIItem>
</APIParameters>
<APIReturns type="NodeEntry | undefined">Matching node entry, if found.</APIReturns>
</API>

### `api.aiChat.reload()`

Replays the last prompt using the stored `UseChatHelpers`, restoring the original selection or block selection before resubmitting.

### `api.aiChat.stop()`

Stops streaming and calls `chat.stop`.

### `api.aiChat.show()`

Opens the AI menu, clears previous chat messages, and resets tool state.

### `api.aiChat.hide(options?)`

Closes the AI menu, optionally undoing the last AI batch and refocusing the editor.

<API name="hide">
<APIParameters>
  <APIItem name="options" type="{ focus?: boolean; undo?: boolean }" optional>Set `focus: false` to keep focus outside the editor or `undo: false` to preserve inserted content.</APIItem>
</APIParameters>
</API>

### `tf.aiChat.accept()`

Accepts the latest response. In insert mode it removes AI marks and places the caret at the end of the streamed content. In chat mode it applies the pending suggestions.

### `tf.aiChat.insertBelow(sourceEditor, options?)`

Inserts the chat preview (`sourceEditor`) below the current selection or block selection.

<API name="insertBelow">
<APIParameters>
  <APIItem name="sourceEditor" type="SlateEditor">Editor containing the generated content.</APIItem>
  <APIItem name="options" type="{ format?: 'all' | 'none' | 'single' }" optional>Copy formatting from the source selection. Defaults to `'single'`.</APIItem>
</APIParameters>
</API>

### `tf.aiChat.replaceSelection(sourceEditor, options?)`

Replaces the current selection or block selection with the chat preview.

<API name="replaceSelection">
<APIParameters>
  <APIItem name="sourceEditor" type="SlateEditor">Editor containing the generated content.</APIItem>
  <APIItem name="options" type="{ format?: 'all' | 'none' | 'single' }" optional>Controls how much formatting from the original selection should be applied.</APIItem>
</APIParameters>
</API>

### `tf.aiChat.removeAnchor(options?)`

Removes the temporary anchor node used to position the AI menu.

<API name="removeAnchor">
<APIParameters>
  <APIItem name="options" type="EditorNodesOptions" optional>Filters the nodes to remove.</APIItem>
</APIParameters>
</API>

### `tf.ai.insertNodes(nodes, options?)`

Inserts nodes tagged with the AI mark at the current selection (or `options.target`).

### `tf.ai.removeMarks(options?)`

Clears the AI mark from matching nodes.

### `tf.ai.removeNodes(options?)`

Removes text nodes that are marked as AI-generated.

### `tf.ai.beginPreview(options?)`

Captures the rollback slice and selection for insert-mode AI preview. Call it once before writing the first unsaved preview chunk.

<API name="beginPreview">
<APIParameters>
  <APIItem name="options" type="{ originalBlocks?: Value }" optional>Top-level blocks that the preview will overwrite. Use `[]` when preview inserts after existing content.</APIItem>
</APIParameters>
<APIReturns type="boolean">Returns `true` when a new preview rollback point was stored, or `false` when preview state already exists.</APIReturns>
</API>

### `tf.ai.acceptPreview()`

Commits the active preview as one fresh undoable batch, strips preview-only markers, and clears preview bookkeeping.

<API name="acceptPreview">
<APIReturns type="boolean">Returns `true` when an active preview was committed.</APIReturns>
</API>

### `tf.ai.cancelPreview()`

Restores the rollback point for the active preview and clears preview bookkeeping.

<API name="cancelPreview">
<APIReturns type="boolean">Returns `true` when an active preview was restored.</APIReturns>
</API>

### `tf.ai.discardPreview()`

Clears preview bookkeeping without restoring content. Use it when the previewed content should stay in place.

<API name="discardPreview">
<APIReturns type="boolean">Returns `true` when active preview bookkeeping was cleared.</APIReturns>
</API>

### `tf.ai.hasPreview()`

Reports whether an insert-mode preview rollback point is currently active.

<API name="hasPreview">
<APIReturns type="boolean">Returns `true` when preview rollback state exists.</APIReturns>
</API>

### `tf.ai.undo()`

Undoes the latest AI history entry when it was created by `withAIBatch`. If an insert-mode preview is active, it cancels that preview first instead of replaying every streamed chunk. In both cases it avoids re-applying AI output from redo.

### `useAIChatEditor`

Registers an auxiliary editor for chat previews and deserializes Markdown with block-level memoization.

<API name="useAIChatEditor">
<APIParameters>
  <APIItem name="editor" type="SlateEditor">Editor instance dedicated to the chat preview.</APIItem>
  <APIItem name="content" type="string">Markdown content returned by the model.</APIItem>
  <APIItem name="options" type="DeserializeMdOptions" optional>Pass `parser` to filter tokens before deserialization.</APIItem>
</APIParameters>
</API>

```tsx
import { usePlateEditor } from 'platejs/react';
import { MarkdownPlugin } from '@platejs/markdown';
import { AIChatPlugin, useAIChatEditor } from '@platejs/ai/react';

const aiPreviewEditor = usePlateEditor({
  plugins: [MarkdownPlugin, AIChatPlugin],
});

useAIChatEditor(aiPreviewEditor, responseMarkdown, {
  parser: { exclude: ['space'] },
});
```

### `useEditorChat`

Connects `UseChatHelpers` to editor state so the AI menu knows whether to anchor to cursor, selection, or block selection.

<API name="useEditorChat">
<APIParameters>
  <APIItem name="onOpenBlockSelection" type="(blocks: NodeEntry[]) => void" optional>Called when the menu opens on block selection.</APIItem>
  <APIItem name="onOpenChange" type="(open: boolean) => void" optional>Called whenever the menu opens or closes.</APIItem>
  <APIItem name="onOpenCursor" type="() => void" optional>Called when the menu opens at the cursor.</APIItem>
  <APIItem name="onOpenSelection" type="() => void" optional>Called when the menu opens on a text selection.</APIItem>
</APIParameters>
</API>

### `useChatChunk`

Streams chat responses chunk-by-chunk and gives you full control over insertion.

<API name="useChatChunk">
<APIParameters>
  <APIItem name="onChunk" type="(chunk: { chunk: string; isFirst: boolean; nodes: TText[]; text: string }) => void">Handle each streamed chunk.</APIItem>
  <APIItem name="onFinish" type="({ content }: { content: string }) => void" optional>Called when streaming finishes.</APIItem>
</APIParameters>
</API>

### `withAIBatch`

Groups editor operations into a single history batch and flags it as AI-generated so `tf.ai.undo()` removes it safely.

<API name="withAIBatch">
<APIParameters>
  <APIItem name="editor" type="SlateEditor">Target editor.</APIItem>
  <APIItem name="fn" type="() => void">Operations to run.</APIItem>
  <APIItem name="options" type="{ split?: boolean }" optional>Set `split: true` to start a new history batch.</APIItem>
</APIParameters>
</API>

### `applyAISuggestions`

Diffs AI output against stored `chatNodes` and writes transient suggestion nodes. Requires `@platejs/suggestion`.

<API name="applyAISuggestions">
<APIParameters>
  <APIItem name="editor" type="SlateEditor">Editor to apply suggestions to.</APIItem>
  <APIItem name="content" type="string">Markdown response from the model.</APIItem>
</APIParameters>
</API>

Complementary helpers allow you to finalize or discard the diff:

- `acceptAISuggestions(editor)`: Converts transient suggestion nodes into permanent suggestions.
- `rejectAISuggestions(editor)`: Removes transient suggestion nodes and clears suggestion marks.

### `aiCommentToRange`

Maps streamed comment metadata back to document ranges so comments can be inserted automatically.

<API name="aiCommentToRange">
<APIParameters>
  <APIItem name="editor" type="PlateEditor">Editor instance.</APIItem>
  <APIItem name="options" type="{ blockId: string; comment: string; content: string }">Block id and text used to locate the range.</APIItem>
</APIParameters>
<APIReturns type="{ start: BasePoint; end: BasePoint } | null">Range matching the comment or `null` if it cannot be found.</APIReturns>
</API>

### `findTextRangeInBlock`

Fuzzy-search helper that uses LCS to find the closest match inside a block.

<API name="findTextRangeInBlock">
<APIParameters>
  <APIItem name="node" type="TNode">Block node to search.</APIItem>
  <APIItem name="searchText" type="string">Text snippet to locate.</APIItem>
</APIParameters>
<APIReturns type="{ start: { path: Path; offset: number }; end: { path: Path; offset: number } } | null">Matched range or `null`.</APIReturns>
</API>

### `getEditorPrompt`

Generates prompts that respect cursor, selection, or block selection states.

<API name="getEditorPrompt">
<APIParameters>
  <APIItem name="editor" type="SlateEditor">Editor providing context.</APIItem>
  <APIItem name="options" type="{ prompt?: EditorPrompt }">String, config, or function describing the prompt.</APIItem>
</APIParameters>
<APIReturns type="string">Contextualized prompt string.</APIReturns>
</API>

### `replacePlaceholders`

Replaces placeholders like `{editor}`, `{blockSelection}`, and `{prompt}` with serialized Markdown.

<API name="replacePlaceholders">
<APIParameters>
  <APIItem name="editor" type="SlateEditor">Editor providing content.</APIItem>
  <APIItem name="text" type="string">Template text.</APIItem>
  <APIItem name="options" type="{ prompt?: string }" optional>Prompt value injected into `{prompt}`.</APIItem>
</APIParameters>
<APIReturns type="string">Template with placeholders replaced by Markdown.</APIReturns>
</API>

## Customization

### Adding Custom AI Commands

[ai-menu registry content](https://platejs.org/r/ai-menu)

Extend the `aiChatItems` map to add new commands. Each command receives `{ aiEditor, editor, input }` and can dispatch `api.aiChat.submit` with custom prompts or transforms.

#### Simple Custom Command

```tsx
summarizeInBullets: {
  icon: <ListIcon />,
  label: 'Summarize in bullets',
  value: 'summarizeInBullets',
  onSelect: ({ editor }) => {
    void editor.getApi(AIChatPlugin).aiChat.submit('', {
      prompt: 'Summarize the current selection using bullet points',
      toolName: 'generate',
    });
  },
},
```

#### Command with Complex Logic

```tsx
generateTOC: {
  icon: <BookIcon />,
  label: 'Generate table of contents',
  value: 'generateTOC',
  onSelect: ({ editor }) => {
    const headings = editor.api.nodes({
      match: (n) => ['h1', 'h2', 'h3'].includes(n.type as string),
    });

    const prompt =
      headings.length === 0
        ? 'Create a realistic table of contents for this document'
        : 'Generate a table of contents that reflects the existing headings';

    void editor.getApi(AIChatPlugin).aiChat.submit('', {
      mode: 'insert',
      prompt,
      toolName: 'generate',
    });
  },
},
```

The menu automatically switches between command and suggestion states:

- `cursorCommand`: Cursor is collapsed and no response yet.
- `selectionCommand`: Text is selected and no response yet.
- `cursorSuggestion` / `selectionSuggestion`: A response exists, so actions like Accept, Try Again, or Insert Below are shown.

Use `toolName` (`'generate' | 'edit' | 'comment'`) to control how streaming hooks process the response. For example, `'edit'` enables diff-based suggestions, and `'comment'` allows you to convert streamed comments into discussion threads with `aiCommentToRange`.


# Copilot

Source: https://platejs.org/docs/copilot

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Copilot
description: AI-powered text completion suggestions.
docs:
  - route: https://pro.platejs.org/docs/examples/copilot
    title: Plus
  - route: /docs/components/ghost-text
    title: Ghost Text
---

[copilot-demo registry content](https://platejs.org/r/copilot-demo)

<PackageInfo>

## Features

- Renders ghost text suggestions as you type
- Two trigger modes:
  - Shortcut (e.g. `Ctrl+Space`). Press again for alternative suggestions.
  - Debounce mode: automatically triggers after a space at paragraph ends
- Accept suggestions with Tab or word-by-word with `Cmd+→`
- Built-in support for Vercel AI SDK completion API

</PackageInfo>

## Kit Usage

<Steps>

### Installation

The fastest way to add Copilot functionality is with the `CopilotKit`, which includes pre-configured `CopilotPlugin` along with `MarkdownKit` and their [Plate UI](/docs/installation/plate-ui) components.

[copilot-kit registry content](https://platejs.org/r/copilot-kit)

- [`GhostText`](/docs/components/ghost-text): Renders the ghost text suggestions.

### Add Kit

```tsx
import { createPlateEditor } from 'platejs/react';
import { CopilotKit } from '@/components/editor/plugins/copilot-kit';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    ...CopilotKit,
    // Place tab-using plugins after CopilotKit to avoid conflicts
    // IndentPlugin,
    // TabbablePlugin,
  ],
});
```

**Tab Key Handling**: The Copilot plugin uses the Tab key to accept suggestions. To avoid conflicts with other plugins that use Tab (like `IndentPlugin` or `TabbablePlugin`), ensure `CopilotKit` is placed before them in your plugin configuration.

### Add API Route

Copilot requires a server-side API endpoint to communicate with the AI model. Add the pre-configured Copilot API route:

[copilot-api registry content](https://platejs.org/r/copilot-api)

### Configure Environment

Ensure your AI Gateway key is set in your environment variables:

```bash title=".env.local"
AI_GATEWAY_API_KEY="your-api-key"
```

</Steps>

## Manual Usage

<Steps>

### Installation

```bash
npm install @platejs/ai @platejs/markdown
```

### Add Plugins

```tsx
import { CopilotPlugin } from '@platejs/ai/react';
import { MarkdownPlugin } from '@platejs/markdown';
import { createPlateEditor } from 'platejs/react';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    MarkdownPlugin,
    CopilotPlugin,
    // Place tab-using plugins after CopilotPlugin to avoid conflicts
    // IndentPlugin,
    // TabbablePlugin,
  ],
});
```

- `MarkdownPlugin`: Required for serializing editor content to send as a prompt.
- `CopilotPlugin`: Enables AI-powered text completion.

**Tab Key Handling**: The Copilot plugin uses the Tab key to accept suggestions. To avoid conflicts with other plugins that use Tab (like `IndentPlugin` or `TabbablePlugin`), ensure `CopilotPlugin` is placed before them in your plugin configuration.

### Configure Plugins

```tsx
import { CopilotPlugin } from '@platejs/ai/react';
import { serializeMd, stripMarkdown } from '@platejs/markdown';
import { GhostText } from '@/components/ui/ghost-text';

const plugins = [
  // ...otherPlugins,
  MarkdownPlugin.configure({
    options: {
      remarkPlugins: [remarkMath, remarkGfm, remarkMdx],
    },
  }),
  CopilotPlugin.configure(({ api }) => ({
    options: {
      completeOptions: {
        api: '/api/ai/copilot',
        onError: () => {
          // Mock the API response. Remove when you implement the route /api/ai/copilot
          api.copilot.setBlockSuggestion({
            text: stripMarkdown('This is a mock suggestion.'),
          });
        },
        onFinish: (_, completion) => {
          if (completion === '0') return;

          api.copilot.setBlockSuggestion({
            text: stripMarkdown(completion),
          });
        },
      },
      debounceDelay: 500,
      renderGhostText: GhostText,
    },
    shortcuts: {
      accept: { keys: 'tab' },
      acceptNextWord: { keys: 'mod+right' },
      reject: { keys: 'escape' },
      triggerSuggestion: { keys: 'ctrl+space' },
    },
  })),
];
```

- `completeOptions`: Configures the Vercel AI SDK `useCompletion` hook.
  - `api`: The endpoint for your AI completion route.
  - `onError`: A callback for handling errors (used for mocking during development).
  - `onFinish`: A callback to handle the completed suggestion. Here, it sets the suggestion in the editor.
- `debounceDelay`: The delay in milliseconds for auto-triggering suggestions after the user stops typing.
- `renderGhostText`: The React component used to display the suggestion inline.
- `shortcuts`: Defines keyboard shortcuts for interacting with Copilot suggestions.

### Add API Route

Create an API route handler at `app/api/ai/copilot/route.ts` to process AI requests. This endpoint will receive the prompt from the editor and call the AI model.

```tsx title="app/api/ai/copilot/route.ts"
import type { NextRequest } from 'next/server';

import { createGateway, generateText } from 'ai';
import { NextResponse } from 'next/server';

export async function POST(req: NextRequest) {
  const {
    apiKey: key,
    instructions,
    model = 'gpt-4o-mini',
    prompt,
  } = await req.json();

  const apiKey = key || process.env.AI_GATEWAY_API_KEY;

  if (!apiKey) {
    return NextResponse.json(
      { error: 'Missing AI Gateway API key.' },
      { status: 401 }
    );
  }

  const gateway = createGateway({ apiKey });

  try {
    const result = await generateText({
      abortSignal: req.signal,
      instructions,
      maxOutputTokens: 50,
      model: gateway(`openai/${model}`),
      prompt,
      temperature: 0.7,
    });

    return NextResponse.json(result);
  } catch (error) {
    if (error instanceof Error && error.name === 'AbortError') {
      return NextResponse.json(null, { status: 408 });
    }

    return NextResponse.json(
      { error: 'Failed to process AI request' },
      { status: 500 }
    );
  }
}
```

Then, set your `AI_GATEWAY_API_KEY` in `.env.local`.

### Instructions

Instructions define the AI's role and behavior. Modify the `body.instructions` property in `completeOptions`:

```tsx
CopilotPlugin.configure(({ api }) => ({
  options: {
    completeOptions: {
      api: '/api/ai/copilot',
      body: {
        instructions: `You are an advanced AI writing assistant, similar to VSCode Copilot but for general text. Your task is to predict and generate the next part of the text based on the given context.

Rules:
- Continue the text naturally up to the next punctuation mark (., ,, ;, :, ?, or !).
- Maintain style and tone. Don't repeat given text.
- For unclear context, provide the most likely continuation.
- Handle code snippets, lists, or structured text if needed.
- Don't include """ in your response.
- CRITICAL: Always end with a punctuation mark.
- CRITICAL: Avoid starting a new block. Do not use block formatting like >, #, 1., 2., -, etc. The suggestion should continue in the same block as the context.
- If no context is provided or you can't generate a continuation, return "0" without explanation.`,
      },
      // ... other options
    },
    // ... other plugin options
  },
})),
```

### User Prompt

The user prompt (via `getPrompt`) determines what context is sent to the AI. You can customize it to include more context or format it differently:

```tsx
CopilotPlugin.configure(({ api }) => ({
  options: {
    getPrompt: ({ editor }) => {
        const contextEntry = editor.api.block({ highest: true });

        if (!contextEntry) return '';

        const prompt = serializeMd(editor, {
          value: [contextEntry[0] as TElement],
        });

        return `Continue the text up to the next punctuation mark:
"""
${prompt}
"""`;
      },
    // ... other options
  },
})),
```

</Steps>



## Plate Plus

[copilot-pro registry content](https://platejs.org/r/copilot-pro)

## Customization

### Switching AI Models

Configure different AI models and providers in your API route:

```tsx title="app/api/ai/copilot/route.ts"
import { createGateway, generateText } from 'ai';

export async function POST(req: NextRequest) {
  const {
    instructions,
    model = 'openai/gpt-4o-mini',
    prompt,
  } = await req.json();

  const gateway = createGateway({ apiKey: process.env.AI_GATEWAY_API_KEY });

  const result = await generateText({
    instructions,
    maxOutputTokens: 50,
    model: gateway(model),
    prompt,
    temperature: 0.7,
  });

  return NextResponse.json(result);
}
```

Configure the model in your `CopilotPlugin`:

```tsx
CopilotPlugin.configure(({ api }) => ({
  options: {
    completeOptions: {
      api: '/api/ai/copilot',
      body: {
        instructions: 'Continue the current paragraph in the same tone.',
        model: 'anthropic/claude-3-haiku-20240307',
      },
    },
    // ... other options
  },
})),
```

For more AI providers and models, see the [Vercel AI SDK documentation](https://sdk.vercel.ai/providers/ai-sdk-providers).

### Custom Trigger Conditions

Control when suggestions are automatically triggered:

```tsx
CopilotPlugin.configure(({ api }) => ({
  options: {
    triggerQuery: ({ editor }) => {
      // Only trigger in paragraph blocks
      const block = editor.api.block();
      if (!block || block[0].type !== 'p') return false;
      
      // Standard checks
      return editor.selection && 
             !editor.api.isExpanded() && 
             editor.api.isAtEnd();
    },
    autoTriggerQuery: ({ editor }) => {
      // Custom conditions for auto-triggering
      const block = editor.api.block();
      if (!block) return false;
      
      const text = editor.api.string(block[0]);
      
      // Trigger after question words
      return /\b(what|how|why|when|where)\s*$/i.test(text);
    },
    // ... other options
  },
})),
```

### Security Considerations

Implement security best practices for Copilot API:

```tsx title="app/api/ai/copilot/route.ts"
export async function POST(req: NextRequest) {
  const { instructions, prompt } = await req.json();

  // Validate prompt length
  if (!prompt || prompt.length > 1000) {
    return NextResponse.json({ error: 'Invalid prompt' }, { status: 400 });
  }

  // Rate limiting (implement with your preferred solution)
  // await rateLimit(req);

  // Content filtering for sensitive content
  if (containsSensitiveContent(prompt)) {
    return NextResponse.json({ error: 'Content filtered' }, { status: 400 });
  }

  // Process AI request...
}
```

**Security Guidelines:**
- **Input Validation**: Limit prompt length and validate content
- **Rate Limiting**: Prevent abuse with request limits
- **Content Filtering**: Filter sensitive or inappropriate content
- **API Key Security**: Never expose API keys client-side
- **Timeout Handling**: Handle request timeouts gracefully

## Plugins

### `CopilotPlugin`

Plugin for AI-powered text completion suggestions.

<API name="CopilotPlugin">
<APIOptions>
  <APIItem name="autoTriggerQuery" type="(options: { editor: PlateEditor }) => boolean" optional>
    Additional conditions to auto trigger copilot.
    - **Default:** Checks:
      - Block above is not empty
      - Block above ends with a space
      - No existing suggestion
  </APIItem>
  <APIItem name="completeOptions" type="Partial<CompleteOptions>">
    AI completion configuration options. See [AI SDK useCompletion Parameters](https://sdk.vercel.ai/docs/reference/ai-sdk-ui/use-completion#parameters).
  </APIItem>
  <APIItem name="debounceDelay" type="number" optional>
    Delay for debouncing auto-triggered suggestions.
    - **Default:** `0`
  </APIItem>
  <APIItem name="getNextWord" type="(options: { text: string }) => { firstWord: string; remainingText: string }" optional>
    Function to extract the next word from suggestion text.
  </APIItem>
  <APIItem name="getPrompt" type="(options: { editor: PlateEditor }) => string" optional>
    Function to generate the prompt for AI completion.
    - **Default:** Uses markdown serialization of ancestor node
  </APIItem>
  <APIItem name="renderGhostText" type="(() => React.ReactNode) | null" optional>
    Component to render ghost text suggestions.
  </APIItem>
  <APIItem name="triggerQuery" type="(options: { editor: PlateEditor }) => boolean" optional>
    Conditions to trigger copilot.
    - **Default:** Checks:
      - Selection is not expanded
      - Selection is at block end
  </APIItem>
</APIOptions>
</API>

## Transforms

### `tf.copilot.accept()`

Accepts the current suggestion and applies it to the editor content.

Default Shortcut: `Tab`

### `tf.copilot.acceptNextWord()`

Accepts only the next word of the current suggestion, allowing for granular acceptance of suggestions.

Example Shortcut: `Cmd + →`

## API

### `api.copilot.reject()`

Resets the plugin state to its initial condition:
Default Shortcut: `Escape`

### `api.copilot.triggerSuggestion()`

Triggers a new suggestion request. The request may be debounced based on the plugin configuration.

Example Shortcut: `Ctrl + Space`

### `api.copilot.setBlockSuggestion()`

Sets suggestion text for a block.

<API name="setBlockSuggestion">
<APIParameters>
  <APIItem name="options" type="SetBlockSuggestionOptions">
    Options for setting the block suggestion.
  </APIItem>
</APIParameters>

<APIOptions type="SetBlockSuggestionOptions">
  <APIItem name="text" type="string">
    The suggestion text to set.
  </APIItem>
  <APIItem name="id" type="string" optional>
    Target block ID.
    - **Default:** Current block
  </APIItem>
</APIOptions>
</API>

### `api.copilot.stop()`

Stops ongoing suggestion requests and cleans up:

- Cancels debounced trigger calls
- Aborts current API request
- Resets abort controller


# Comment

Source: https://platejs.org/docs/comment

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Comment
docs:
  - route: https://pro.platejs.org/docs/examples/discussion
    title: Plus
  - route: /docs/components/comment-node
    title: Comment Leaf
  - route: /docs/components/comment-toolbar-button
    title: Comment Toolbar Button
  - route: /docs/components/block-discussion
    title: Block Discussion
---

[discussion-demo registry content](https://platejs.org/r/discussion-demo)

<PackageInfo>

## Features

- **Text Comments:** Add comments as text marks with inline annotations
- **Overlapping Comments:** Support multiple comments on the same text
- **Draft Comments:** Create draft comments before finalizing
- **State Tracking:** Track comment state and user interactions
- **Discussion Integration:** Works with discussion plugin for complete collaboration

</PackageInfo>

## Kit Usage

<Steps>

### Installation

The fastest way to add comment functionality is with the `CommentKit`, which includes pre-configured `commentPlugin` and related components along with their [Plate UI](/docs/installation/plate-ui) components.

[comment-kit registry content](https://platejs.org/r/comment-kit)

- [`CommentLeaf`](/docs/components/comment-node): Renders comment text marks
- [`BlockDiscussion`](/docs/components/block-discussion): Renders discussion UI with comments integration

### Add Kit

```tsx
import { createPlateEditor } from 'platejs/react';
import { CommentKit } from '@/components/editor/plugins/comment-kit';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    ...CommentKit,
  ],
});
```

</Steps>

## Manual Usage

<Steps>

### Installation

```bash
npm install @platejs/comment
```

### Extend Comment Plugin

Create the comment plugin with extended configuration for state management:

```tsx
import { type ExtendConfig, type Path, isSlateString } from 'platejs';
import {
  type BaseCommentConfig,
  BaseCommentPlugin,
  getDraftCommentKey,
} from '@platejs/comment';
import { toTPlatePlugin } from 'platejs/react';
import { CommentLeaf } from '@/components/ui/comment-node';

type CommentConfig = ExtendConfig<
  BaseCommentConfig,
  {
    activeId: string | null;
    commentingBlock: Path | null;
    hoverId: string | null;
  }
>;

export const commentPlugin = toTPlatePlugin<CommentConfig>(
  BaseCommentPlugin,
  ({ editor }) => ({
    options: {
      activeId: null,
      commentingBlock: null,
      hoverId: null,
    },
    render: {
      node: CommentLeaf,
    },
  })
);
```

- `options.activeId`: Currently active comment ID for visual highlighting
- `options.commentingBlock`: Path of the block currently being commented
- `options.hoverId`: Currently hovered comment ID for hover effects
- `render.node`: Assigns [`CommentLeaf`](/docs/components/comment-node) to render comment text marks

### Add Click Handler

Add click handling to manage active comment state:

```tsx
export const commentPlugin = toTPlatePlugin<CommentConfig>(
  BaseCommentPlugin,
  ({ editor }) => ({
    handlers: {
      // Set active comment when clicking on comment marks
      onClick: ({ api, event, setOption, type }) => {
        let leaf = event.target as HTMLElement;
        let isSet = false;

        const unsetActiveComment = () => {
          setOption('activeId', null);
          isSet = true;
        };

        if (!isSlateString(leaf)) unsetActiveComment();

        while (leaf.parentElement) {
          if (leaf.classList.contains(`slate-${type}`)) {
            const commentsEntry = api.comment.node();

            if (!commentsEntry) {
              unsetActiveComment();
              break;
            }

            const id = api.comment.nodeId(commentsEntry[0]);
            setOption('activeId', id ?? null);
            isSet = true;
            break;
          }

          leaf = leaf.parentElement;
        }

        if (!isSet) unsetActiveComment();
      },
    },
    // ... previous options and render
  })
);
```

The click handler tracks which comment is currently active:

- **Detects comment clicks**: Traverses DOM to find comment elements
- **Sets active state**: Updates `activeId` when clicking on comments
- **Clears state**: Unsets `activeId` when clicking outside comments
- **Visual feedback**: Enables hover/active styling in comment components

### Extend Transforms

Extend the `setDraft` transform for enhanced functionality:

```tsx
export const commentPlugin = toTPlatePlugin<CommentConfig>(
  BaseCommentPlugin,
  ({ editor }) => ({
    // ... previous configuration
  })
)
  .extendTransforms(
    ({
      editor,
      setOption,
      tf: {
        comment: { setDraft },
      },
    }) => ({
      setDraft: () => {
        if (editor.api.isCollapsed()) {
          editor.tf.select(editor.api.block()![1]);
        }

        setDraft();

        editor.tf.collapse();
        setOption('activeId', getDraftCommentKey());
        setOption('commentingBlock', editor.selection!.focus.path.slice(0, 1));
      },
    })
  )
  .configure({
    node: { component: CommentLeaf },
    shortcuts: {
      setDraft: { keys: 'mod+shift+m' },
    },
  });
```

### Add Toolbar Button

You can add [`CommentToolbarButton`](/docs/components/comment-toolbar-button) to your [Toolbar](/docs/toolbar) to add comments on selected text.

### Add Plugins

```tsx
import { createPlateEditor } from 'platejs/react';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    commentPlugin,
  ],
});
```

### Discussion Integration

The comment plugin works with the [discussion plugin](/docs/discussion) for complete collaboration:

```tsx
import { discussionPlugin } from '@/components/editor/plugins/discussion-kit';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    discussionPlugin,
    commentPlugin,
  ],
});
```

</Steps>

## Keyboard Shortcuts

<KeyTable>
  <KeyTableItem hotkey="Cmd + Shift + M">
    Add a comment on the selected text.
  </KeyTableItem>
</KeyTable>

## Plate Plus

[discussion-pro registry content](https://platejs.org/r/discussion-pro)

## Plugins

### `CommentPlugin`

Plugin for creating and managing text comments with state tracking and discussion integration.

<API name="CommentPlugin">
  <APIOptions>
    <APIItem name="activeId" type="string | null">
      Currently active comment ID for visual highlighting. Used internally to
      track state.
    </APIItem>
    <APIItem name="commentingBlock" type="Path | null">
      Path of the block currently being commented on.
    </APIItem>
    <APIItem name="hoverId" type="string | null">
      Currently hovered comment ID for hover effects.
    </APIItem>
  </APIOptions>
</API>

## API

### `api.comment.has`

Checks if a comment with the given ID exists in the editor.

<API name="has">
  <APIParameters>
    <APIItem name="options" type="{ id: string }">
      Options containing the comment ID to check.
    </APIItem>
  </APIParameters>
  <APIReturns type="boolean">Whether the comment exists.</APIReturns>
</API>

### `api.comment.node`

Gets a comment node entry.

<API name="node">
  <APIOptions
    type="EditorNodesOptions & { id?: string; isDraft?: boolean }"
    optional
  >
    Options for finding the node.
  </APIOptions>
  <APIReturns type="NodeEntry<TCommentText> | undefined">
    The comment node entry if found.
  </APIReturns>
</API>

### `api.comment.nodeId`

Gets the ID of a comment from a leaf node.

<API name="nodeId">
  <APIParameters>
    <APIItem name="leaf" type="TCommentText">
      The comment leaf node.
    </APIItem>
  </APIParameters>
  <APIReturns type="string | undefined">The comment ID if found.</APIReturns>
</API>

### `api.comment.nodes`

Gets all comment node entries matching the options.

<API name="nodes">
  <APIOptions
    type="EditorNodesOptions & { id?: string; isDraft?: boolean }"
    optional
  >
    Options for finding the nodes.
  </APIOptions>
  <APIReturns type="NodeEntry<TCommentText>[]">
    Array of comment node entries.
  </APIReturns>
</API>

## Transforms

### `tf.comment.removeMark`

Removes the comment mark from the current selection or a specified location.

<API name="removeMark" />

### `tf.comment.setDraft`

Sets a draft comment mark at the current selection.

<API name="setDraft">
  <APIOptions type="SetNodesOptions" optional>
    Options for setting the draft comment.
  </APIOptions>
</API>

### `tf.comment.unsetMark`

Unsets comment nodes with the specified ID from the editor.

<API name="unsetMark">
<APIParameters>
  <APIItem name="options" type="{ id: string; transient?: boolean }">
    Options for unsetting comment marks.
  </APIItem>
</APIParameters>

<APIOptions type="object">
  <APIItem name="id" type="string">
    The comment ID to unset.
  </APIItem>
  <APIItem name="transient" type="boolean" optional>
    When true, removes all AI comments at once.
    - **Default:** `false`
  </APIItem>
</APIOptions>
</API>

## Utilities

### `getCommentCount`

Gets the count of non-draft comments in a comment node.

<API name="getCommentCount">
  <APIParameters>
    <APIItem name="node" type="TCommentText">
      The comment node.
    </APIItem>
  </APIParameters>
  <APIReturns type="number">The count of comments.</APIReturns>
</API>

### `getCommentKey`

Generates a comment key based on the provided ID.

<API name="getCommentKey">
  <APIParameters>
    <APIItem name="id" type="string">
      The ID of the comment.
    </APIItem>
  </APIParameters>
  <APIReturns type="string">The generated comment key.</APIReturns>
</API>

### `getCommentKeyId`

Extracts the comment ID from a comment key.

<API name="getCommentKeyId">
  <APIParameters>
    <APIItem name="key" type="string">
      The comment key.
    </APIItem>
  </APIParameters>
  <APIReturns type="string">The extracted comment ID.</APIReturns>
</API>

### `getCommentKeys`

Returns an array of comment keys present in the given node.

<API name="getCommentKeys">
  <APIParameters>
    <APIItem name="node" type="TCommentText">
      The node to check for comment keys.
    </APIItem>
  </APIParameters>
  <APIReturns type="string[]">Array of comment keys.</APIReturns>
</API>

### `getDraftCommentKey`

Gets the key used for draft comments.

<API name="getDraftCommentKey">
  <APIReturns type="string">The draft comment key.</APIReturns>
</API>

### `isCommentKey`

Checks if a given key is a comment key.

<API name="isCommentKey">
  <APIParameters>
    <APIItem name="key" type="string">
      The key to check.
    </APIItem>
  </APIParameters>
  <APIReturns type="boolean">Whether the key is a comment key.</APIReturns>
</API>

### `isCommentNodeById`

Checks if a given node is a comment with the specified ID.

<API name="isCommentNodeById">
  <APIParameters>
    <APIItem name="node" type="TNode">
      The node to check.
    </APIItem>
    <APIItem name="id" type="string">
      The ID of the comment.
    </APIItem>
  </APIParameters>
  <APIReturns type="boolean">
    Whether the node is a comment with the specified ID.
  </APIReturns>
</API>

## Types

### `TCommentText`

Text nodes that can contain comments.

<API name="TCommentText">
  <APIAttributes>
    <APIItem name="comment" type="boolean" optional>
      Whether this text node contains comments.
    </APIItem>
    <APIItem name="comment_<id>" type="boolean" optional>
      Comment data keyed by comment ID. Multiple comments can exist in one text
      node.
    </APIItem>
  </APIAttributes>
</API>


# Discussion

Source: https://platejs.org/docs/discussion

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Discussion
docs:
  - route: https://pro.platejs.org/docs/examples/discussion
    title: Plus
  - route: /docs/components/block-discussion
    title: Block Discussion
---

[discussion-demo registry content](https://platejs.org/r/discussion-demo)

<PackageInfo>

## Features

- **User Management**: Store and manage user data with avatars and names
- **Discussion Threads**: Manage discussion data structures with comments
- **Current User Tracking**: Track the current active user for collaboration
- **Data Storage**: Pure UI plugin for storing collaboration state
- **Selector API**: Easy access to user data through plugin selectors

</PackageInfo>

## Kit Usage

<Steps>

### Installation

The fastest way to add discussion functionality is with the `DiscussionKit`, which includes the pre-configured `discussionPlugin` along with its [Plate UI](/docs/installation/plate-ui) components.

[discussion-kit registry content](https://platejs.org/r/discussion-kit)

- [`BlockDiscussion`](/docs/components/block-discussion): Renders discussion UI above nodes

### Add Kit

```tsx
import { createPlateEditor } from 'platejs/react';
import { DiscussionKit } from '@/components/editor/plugins/discussion-kit';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    ...DiscussionKit,
  ],
});
```

</Steps>

## Manual Usage

<Steps>

### Installation

```bash
npm install @platejs/comment @platejs/suggestion
```

### Create Plugin

```tsx
import { createPlatePlugin } from 'platejs/react';
import { BlockDiscussion } from '@/components/ui/block-discussion';

export interface TDiscussion {
  id: string;
  comments: TComment[];
  createdAt: Date;
  isResolved: boolean;
  userId: string;
  documentContent?: string;
}

const usersData = {
  alice: {
    id: 'alice',
    avatarUrl: 'https://api.dicebear.com/9.x/glass/svg?seed=alice6',
    name: 'Alice',
  },
  bob: {
    id: 'bob', 
    avatarUrl: 'https://api.dicebear.com/9.x/glass/svg?seed=bob4',
    name: 'Bob',
  },
};

export const discussionPlugin = createPlatePlugin({
  key: 'discussion',
  options: {
    currentUserId: 'alice',
    discussions: [],
    users: usersData,
  },
})
  .configure({
    render: { aboveNodes: BlockDiscussion },
  })
  .extendSelectors(({ getOption }) => ({
    currentUser: () => getOption('users')[getOption('currentUserId')],
    user: (id: string) => getOption('users')[id],
  }));
```

- `options.currentUserId`: ID of the current active user
- `options.discussions`: Array of discussion data structures  
- `options.users`: Object mapping user IDs to user data
- `render.aboveNodes`: Renders [`BlockDiscussion`](/docs/components/block-discussion) above nodes for discussion UI
- `selectors.currentUser`: Gets the current user data
- `selectors.user`: Gets user data by ID

### Add Plugin

```tsx
import { createPlateEditor } from 'platejs/react';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    discussionPlugin,
  ],
});
```

</Steps>

## Plate Plus

[discussion-pro registry content](https://platejs.org/r/discussion-pro)

## Plugins

### `discussionPlugin`

Pure UI plugin for managing collaboration state including users and discussion data.

<API name="discussionPlugin">
<APIOptions>
  <APIItem name="currentUserId" type="string">
    ID of the current active user in the collaboration session.
  </APIItem>
  <APIItem name="discussions" type="TDiscussion[]">
    Array of discussion objects containing comments and metadata.
  </APIItem>
  <APIItem name="users" type="Record<string, UserData>">
    Object mapping user IDs to user information including name and avatar.
  </APIItem>
</APIOptions>
</API>

## Selectors

### `currentUser`

Gets the current user data.

<API name="currentUser">
<APIReturns type="UserData">
  The current user's data including id, name, and avatarUrl.
</APIReturns>
</API>

### `user`

Gets user data by ID.

<API name="user">
<APIParameters>
  <APIItem name="id" type="string">
    The user ID to look up.
  </APIItem>
</APIParameters>
<APIReturns type="UserData | undefined">
  The user data if found, undefined otherwise.
</APIReturns>
</API>

## Types

### `TDiscussion`

Discussion data structure containing comments and metadata.

<API name="TDiscussion">
<APIAttributes>
  <APIItem name="id" type="string">
    Unique identifier for the discussion.
  </APIItem>
  <APIItem name="comments" type="TComment[]">
    Array of comments in the discussion thread.
  </APIItem>
  <APIItem name="createdAt" type="Date">
    When the discussion was created.
  </APIItem>
  <APIItem name="isResolved" type="boolean">
    Whether the discussion has been resolved.
  </APIItem>
  <APIItem name="userId" type="string">
    ID of the user who created the discussion.
  </APIItem>
  <APIItem name="documentContent" type="string" optional>
    Content from the document related to this discussion.
  </APIItem>
</APIAttributes>
</API>

### `UserData`

User information structure for collaboration.

<API name="UserData">
<APIAttributes>
  <APIItem name="id" type="string">
    Unique identifier for the user.
  </APIItem>
  <APIItem name="name" type="string">
    Display name of the user.
  </APIItem>
  <APIItem name="avatarUrl" type="string">
    URL for the user's avatar image.
  </APIItem>
  <APIItem name="hue" type="number" optional>
    Optional color hue for user identification.
  </APIItem>
</APIAttributes>
</API> 

# Suggestion

Source: https://platejs.org/docs/suggestion

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Suggestion
docs:
  - route: https://pro.platejs.org/docs/examples/discussion
    title: Plus
  - route: /docs/components/suggestion-node
    title: Suggestion Leaf
  - route: /docs/components/suggestion-toolbar-button
    title: Suggestion Toolbar Button
  - route: /docs/components/block-suggestion
    title: Block suggestion
  - route: /docs/components/block-discussion
    title: Block discussion
---

[discussion-demo registry content](https://platejs.org/r/discussion-demo)

<PackageInfo>

## Features

- **Text Suggestions:** Add suggestions as text marks with inline annotations
- **Block Suggestions:** Create suggestions for entire blocks of content
- **State Tracking:** Track suggestion state and user interactions
- **Undo/Redo Support:** Full undo/redo support for suggestion changes
- **Discussion Integration:** Works with discussion plugin for complete collaboration

</PackageInfo>

## Kit Usage

<Steps>

### Installation

The fastest way to add suggestion functionality is with the `SuggestionKit`, which includes pre-configured `SuggestionPlugin` and related components along with their [Plate UI](/docs/installation/plate-ui) components.

[suggestion-kit registry content](https://platejs.org/r/suggestion-kit)

- [`SuggestionLeaf`](/docs/components/suggestion-node): Renders suggestion text marks
- [`BlockSuggestion`](/docs/components/block-suggestion): Renders block-level suggestions
- [`SuggestionLineBreak`](/docs/components/suggestion-node): Handles line breaks in suggestions

### Add Kit

```tsx
import { createPlateEditor } from 'platejs/react';
import { SuggestionKit } from '@/components/editor/plugins/suggestion-kit';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    ...SuggestionKit,
  ],
});
```

</Steps>

## Manual Usage

<Steps>

### Installation

```bash
npm install @platejs/suggestion
```

### Extend Suggestion Plugin

Create the suggestion plugin with extended configuration for state management:

```tsx
import {
  type ExtendConfig,
  isSlateEditor,
  isSlateElement,
  isSlateString,
} from 'platejs';
import {
  type BaseSuggestionConfig,
  BaseSuggestionPlugin,
} from '@platejs/suggestion';
import { createPlatePlugin, toTPlatePlugin } from 'platejs/react';
import { BlockSuggestion } from '@/components/ui/block-suggestion';
import { SuggestionLeaf } from '@/components/ui/suggestion-node';

export type SuggestionConfig = ExtendConfig<
  BaseSuggestionConfig,
  {
    activeId: string | null;
    hoverId: string | null;
  }
>;

export const suggestionPlugin = toTPlatePlugin<SuggestionConfig>(
  BaseSuggestionPlugin,
  ({ editor }) => ({
    options: {
      activeId: null,
      currentUserId: 'alice', // Set your current user ID
      hoverId: null,
    },
    render: {
      node: SuggestionLeaf,
      belowRootNodes: ({ api, element }) => {
        if (!api.suggestion!.isBlockSuggestion(element)) {
          return null;
        }

        return <BlockSuggestion element={element} />;
      },
    },
  })
);
```

- `options.activeId`: Currently active suggestion ID for visual highlighting
- `options.currentUserId`: ID of the current user creating suggestions  
- `options.hoverId`: Currently hovered suggestion ID for hover effects
- `render.node`: Assigns [`SuggestionLeaf`](/docs/components/suggestion-node) to render suggestion text marks
- `render.belowRootNodes`: Renders [`BlockSuggestion`](/docs/components/block-suggestion) for block-level suggestions

### Add Click Handler

Add click handling to manage active suggestion state:

```tsx
export const suggestionPlugin = toTPlatePlugin<SuggestionConfig>(
  BaseSuggestionPlugin,
  ({ editor }) => ({
    handlers: {
      // Unset active suggestion when clicking outside of suggestion
      onClick: ({ api, event, setOption, type }) => {
        let leaf = event.target as HTMLElement;
        let isSet = false;

        const unsetActiveSuggestion = () => {
          setOption('activeId', null);
          isSet = true;
        };

        if (!isSlateString(leaf)) unsetActiveSuggestion();

        while (
          leaf.parentElement &&
          !isSlateElement(leaf.parentElement) &&
          !isSlateEditor(leaf.parentElement)
        ) {
          if (leaf.classList.contains(`slate-${type}`)) {
            const suggestionEntry = api.suggestion!.node({ isText: true });

            if (!suggestionEntry) {
              unsetActiveSuggestion();
              break;
            }

            const id = api.suggestion!.nodeId(suggestionEntry[0]);
            setOption('activeId', id ?? null);
            isSet = true;
            break;
          }

          leaf = leaf.parentElement;
        }

        if (!isSet) unsetActiveSuggestion();
      },
    },
    // ... previous options and render
  })
);
```

The click handler tracks which suggestion is currently active:
- **Detects suggestion clicks**: Traverses DOM to find suggestion elements
- **Sets active state**: Updates `activeId` when clicking on suggestions
- **Clears state**: Unsets `activeId` when clicking outside suggestions
- **Visual feedback**: Enables hover/active styling in suggestion components

### Add Plugins

```tsx
import { createPlateEditor, createPlatePlugin } from 'platejs/react';
import { SuggestionLineBreak } from '@/components/ui/suggestion-node';

const suggestionLineBreakPlugin = createPlatePlugin({
  key: 'suggestionLineBreak',
  render: { belowNodes: SuggestionLineBreak as any },
});

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    suggestionPlugin,
    suggestionLineBreakPlugin,
  ],
});
```

- `render.belowNodes`: Renders [`SuggestionLineBreak`](/docs/components/suggestion-node) below nodes to handle line break suggestions

### Enable Suggestion Mode

Use the plugin's API to control suggestion mode:

```tsx
import { useEditorRef, usePluginOption } from 'platejs/react';

function SuggestionToolbar() {
  const editor = useEditorRef();
  const isSuggesting = usePluginOption(suggestionPlugin, 'isSuggesting');

  const toggleSuggesting = () => {
    editor.setOption(suggestionPlugin, 'isSuggesting', !isSuggesting);
  };

  return (
    <button onClick={toggleSuggesting}>
      {isSuggesting ? 'Stop Suggesting' : 'Start Suggesting'}
    </button>
  );
}
```

### Add Toolbar Button

You can add [`SuggestionToolbarButton`](/docs/components/suggestion-toolbar-button) to your [Toolbar](/docs/toolbar) to toggle suggestion mode in the editor.

### Discussion Integration

The suggestion plugin works with the [discussion plugin](/docs/discussion) for complete collaboration:

```tsx
const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    discussionPlugin,
    suggestionPlugin.configure({
      options: {
        currentUserId: 'alice',
      },
    }),
    suggestionLineBreakPlugin,
  ],
});
```

</Steps>

## Keyboard Shortcuts

<KeyTable>
  <KeyTableItem hotkey="Cmd + Shift + S">
    Add a suggestion on the selected text.
  </KeyTableItem>
</KeyTable>

## Plate Plus

[discussion-pro registry content](https://platejs.org/r/discussion-pro)

## Plugins

### `SuggestionPlugin`

Plugin for creating and managing text and block suggestions with state tracking and discussion integration.

<API name="SuggestionPlugin">
<APIOptions>
  <APIItem name="currentUserId" type="string | null">
    ID of the current user creating suggestions. Required for proper suggestion attribution.
  </APIItem>
  <APIItem name="isSuggesting" type="boolean">
    Whether the editor is currently in suggestion mode. Used internally to track state.
  </APIItem>
</APIOptions>
</API>

## API

### `api.suggestion.dataList`

Gets suggestion data from a text node.

<API name="dataList">
<APIParameters>
  <APIItem name="node" type="TSuggestionText">
    The suggestion text node.
  </APIItem>
</APIParameters>
<APIReturns type="TInlineSuggestionData[]">
  Array of suggestion data.
</APIReturns>
</API>

### `api.suggestion.isBlockSuggestion`

Checks if a node is a block suggestion element.

<API name="isBlockSuggestion">
<APIParameters>
  <APIItem name="node" type="TElement">
    The node to check.
  </APIItem>
</APIParameters>
<APIReturns type="node is TSuggestionElement">
  Whether the node is a block suggestion.
</APIReturns>
</API>

### `api.suggestion.node`

Gets a suggestion node entry.

<API name="node">
<APIOptions type="EditorNodesOptions & { id?: string; isText?: boolean }" optional>
  Options for finding the node.
</APIOptions>
<APIReturns type="NodeEntry<TSuggestionElement | TSuggestionText> | undefined">
  The suggestion node entry if found.
</APIReturns>
</API>

### `api.suggestion.nodeId`

Gets the ID of a suggestion from a node.

<API name="nodeId">
<APIParameters>
  <APIItem name="node" type="TElement | TSuggestionText">
    The node to get ID from.
  </APIItem>
</APIParameters>
<APIReturns type="string | undefined">
  The suggestion ID if found.
</APIReturns>
</API>

### `api.suggestion.nodes`

Gets all suggestion node entries matching the options.

<API name="nodes">
<APIOptions type="EditorNodesOptions" optional>
  Options for finding the nodes.
</APIOptions>
<APIReturns type="NodeEntry<TElement | TSuggestionText>[]">
  Array of suggestion node entries.
</APIReturns>
</API>

### `api.suggestion.suggestionData`

Gets suggestion data from a node.

<API name="suggestionData">
<APIParameters>
  <APIItem name="node" type="TElement | TSuggestionText">
    The node to get suggestion data from.
  </APIItem>
</APIParameters>
<APIReturns type="TInlineSuggestionData | TSuggestionElement['suggestion'] | undefined">
  The suggestion data if found.
</APIReturns>
</API>

### `api.suggestion.withoutSuggestions`

Temporarily disables suggestions while executing a function.

<API name="withoutSuggestions">
<APIParameters>
  <APIItem name="fn" type="() => void">
    The function to execute.
  </APIItem>
</APIParameters>
</API>

## Types

### `TSuggestionText`

Text nodes that can contain suggestions.

<API name="TSuggestionText">
<APIAttributes>
  <APIItem name="suggestion" type="boolean" optional>
    Whether this is a suggestion.
  </APIItem>
  <APIItem name="suggestion_<id>" type="TInlineSuggestionData" optional>
    Suggestion data. Multiple suggestions can exist in one text node.
  </APIItem>
</APIAttributes>
</API>

### `TSuggestionElement`

Block elements that contain suggestion metadata.

<API name="TSuggestionElement">
<APIAttributes>
  <APIItem name="suggestion" type="TSuggestionData">
    Block-level suggestion data including type, user, and timing information.
  </APIItem>
</APIAttributes>
</API>

### `TInlineSuggestionData`

Data structure for inline text suggestions.

<API name="TInlineSuggestionData">
<APIAttributes>
  <APIItem name="id" type="string">
    Unique identifier for the suggestion.
  </APIItem>
  <APIItem name="userId" type="string">
    ID of the user who created the suggestion.
  </APIItem>
  <APIItem name="createdAt" type="number">
    Timestamp when the suggestion was created.
  </APIItem>
  <APIItem name="type" type="'insert' | 'remove' | 'update'">
    Type of suggestion operation.
  </APIItem>
  <APIItem name="newProperties" type="object" optional>
    For update suggestions, the new mark properties being suggested.
  </APIItem>
  <APIItem name="properties" type="object" optional>
    For update suggestions, the previous mark properties.
  </APIItem>
</APIAttributes>
</API>

### `TSuggestionData`

Data structure for block-level suggestions.

<API name="TSuggestionData">
<APIAttributes>
  <APIItem name="id" type="string">
    Unique identifier for the suggestion.
  </APIItem>
  <APIItem name="userId" type="string">
    ID of the user who created the suggestion.
  </APIItem>
  <APIItem name="createdAt" type="number">
    Timestamp when the suggestion was created.
  </APIItem>
  <APIItem name="type" type="'insert' | 'remove'">
    Type of block suggestion operation.
  </APIItem>
  <APIItem name="isLineBreak" type="boolean" optional>
    Whether this suggestion represents a line break insertion.
  </APIItem>
</APIAttributes>
</API>


# Collaboration

Source: https://platejs.org/docs/yjs

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Collaboration
description: Real-time collaboration with Yjs
toc: true
---

[collaboration-demo registry content](https://platejs.org/r/collaboration-demo)

<PackageInfo>

## Features

- **Multi-Provider Support:** Enables real-time collaboration using [Yjs](https://github.com/yjs/yjs) and [slate-yjs](https://docs.slate-yjs.dev/). Supports multiple synchronization providers simultaneously (e.g., IndexedDB + Hocuspocus + WebRTC) working on a shared `Y.Doc`.
- **Built-in Providers:** Includes support for [IndexedDB](https://github.com/yjs/y-indexeddb) local persistence, [Hocuspocus](https://tiptap.dev/hocuspocus) server-based collaboration, and [WebRTC](https://github.com/yjs/y-webrtc) peer-to-peer collaboration.
- **Custom Providers:** Extensible architecture allows adding custom providers by implementing the `UnifiedProvider` interface.
- **Awareness & Cursors:** Integrates Yjs Awareness protocol for sharing cursor locations and other ephemeral state between users. Includes [`RemoteCursorOverlay`](/docs/components/remote-cursor-overlay) for rendering remote cursors.
- **Customizable Cursors:** Cursor appearance (name, color) can be customized via `cursors`.
- **Manual Lifecycle:** Provides explicit `init` and `destroy` methods for managing the Yjs connection lifecycle.

</PackageInfo>

## Usage

<Steps>

### Installation

Install the core Yjs plugin.

```bash
npm install @platejs/yjs
```

For Hocuspocus server-based collaboration:

```bash
npm install @hocuspocus/provider
```

For WebRTC peer-to-peer collaboration:

```bash
npm install y-webrtc
```

### Add Plugin

```tsx
import { YjsPlugin } from '@platejs/yjs/react';
import { createPlateEditor } from 'platejs/react';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    YjsPlugin,
  ],
  // Important: Skip Plate's default initialization when using Yjs
  skipInitialization: true,
});
```

<Callout type="warning" title="Required Editor Configuration">
  It's crucial to set `skipInitialization: true` when creating the editor. Yjs manages the initial document state, so Plate's default value initialization should be skipped to avoid conflicts.
</Callout>

### Configure YjsPlugin

Configure the plugin with providers and cursor settings:

```tsx
import { YjsPlugin } from '@platejs/yjs/react';
import { createPlateEditor } from 'platejs/react';
import { RemoteCursorOverlay } from '@/components/ui/remote-cursor-overlay';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    YjsPlugin.configure({
      render: {
        afterEditable: RemoteCursorOverlay,
      },
      options: {
        // Configure local user cursor appearance
        cursors: {
          data: {
            name: 'User Name', // Replace with dynamic user name
            color: '#aabbcc', // Replace with dynamic user color
          },
        },
        // Configure providers. All providers share the same Y.Doc and Awareness instance.
        providers: [
          // Example: IndexedDB provider for local persistence
          {
            type: 'indexeddb',
            options: {
              docName: 'my-document-id', // Unique IndexedDB database name
            },
          },
          // Example: Hocuspocus provider
          {
            type: 'hocuspocus',
            options: {
              name: 'my-document-id', // Unique identifier for the document
              url: 'ws://localhost:8888', // Your Hocuspocus server URL
            },
          },
          // Example: WebRTC provider (can be used alongside Hocuspocus)
          {
            type: 'webrtc',
            options: {
              roomName: 'my-document-id', // Must match the document identifier
              signaling: ['ws://localhost:4444'], // Optional: Your signaling server URLs
            },
          },
        ],
      },
    }),
  ],
  skipInitialization: true,
});
```

- `render.afterEditable`: Assigns [`RemoteCursorOverlay`](/docs/components/remote-cursor-overlay) to render remote user cursors.
- `cursors.data`: Configures the local user's cursor appearance with name and color.
- `providers`: Array of collaboration providers to use (Hocuspocus, WebRTC, or custom providers).

### Add Editor Container

The `RemoteCursorOverlay` requires a positioned container around the editor content. Use [`EditorContainer`](/docs/components/editor) component or `PlateContainer` from `platejs/react`:

```tsx
import { Plate } from 'platejs/react';
import { EditorContainer } from '@/components/ui/editor';

return (
  <Plate editor={editor}>
    <EditorContainer>
      <Editor />
    </EditorContainer>
  </Plate>
);
```

### Initialize Yjs Connection

Yjs connection and state initialization are handled manually, typically within a `useEffect` hook:

```tsx
import React, { useEffect } from 'react';
import { YjsPlugin } from '@platejs/yjs/react';
import { useMounted } from '@/hooks/use-mounted'; // Or your own mounted check

const MyEditorComponent = ({ documentId, initialValue }) => {
  const editor = usePlateEditor(/** editor config from previous steps **/);
  const mounted = useMounted();

  useEffect(() => {
    // Ensure component is mounted and editor is ready
    if (!mounted) return;

    // Initialize Yjs connection, sync document, and set initial editor state
    editor.getApi(YjsPlugin).yjs.init({
      id: documentId,          // Unique identifier for the Yjs document
      value: initialValue,     // Initial content if the Y.Doc is empty
    });

    // Clean up: Destroy connection when component unmounts
    return () => {
      editor.getApi(YjsPlugin).yjs.destroy();
    };
  }, [editor, mounted]);

  return (
    <Plate editor={editor}>
      <EditorContainer>
        <Editor />
      </EditorContainer>
    </Plate>
  );
};
```

<Callout>
  **Initial Value**: The `value` passed to `init` is only used to populate the Y.Doc if it's completely empty on the backend/peer network. If the document already exists, its content will be synced, and this initial value will be ignored.
  
  **Lifecycle Management**: You **must** call `editor.api.yjs.init()` to establish the connection and `editor.api.yjs.destroy()` on component unmount to clean up resources.
</Callout>

### Monitor Connection Status (Optional)

Access provider states and add event handlers for connection monitoring:

```tsx
import React from 'react';
import { YjsPlugin } from '@platejs/yjs/react';
import { usePluginOption } from 'platejs/react';

function EditorStatus() {
  // Access provider states directly (read-only)
  const providers = usePluginOption(YjsPlugin, '_providers');
  const isConnected = usePluginOption(YjsPlugin, '_isConnected');

  return (
    <div>
      {providers.map((provider) => (
        <span key={provider.type}>
          {provider.type}: {provider.isConnected ? 'Connected' : 'Disconnected'} ({provider.isSynced ? 'Synced' : 'Syncing'})
        </span>
      ))}
    </div>
  );
}

// Add event handlers for connection events:
YjsPlugin.configure({
  options: {
    // ... other options
    onConnect: ({ type }) => console.debug(`Provider ${type} connected!`),
    onDisconnect: ({ type }) => console.debug(`Provider ${type} disconnected.`),
    onSyncChange: ({ type, isSynced }) => console.debug(`Provider ${type} sync status: ${isSynced}`),
    onError: ({ type, error }) => console.error(`Error in provider ${type}:`, error),
  },
});
```

</Steps>

## Provider Types

### Hocuspocus Provider

Server-based collaboration using [Hocuspocus](https://tiptap.dev/hocuspocus). Requires a running Hocuspocus server.

```tsx
type HocuspocusProviderConfig = {
  type: 'hocuspocus',
  options: {
    name: string;     // Document identifier
    url: string;      // WebSocket server URL
    token?: string;   // Authentication token
    wsOptions?: HocuspocusProviderWebsocketConfiguration; // Advanced websocket config (headers, protocols, etc.)
  }
}
```

#### `wsOptions`

You can pass a `wsOptions` field to configure advanced websocket options for the Hocuspocus provider. This is useful for custom headers, authentication, protocols, or other websocket settings supported by [`HocuspocusProviderWebsocket`](https://tiptap.dev/hocuspocus/api/provider#websocket-configuration).

Example usage:

```tsx
{
  type: 'hocuspocus',
  options: {
    name: 'my-document-id',
  },
  wsOptions: {
    url: 'ws://localhost:8888',
    maxAttempts: 5,
    parameters: {
      // request parameters
    }
  },
}
```

### WebRTC Provider

Peer-to-peer collaboration using [y-webrtc](https://github.com/yjs/y-webrtc).

```tsx
type WebRTCProviderConfig = {
  type: 'webrtc',
  options: {
    roomName: string;      // Room name for collaboration
    signaling?: string[];  // Signaling server URLs
    password?: string;     // Room password
    maxConns?: number;     // Max connections
    peerOpts?: object;     // WebRTC peer options
  }
}
```

### IndexedDB Provider

Local browser persistence using [y-indexeddb](https://github.com/yjs/y-indexeddb). Use it alongside a network provider when the editor should restore local state before remote sync finishes.

```tsx
type IndexeddbProviderConfig = {
  type: 'indexeddb',
  options: {
    docName: string; // Stable IndexedDB database name for this document
  }
}
```

### Custom Provider

Create custom providers by implementing the `UnifiedProvider` interface:

```typescript
interface UnifiedProvider {
  awareness: Awareness;
  document: Y.Doc;
  type: string;
  connect: () => void;
  destroy: () => void;
  disconnect: () => void;
  isConnected: boolean;
  isSynced: boolean;
}
```

Use custom providers directly in the providers array:

```tsx
const customProvider = new MyCustomProvider({ doc: ydoc, awareness });

YjsPlugin.configure({
  options: {
    providers: [customProvider],
  },
});
```

## Backend Setup

### IndexedDB Local Persistence

IndexedDB runs in the browser and uses the shared `Y.Doc` created by `YjsPlugin`. Use the same document identifier for `docName` and your network provider room/name when you combine providers:

```tsx
{
  type: 'indexeddb',
  options: {
    docName: 'document-1',
  },
}
```

IndexedDB does not transport remote awareness or cursors. It persists document updates locally; Hocuspocus or WebRTC still own multi-user transport.

### Hocuspocus Server

Set up a [Hocuspocus server](https://tiptap.dev/hocuspocus/getting-started) for server-based collaboration. Ensure the `url` and `name` in your provider options match your server configuration.

### WebRTC Setup

#### Signaling Server

WebRTC requires signaling servers for peer discovery. Public servers work for testing but use your own for production:

```bash
npm install y-webrtc
PORT=4444 node ./node_modules/y-webrtc/bin/server.js
```

Configure your client to use custom signaling:

```tsx
{
  type: 'webrtc',
  options: {
    roomName: 'document-1',
    signaling: ['ws://your-signaling-server.com:4444'],
  },
}
```

#### TURN Servers

<Callout type="warning">
  WebRTC connections can fail due to firewalls. Use TURN servers or combine with Hocuspocus for production reliability.
</Callout>

Configure TURN servers for reliable connections:

```tsx
{
  type: 'webrtc',
  options: {
    roomName: 'document-1',
    signaling: ['ws://your-signaling-server.com:4444'],
    peerOpts: {
      config: {
        iceServers: [
          { urls: 'stun:stun.l.google.com:19302' },
          {
            urls: 'turn:your-turn-server.com:3478',
            username: 'username',
            credential: 'password'
          }
        ]
      }
    }
  }
}
```

## Security

**Authentication & Authorization:**
- Use Hocuspocus's `onAuthenticate` hook to validate users
- Implement document-level access control on your backend
- Pass authentication tokens via the `token` option

**Transport Security:**
- Use `wss://` URLs in production for encrypted communication
- Configure secure TURN servers with the `turns://` protocol

**WebRTC Security:**
- Use the `password` option for basic room access control
- Configure secure signaling servers

Example secure configuration:

```tsx
YjsPlugin.configure({
  options: {
    providers: [
      {
        type: 'hocuspocus',
        options: {
          name: 'secure-document-id',
          url: 'wss://your-hocuspocus-server.com',
          token: 'user-auth-token',
        },
      },
      {
        type: 'webrtc',
        options: {
          roomName: 'secure-document-id',
          password: 'strong-room-password',
          signaling: ['wss://your-secure-signaling.com'],
          peerOpts: {
            config: {
              iceServers: [
                {
                  urls: 'turns:your-turn-server.com:443?transport=tcp',
                  username: 'user',
                  credential: 'pass'
                }
              ]
            }
          }
        },
      },
    ],
  },
});
```

## Troubleshooting

### Connection Issues

**Check URLs and Names:**
- Verify `url` (Hocuspocus) and `signaling` URLs (WebRTC) are correct
- Ensure `docName`, `name`, or `roomName` matches exactly across providers that share one document
- Use `ws://` for local development, `wss://` for production

**Server Status:**
- Verify Hocuspocus and signaling servers are running
- Check server logs for errors
- Test TURN server connectivity if using WebRTC

**Network Issues:**
- Firewalls may block WebSocket or WebRTC traffic
- Use TURN servers configured for TCP (port 443) for better traversal
- Check browser console for provider errors

### Multiple Documents

**Separate Instances:**
- Create separate `Y.Doc` instances for each document
- Use unique document identifiers for `name`/`roomName`
- Pass unique `ydoc` and `awareness` instances to each editor

### Sync Issues

**Editor Initialization:**
- Always set `skipInitialization: true` when creating the editor
- Use `editor.api.yjs.init({ value })` for initial content
- Ensure all providers use the exact same document identifier

**Content Conflicts:**
- Avoid manually manipulating the shared `Y.Doc`
- Let Yjs handle all document operations through the editor

### Cursor Issues

**Overlay Setup:**
- Include [`RemoteCursorOverlay`](/docs/components/remote-cursor-overlay) in plugin render config
- Use positioned container (`EditorContainer` or `PlateContainer`)
- Verify `cursors.data` (name, color) is set correctly for local user

## Related

- [Yjs](https://github.com/yjs/yjs) - CRDT framework for collaboration
- [slate-yjs](https://docs.slate-yjs.dev/) - Yjs bindings for Slate
- [y-indexeddb](https://github.com/yjs/y-indexeddb) - IndexedDB persistence provider
- [Hocuspocus](https://tiptap.dev/hocuspocus) - Backend server for Yjs
- [y-webrtc](https://github.com/yjs/y-webrtc) - WebRTC provider
- [RemoteCursorOverlay](/docs/components/remote-cursor-overlay) - Remote cursor component
- [EditorContainer](/docs/components/editor) - Editor container component

## Plugins

### `YjsPlugin`

Enables real-time collaboration using Yjs with support for multiple providers and remote cursors.

<API name="YjsPlugin">
<APIOptions>
  <APIItem name="providers" type="(UnifiedProvider | YjsProviderConfig)[]">
    Array of provider configurations or pre-instantiated provider instances. The plugin will create instances from configurations and use existing instances directly. All providers will share the same Y.Doc and Awareness. Each configuration object specifies a provider `type` (for example `'indexeddb'`, `'hocuspocus'`,
    or `'webrtc'`) and its specific `options`. Custom provider instances must conform to the
    `UnifiedProvider` interface.
  </APIItem>
  <APIItem name="cursors" type="WithCursorsOptions | null" optional>
    Configuration for remote cursors. Set to `null` to explicitly disable cursors. If omitted, cursors are enabled by default if providers are specified. Passed to `withTCursors`. See [WithCursorsOptions API](https://docs.slate-yjs.dev/api/slate-yjs-core/cursor-plugin#withcursors). Includes `data` for local user info and `autoSend` (default `true`).
  </APIItem>
  <APIItem name="ydoc" type="Y.Doc" optional>
    Optional shared Y.Doc instance. If not provided, a new one will be created internally by the plugin. Provide your own if integrating with other Yjs tools or managing multiple documents.
  </APIItem>
  <APIItem name="awareness" type="Awareness" optional>
    Optional shared Awareness instance. If not provided, a new one will be created.
  </APIItem>
  <APIItem name="onConnect" type="(props: { type: YjsProviderType }) => void" optional>
    Callback fired when any provider successfully connects.
  </APIItem>
  <APIItem name="onDisconnect" type="(props: { type: YjsProviderType }) => void" optional>
    Callback fired when any provider disconnects.
  </APIItem>
  <APIItem name="onError" type="(props: { error: Error; type: YjsProviderType }) => void" optional>
    Callback fired when any provider encounters an error (e.g., connection failure).
  </APIItem>
  <APIItem name="onSyncChange" type="(props: { isSynced: boolean; type: YjsProviderType }) => void" optional>
    Callback fired when the sync status (`provider.isSynced`) of any individual provider changes.
  </APIItem>
</APIOptions>
<APIAttributes>
  {/* Attributes are internal state, generally use options or event handlers instead */}
  <APIItem name="_isConnected" type="boolean">
    Internal state: Whether at least one provider is currently connected.
  </APIItem>
  <APIItem name="_isSynced" type="boolean">
    Internal state: Reflects overall sync status.
  </APIItem>
  <APIItem name="_providers" type="UnifiedProvider[]">
    Internal state: Array of all active, instantiated provider instances.
  </APIItem>
</APIAttributes>
</API>

## API

### `api.yjs.init`

Initializes the Yjs connection, binds it to the editor, sets up providers based on plugin configuration, potentially populates the Y.Doc with initial content, and connects providers. **Must be called after the editor is mounted.**

<API name="editor.api.yjs.init">
<APIParameters>
  <APIItem name="options" type="object" optional>
    Configuration object for initialization.
  </APIItem>
</APIParameters>

<APIOptions type="object">
  <APIItem name="id" type="string" optional>
    A unique identifier for the Yjs document (e.g., room name, document ID). If not provided, `editor.id` is used. Essential for ensuring collaborators connect to the same document state.
  </APIItem>
  <APIItem name="value" type="Value | string | ((editor: PlateEditor) => Value | Promise<Value>)" optional>
    The initial content for the editor. **This is only applied if the Y.Doc associated with the `id` is completely empty in the shared state (backend/peers).** If the document already exists, its content will be synced, ignoring this value. Can be Plate JSON (`Value`), an HTML string, or a function returning/resolving to `Value`. If omitted or empty, a default empty paragraph is used for initialization if the Y.Doc is new.
  </APIItem>
  <APIItem name="autoConnect" type="boolean" optional>
    Whether to automatically call `provider.connect()` for all configured providers during initialization. Default: `true`. Set to `false` if you want to manage connections manually using `editor.api.yjs.connect()`.
  </APIItem>
  <APIItem name="autoSelect" type="'start' | 'end'" optional>
    If set, automatically focuses the editor and places the cursor at the 'start' or 'end' of the document after initialization and sync.
  </APIItem>
  <APIItem name="selection" type="Location" optional>
    Specific Plate `Location` to set the selection to after initialization, overriding `autoSelect`.
  </APIItem>
</APIOptions>

<APIReturns type="Promise<void>">
  Resolves when the initial setup (including potential async `value` resolution and YjsEditor binding) is complete. Note that provider connection and synchronization happen asynchronously.
</APIReturns>
</API>

### `api.yjs.destroy`

Disconnects all providers, cleans up Yjs bindings (detaches editor from Y.Doc), and destroys the awareness instance. **Must be called when the editor component unmounts** to prevent memory leaks and stale connections.

### `api.yjs.connect`

Manually connects to providers. Useful if `autoConnect: false` was used during `init`.

<API name="editor.api.yjs.connect">
<APIParameters>
 <APIItem name="type" type="YjsProviderType | YjsProviderType[]" optional>
   If provided, only connects to providers of the specified type(s). If omitted, connects to all configured providers that are not already connected.
 </APIItem>
</APIParameters>
</API>

### `api.yjs.disconnect`

Manually disconnects from providers.

<API name="editor.api.yjs.disconnect">
<APIParameters>
 <APIItem name="type" type="YjsProviderType | YjsProviderType[]" optional>
   If provided, only disconnects from providers of the specified type(s). If omitted, disconnects from all currently connected providers.
 </APIItem>
</APIParameters>
</API>


# Basic Blocks

Source: https://platejs.org/docs/basic-blocks

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Basic Blocks
description: Paragraphs, headings, blockquotes, and horizontal rules.
docs:
  - route: /docs/components/paragraph-node
    title: Paragraph Element
  - route: /docs/components/heading-node
    title: Heading Element
  - route: /docs/components/blockquote-node
    title: Blockquote Element
  - route: /docs/components/hr-node
    title: Horizontal Rule Element
---

Basic Blocks is the registry kit for the common structural blocks in a Plate editor. It wires paragraphs, six heading levels, blockquotes, and horizontal rules to Plate UI components. Use the leaf docs when you need the behavior details for one block type.

<Cards>

<Card icon="heading" title="Heading" href="/docs/heading">
Structure content with H1 through H6 blocks.
</Card>

<Card icon="blockquote" title="Blockquote" href="/docs/blockquote">
Wrap quoted or emphasized content in a blockquote.
</Card>

<Card icon="horizontal-rule" title="Horizontal Rule" href="/docs/horizontal-rule">
Insert a void divider between sections.
</Card>

</Cards>

[basic-blocks-demo registry content](https://platejs.org/r/basic-blocks-demo)

<PackageInfo>

## Features

- Paragraph, H1-H6, blockquote, and horizontal rule components.
- Markdown shortcuts for headings, blockquotes, and horizontal rules.
- Keyboard shortcuts for heading toggles and blockquote toggling.
- Static rendering companion through `basic-blocks-base-kit`.
- Leaf docs for block-specific setup and API details.

</PackageInfo>

## Fast Path

<Steps>

### Add The Kit

`BasicBlocksKit` is the normal app/editor kit. It installs the React plugins and the matching registry UI components.

[basic-blocks-kit registry content](https://platejs.org/r/basic-blocks-kit)

```tsx
import { createPlateEditor } from 'platejs/react';

import { BasicBlocksKit } from '@/components/editor/plugins/basic-blocks-kit';

export const editor = createPlateEditor({
  plugins: BasicBlocksKit,
});
```

### Add Static Rendering

Use `BaseBasicBlocksKit` in static or server-safe rendering paths.

[basic-blocks-base-kit registry content](https://platejs.org/r/basic-blocks-base-kit)

```tsx
import { createStaticEditor } from 'platejs';

import { BaseBasicBlocksKit } from '@/components/editor/plugins/basic-blocks-base-kit';

const value = [
  {
    children: [{ text: 'Static content' }],
    type: 'p',
  },
];

export const staticEditor = createStaticEditor({
  plugins: BaseBasicBlocksKit,
  value,
});
```

</Steps>

## Ownership

| Layer | Owner | What It Does |
|-------|-------|--------------|
| `platejs/react` | Package | Exports `ParagraphPlugin`. |
| `@platejs/basic-nodes` | Package | Exports block rules and base block plugins. |
| `@platejs/basic-nodes/react` | Package | Exports `BlockquotePlugin`, `HeadingPlugin`, `H1Plugin` through `H6Plugin`, `HorizontalRulePlugin`, and `BasicBlocksPlugin`. |
| `basic-blocks-kit` | Registry | Adds React UI components, input rules, break rules, and shortcuts. |
| `basic-blocks-base-kit` | Registry | Adds static UI components for static rendering. |
| Leaf pages | Docs | Own block-specific behavior: [`Heading`](/docs/heading), [`Blockquote`](/docs/blockquote), and [`Horizontal Rule`](/docs/horizontal-rule). |

`BasicBlocksPlugin` is a package-level grouping plugin. It does not install the registry UI components; use `BasicBlocksKit` when you want Plate UI rendering.

## Included Plugins

| Block | Plugin | Registry Component | Notes |
|-------|--------|--------------------|-------|
| Paragraph | `ParagraphPlugin` | `ParagraphElement` | Comes from `platejs/react`; the registry kit adds the UI component. |
| Heading 1-6 | `H1Plugin` through `H6Plugin` | `H1Element` through `H6Element` | Each level gets a markdown rule and `mod+alt+<level>` shortcut. |
| Blockquote | `BlockquotePlugin` | `BlockquoteElement` | Uses a wrapping transform and `mod+shift+period`. |
| Horizontal rule | `HorizontalRulePlugin` | `HrElement` | Void block; supports dash and underscore markdown rules. |

## Markdown Shortcuts

| Shortcut | Result |
|----------|--------|
| `# ` through `###### ` | Converts the current paragraph into H1 through H6. |
| `> ` | Wraps the current block in a blockquote. |
| `---` | Converts the current block into a horizontal rule, then inserts a paragraph after it. |
| `___ ` | Converts the current block into a horizontal rule, then inserts a paragraph after it. |

See [`Plugin Input Rules`](/docs/plugin-input-rules) for the rule engine and trigger model.

## Manual Setup

Use manual setup when you want the package plugins without the registry kit.

```bash
npm install @platejs/basic-nodes
```

```tsx
import {
  BlockquoteRules,
  HeadingRules,
  HorizontalRuleRules,
} from '@platejs/basic-nodes';
import {
  BlockquotePlugin,
  H1Plugin,
  H2Plugin,
  H3Plugin,
  H4Plugin,
  H5Plugin,
  H6Plugin,
  HorizontalRulePlugin,
} from '@platejs/basic-nodes/react';
import { createPlateEditor, ParagraphPlugin } from 'platejs/react';

export const editor = createPlateEditor({
  plugins: [
    ParagraphPlugin,
    H1Plugin.configure({
      inputRules: [HeadingRules.markdown()],
      shortcuts: { toggle: { keys: 'mod+alt+1' } },
    }),
    H2Plugin.configure({
      inputRules: [HeadingRules.markdown()],
      shortcuts: { toggle: { keys: 'mod+alt+2' } },
    }),
    H3Plugin.configure({
      inputRules: [HeadingRules.markdown()],
      shortcuts: { toggle: { keys: 'mod+alt+3' } },
    }),
    H4Plugin.configure({
      inputRules: [HeadingRules.markdown()],
      shortcuts: { toggle: { keys: 'mod+alt+4' } },
    }),
    H5Plugin.configure({
      inputRules: [HeadingRules.markdown()],
      shortcuts: { toggle: { keys: 'mod+alt+5' } },
    }),
    H6Plugin.configure({
      inputRules: [HeadingRules.markdown()],
      shortcuts: { toggle: { keys: 'mod+alt+6' } },
    }),
    BlockquotePlugin.configure({
      inputRules: [BlockquoteRules.markdown()],
      shortcuts: { toggle: { keys: 'mod+shift+period' } },
    }),
    HorizontalRulePlugin.configure({
      inputRules: [
        HorizontalRuleRules.markdown({ variant: '-' }),
        HorizontalRuleRules.markdown({ variant: '_' }),
      ],
    }),
  ],
});
```

## API Reference

| API | Use |
|-----|-----|
| `BasicBlocksPlugin` | Package grouping plugin for blockquote, heading, and horizontal rule behavior. |
| `BaseBasicBlocksPlugin` | Static/headless grouping plugin for blockquote, heading, and horizontal rule behavior. |
| `HeadingRules.markdown()` | Creates heading input rules based on the configured H1-H6 plugin key. |
| `BlockquoteRules.markdown()` | Creates the `> ` block-start rule. |
| `HorizontalRuleRules.markdown({ variant })` | Creates dash or underscore thematic-break rules. |


# Blockquote

Source: https://platejs.org/docs/blockquote

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Blockquote
docs:
  - route: /docs/components/blockquote-node
    title: Blockquote Element
---

[basic-blocks-demo registry content](https://platejs.org/r/basic-blocks-demo)

<PackageInfo>

## Features

- Create blockquotes to emphasize important information or highlight quotes from external sources.
- Renders as `<blockquote>` HTML element by default.
- Supports nested block content such as paragraphs, lists, and nested blockquotes.

</PackageInfo>

## Kit Usage

<Steps>

### Installation

The fastest way to add the blockquote plugin is with the `BasicBlocksKit`, which includes pre-configured `BlockquotePlugin` along with other basic block elements and their [Plate UI](/docs/installation/plate-ui) components.

[basic-blocks-kit registry content](https://platejs.org/r/basic-blocks-kit)

- [`BlockquoteElement`](/docs/components/blockquote-node): Renders blockquote elements.

### Add Kit

Add the kit to your plugins:

```tsx
import { createPlateEditor } from 'platejs/react';
import { BasicBlocksKit } from '@/components/editor/plugins/basic-blocks-kit';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    ...BasicBlocksKit,
  ],
});
```

</Steps>

## Manual Usage

<Steps>

### Installation

```bash
npm install @platejs/basic-nodes
```

### Add Plugin

Include `BlockquotePlugin` in your Plate plugins array when creating the editor.

```tsx
import { BlockquotePlugin } from '@platejs/basic-nodes/react';
import { createPlateEditor } from 'platejs/react';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    BlockquotePlugin,
  ],
});
```

### Configure Plugin

You can configure the `BlockquotePlugin` with options such as a specific rendering component or custom keyboard shortcuts.

```tsx
import { BlockquotePlugin } from '@platejs/basic-nodes/react';
import { createPlateEditor } from 'platejs/react';
import { BlockquoteElement } from '@/components/ui/blockquote-node';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    BlockquotePlugin.configure({
      node: { component: BlockquoteElement },
      shortcuts: { toggle: 'mod+shift+.' },
    }),
  ],
});
```

- `node.component`: Assigns [`BlockquoteElement`](/docs/components/blockquote-node) to render blockquote elements.
- `shortcuts.toggle`: Defines a keyboard [shortcut](/docs/plugin-shortcuts) to toggle blockquote formatting.

### Turn Into Toolbar Button

You can add blockquote to the [Turn Into Toolbar Button](/docs/toolbar#turn-into-toolbar-button) to toggle blockquotes:

```tsx
{
  icon: <QuoteIcon />,
  label: 'Quote',
  value: KEYS.blockquote,
}
```

### Insert Toolbar Button

You can add blockquote to the [Insert Toolbar Button](/docs/toolbar#insert-toolbar-button) to insert blockquotes:

```tsx
{
  icon: <QuoteIcon />,
  label: 'Quote',
  value: KEYS.blockquote,
}
```

</Steps>

## Plugins

### `BlockquotePlugin`

Plugin for blockquote container elements. Renders as `<blockquote>` HTML element by default.

## Transforms

### `tf.blockquote.toggle`

Wraps the current block or selection in a blockquote. If the selection is already inside a blockquote, it unwraps the quoted blocks.


# Callout

Source: https://platejs.org/docs/callout

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Callout
docs:
  - route: https://pro.platejs.org/docs/components/callout-node
    title: Plus
  - route: /docs/components/callout
    title: Callout Element
---

[callout-demo registry content](https://platejs.org/r/callout-demo)

<PackageInfo>

## Features

- Customizable callout blocks for highlighting important information
- Support for different callout variants (e.g., info, warning, error)
- Ability to set custom icons or emojis for callouts

</PackageInfo>

## Kit Usage

<Steps>

### Installation

The fastest way to add the callout plugin is with the `CalloutKit`, which includes pre-configured `CalloutPlugin` with the [Plate UI](/docs/installation/plate-ui) component.

[callout-kit registry content](https://platejs.org/r/callout-kit)

- [`CalloutElement`](/docs/components/callout-node): Renders callout elements.

### Add Kit

Add the kit to your plugins:

```tsx
import { createPlateEditor } from 'platejs/react';
import { CalloutKit } from '@/components/editor/plugins/callout-kit';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    ...CalloutKit,
  ],
});
```

</Steps>

## Manual Usage

<Steps>

### Installation

```bash
npm install @platejs/callout
```

### Add Plugin

Include `CalloutPlugin` in your Plate plugins array when creating the editor.

```tsx
import { CalloutPlugin } from '@platejs/callout/react';
import { createPlateEditor } from 'platejs/react';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    CalloutPlugin,
  ],
});
```

### Configure Plugin

You can configure the `CalloutPlugin` with a custom component to render callout elements.

```tsx
import { CalloutPlugin } from '@platejs/callout/react';
import { createPlateEditor } from 'platejs/react';
import { CalloutElement } from '@/components/ui/callout-node';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    CalloutPlugin.withComponent(CalloutElement),
  ],
});
```

- `withComponent`: Assigns [`CalloutElement`](/docs/components/callout-node) to render callout elements.

</Steps>


## Plate Plus

[callout-pro registry content](https://platejs.org/r/callout-pro)

## Plugins

### `CalloutPlugin`

Callout element plugin.

## Transforms

### `tf.insert.callout`

Insert a callout element into the editor.

<API name="callout">
<APIOptions type="object">
  <APIItem name="variant" type="string" optional>
    The variant of the callout to insert.
  </APIItem>
  <APIItem name="...InsertNodesOptions" type="InsertNodesOptions<V>">
    Other options from `InsertNodesOptions`.
  </APIItem>
</APIOptions>
</API>

## Hooks

### `useCalloutEmojiPicker`

Manage the emoji picker functionality for callouts.

<API name="useCalloutEmojiPicker">
<APIOptions type="UseCalloutEmojiPickerOptions">
  <APIItem name="isOpen" type="boolean">
    Whether the emoji picker is open.
  </APIItem>
  <APIItem name="setIsOpen" type="(isOpen: boolean) => void">
    Function to set the open state of the emoji picker.
  </APIItem>
</APIOptions>

<APIReturns type="object">
  <APIItem name="emojiToolbarDropdownProps" type="object">
    Props for the emoji toolbar dropdown.
    <APISubList>
      <APISubListItem parent="emojiToolbarDropdownProps" name="isOpen" type="boolean">
        Whether the emoji picker is open.
      </APISubListItem>
      <APISubListItem parent="emojiToolbarDropdownProps" name="setIsOpen" type="(v: boolean) => void">
        Function to set the open state of the emoji picker, respecting read-only mode.
      </APISubListItem>
    </APISubList>
  </APIItem>
  <APIItem name="props" type="object">
    Props for the emoji picker component.
    <APISubList>
      <APISubListItem parent="props" name="isOpen" type="boolean">
        Whether the emoji picker is open.
      </APISubListItem>
      <APISubListItem parent="props" name="setIsOpen" type="(isOpen: boolean) => void">
        Function to set the open state of the emoji picker.
      </APISubListItem>
      <APISubListItem parent="props" name="onSelectEmoji" type="(options: { emojiValue?: any; icon?: any }) => void">
        Function called when an emoji is selected. It updates the callout's icon and closes the picker.
      </APISubListItem>
    </APISubList>
  </APIItem>
</APIReturns>
</API>

## Types

### `TCalloutElement`

```typescript
interface TCalloutElement extends TElement {
  variant?: string;
  icon?: string;
}
```

<API name="TCalloutElement">
<APIAttributes>
  <APIItem name="variant" type="string" optional>
    The variant of the callout.
  </APIItem>
  <APIItem name="icon" type="string" optional>
    The icon or emoji to display.
  </APIItem>
</APIAttributes>
</API>


# Code Block

Source: https://platejs.org/docs/code-block

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Code Block
docs:
  - route: https://pro.platejs.org/docs/components/code-block-node
    title: Plus
  - route: /docs/components/code-block-node
    title: Code Block Element
---

[code-block-demo registry content](https://platejs.org/r/code-block-demo)

<PackageInfo>

## Features

- Syntax highlighting for code blocks
- Support for multiple programming languages
- Customizable language selection
- Proper indentation handling
- Markdown code fence shortcuts through `CodeBlockRules.markdown({ on })`

</PackageInfo>

## Kit Usage

<Steps>

### Installation

The fastest way to add code block functionality is with the `CodeBlockKit`, which includes pre-configured `CodeBlockPlugin`, `CodeLinePlugin`, and `CodeSyntaxPlugin` with syntax highlighting, the shipped triple-backtick input rule, and [Plate UI](/docs/installation/plate-ui) components.

[code-block-kit registry content](https://platejs.org/r/code-block-kit)

- [`CodeBlockElement`](/docs/components/code-block-node): Renders code block containers.
- [`CodeLineElement`](/docs/components/code-block-node): Renders individual code lines.
- [`CodeSyntaxLeaf`](/docs/components/code-block-node): Renders syntax highlighted text.

### Add Kit

Add the kit to your plugins:

```tsx
import { createPlateEditor } from 'platejs/react';
import { CodeBlockKit } from '@/components/editor/plugins/code-block-kit';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    ...CodeBlockKit,
  ],
});
```

</Steps>

## Manual Usage

<Steps>

### Installation

```bash
npm install @platejs/code-block lowlight
```

### Add Plugins

Include the code block plugins in your Plate plugins array when creating the editor.

```tsx
import { CodeBlockPlugin, CodeLinePlugin, CodeSyntaxPlugin } from '@platejs/code-block/react';
import { createPlateEditor } from 'platejs/react';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    CodeBlockPlugin,
    CodeLinePlugin,
    CodeSyntaxPlugin,
  ],
});
```

### Configure Plugins

Configure the plugins with syntax highlighting and custom components.

**Basic Setup with All Languages:**

```tsx
import { CodeBlockRules } from '@platejs/code-block';
import { CodeBlockPlugin, CodeLinePlugin, CodeSyntaxPlugin } from '@platejs/code-block/react';
import { all, createLowlight } from 'lowlight';
import { createPlateEditor } from 'platejs/react';
import { CodeBlockElement, CodeLineElement, CodeSyntaxLeaf } from '@/components/ui/code-block-node';

// Create a lowlight instance with all languages
const lowlight = createLowlight(all);

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    CodeBlockPlugin.configure({
      inputRules: [CodeBlockRules.markdown({ on: 'match' })],
      node: { component: CodeBlockElement },
      options: { lowlight },
      shortcuts: { toggle: { keys: 'mod+alt+8' } },
    }),
    CodeLinePlugin.withComponent(CodeLineElement),
    CodeSyntaxPlugin.withComponent(CodeSyntaxLeaf),
  ],
});
```

**Custom Language Setup (Optimized Bundle):**

For optimized bundle size, you can register only specific languages:

```tsx
import { createLowlight } from 'lowlight';
import css from 'highlight.js/lib/languages/css';
import js from 'highlight.js/lib/languages/javascript';
import ts from 'highlight.js/lib/languages/typescript';
import html from 'highlight.js/lib/languages/xml';

// Create a lowlight instance
const lowlight = createLowlight();

// Register only the languages you need
lowlight.register('html', html);
lowlight.register('css', css);
lowlight.register('js', js);
lowlight.register('ts', ts);

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    CodeBlockPlugin.configure({
      inputRules: [CodeBlockRules.markdown({ on: 'match' })],
      node: { component: CodeBlockElement },
      options: {
        lowlight,
        defaultLanguage: 'js', // Set default language (optional)
      },
      shortcuts: { toggle: { keys: 'mod+alt+8' } },
    }),
    CodeLinePlugin.withComponent(CodeLineElement),
    CodeSyntaxPlugin.withComponent(CodeSyntaxLeaf),
  ],
});
```

- `node.component`: Assigns [`CodeBlockElement`](/docs/components/code-block-node) to render code block containers.
- `inputRules`: Registers the triple-backtick fence rule. Use `on: 'match'` to commit when the fence becomes complete or `on: 'break'` to commit on `Enter`.
- `options.lowlight`: Lowlight instance for syntax highlighting.
- `options.defaultLanguage`: Default language when no language is specified.
- `shortcuts.toggle`: Defines a keyboard [shortcut](/docs/plugin-shortcuts) to toggle code blocks.
- `withComponent`: Assigns components for code lines and syntax highlighting.

For the runtime model, see [Plugin Input Rules](/docs/plugin-input-rules).

### Turn Into Toolbar Button

You can add this item to the [Turn Into Toolbar Button](/docs/toolbar#turn-into-toolbar-button) to convert blocks into code blocks:

```tsx
{
  icon: <FileCodeIcon />,
  label: 'Code',
  value: KEYS.codeBlock,
}
```

### Insert Toolbar Button

You can add this item to the [Insert Toolbar Button](/docs/toolbar#insert-toolbar-button) to insert code block elements:

```tsx
{
  icon: <FileCodeIcon />,
  label: 'Code',
  value: KEYS.codeBlock,
}
```

</Steps>

## Plugins

### `CodeBlockPlugin`

<API name="CodeBlockPlugin">
<APIOptions>
  <APIItem name="defaultLanguage" type="string | null" optional>
    Default language to use when no language is specified. Set to null to disable syntax highlighting by default.
  </APIItem>
  <APIItem name="lowlight" type="ReturnType<typeof createLowlight> | null" optional>
    Lowlight instance to use for highlighting. If not provided, syntax highlighting will be disabled.
  </APIItem>
</APIOptions>
</API>

## API

### `isCodeBlockEmpty`

<API name="isCodeBlockEmpty">
<APIReturns type="boolean">
  Whether the selection is in an empty code block.
</APIReturns>
</API>

### `isSelectionAtCodeBlockStart`

<API name="isSelectionAtCodeBlockStart">
<APIReturns type="boolean">
  Whether the selection is at the start of the first code line in a code block.
</APIReturns>
</API>

### `indentCodeLine`

Indents the code line if the selection is expanded or there are no non-whitespace characters at left of the cursor. The indentation is 2 spaces by default.

<API name="indentCodeLine">
<APIOptions type="IndentCodeLineOptions">
  <APIItem name="codeLine" type="ElementEntry">
    The code line to be indented.
  </APIItem>
  <APIItem name="indentDepth" type="number">
    The size of indentation for the code line.
    - **Default:** `2`
  </APIItem>
</APIOptions>
</API>

### `insertCodeBlock`

Inserts a code block by setting the node to code line and wrapping it with a code block. If the cursor is not at the block start, it inserts a break before the code block.

<API name="insertCodeBlock">
<APIParameters>
  <APIItem name="insertNodesOptions" type="Omit<InsertNodesOptions, 'match'>" optional>
    Options for inserting nodes.
  </APIItem>
</APIParameters>
</API>

### `insertCodeLine`

Inserts a code line starting with the specified indentation depth.

<API name="insertCodeLine">
<APIParameters>
  <APIItem name="indentDepth" type="number" optional>
    The depth of indentation for the code line.
    - **Default:** `0`
  </APIItem>
</APIParameters>
</API>

### `outdentCodeLine`

Outdents a code line, removing two whitespace characters if present.

<API name="outdentCodeLine">
<APIOptions type="OutdentCodeLineOptions">
  <APIItem name="codeLine" type="ElementEntry">
    The code line to be outdented.
  </APIItem>
  <APIItem name="codeBlock" type="ElementEntry">
    The code block containing the code line to be outdented.
  </APIItem>
</APIOptions>
</API>

### `toggleCodeBlock`

Toggles the code block in the editor.

### `unwrapCodeBlock`

Unwraps the code block in the editor. 


# Code Drawing

Source: https://platejs.org/docs/code-drawing

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Code Drawing
docs:
  - route: /docs/components/code-drawing-node
    title: Code Drawing Node
---

[code-drawing-demo registry content](https://platejs.org/r/code-drawing-demo)

<PackageInfo>

## Features

- Support for multiple diagram types: PlantUml, Graphviz, Flowchart, and Mermaid
- Inline code editing with code-block-like styling
- Real-time preview with debounced rendering (500ms)
- Multiple view modes: Both (code and preview), Code only, Image only
- Responsive layout: horizontal on desktop (code left, preview right), vertical on mobile (preview top, code bottom)
- Border separator between code editor and preview in Both mode
- Toolbar controls: language selector and view mode selector (always visible on mobile, hover to show on desktop)
- Download rendered diagrams as images
- Floating toolbar with delete and download actions

</PackageInfo>

## Kit Usage

<Steps>

### Installation

The fastest way to add code drawing functionality is with the `CodeDrawingKit`, which includes the pre-configured `CodeDrawingPlugin` with its [Plate UI](/docs/installation/plate-ui) components.

[code-drawing-kit registry content](https://platejs.org/r/code-drawing-kit)

- [`CodeDrawingElement`](/docs/components/code-drawing-node): Renders code drawing elements with inline editing and preview.

### Add Kit

Add the kit to your plugins:

```tsx
import { createPlateEditor } from 'platejs/react';
import { CodeDrawingKit } from '@/components/editor/plugins/code-drawing-kit';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    ...CodeDrawingKit,
  ],
});
```

</Steps>

## Manual Usage

<Steps>

### Installation

```bash
npm install @platejs/code-drawing
```

### Add Plugin

Include `CodeDrawingPlugin` in your Plate plugins array when creating the editor.

```tsx
import { CodeDrawingPlugin } from '@platejs/code-drawing/react';
import { createPlateEditor } from 'platejs/react';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    CodeDrawingPlugin,
  ],
});
```

### Configure Plugin

Configure the code drawing plugin with custom components.

```tsx
import { CodeDrawingPlugin } from '@platejs/code-drawing/react';
import { createPlateEditor } from 'platejs/react';
import { CodeDrawingElement } from '@/components/ui/code-drawing-node';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    CodeDrawingPlugin.withComponent(CodeDrawingElement),
  ],
});
```

- `withComponent`: Assigns [`CodeDrawingElement`](/docs/components/code-drawing-node) to render code drawing elements.

### Add Toolbar Button

You can add a toolbar button to insert code drawing elements. Add this item to the [Insert Toolbar Button](/docs/toolbar#insert-toolbar-button):

```tsx
{
  icon: <Code2Icon />,
  label: 'Code Drawing',
  value: KEYS.codeDrawing,
}
```

</Steps>

## Plugins

### CodeDrawingPlugin

Plugin for rendering code drawings (PlantUml, Graphviz, Flowchart, Mermaid) with inline editing and preview capabilities.

## API

### editor.tf.insert.codeDrawing

Inserts a code drawing element at the current selection.

<API name="insert.codeDrawing">
<APIParameters>
<APIItem name="props" type="NodeProps<TCodeDrawingElement>" optional>
Props for the code drawing element.
<APISubList>
<APISubListItem parent="props" name="data" type="CodeDrawingData" optional>
The data for the code drawing element.
<APISubList>
<APISubListItem parent="data" name="drawingType" type="CodeDrawingType" optional>
The type of diagram to render.

- **Default:** `'Mermaid'`

- **Options:** `'PlantUml'`, `'Graphviz'`, `'Flowchart'`, `'Mermaid'`

</APISubListItem>
<APISubListItem parent="data" name="drawingMode" type="ViewMode" optional>
The view mode for the code drawing.

- **Default:** `'Both'`

- **Options:** `'Both'`, `'Code'`, `'Image'`

</APISubListItem>
<APISubListItem parent="data" name="code" type="string" optional>
The code content for the diagram.

- **Default:** `''`

</APISubListItem>
</APISubList>
</APISubListItem>
</APISubList>
</APIItem>
<APIItem name="options" type="InsertNodesOptions" optional>
The options for inserting the code drawing node.
</APIItem>
</APIParameters>
</API>

## Transforms

### `tf.insert.codeDrawing`

Inserts a code drawing element at the current selection.

<API name="insert.codeDrawing">
<APIParameters>
<APIItem name="props" type="NodeProps<TCodeDrawingElement>" optional>
Props for the code drawing element.
</APIItem>
<APIItem name="options" type="InsertNodesOptions" optional>
The options for inserting the code drawing node.
</APIItem>
</APIParameters>
</API>

## Hooks

### `useCodeDrawingElement`

A hook for a code drawing element that handles rendering and state management.

<API name="useCodeDrawingElement">
<APIParameters>
<APIItem name="element" type="TCodeDrawingElement">
The code drawing element.
</APIItem>
</APIParameters>

<APIReturns>
<APIItem name="loading" type="boolean">
Whether the diagram is currently being rendered.
</APIItem>
<APIItem name="error" type="string | null">
The error message if rendering failed, or `null` if there's no error.
</APIItem>
<APIItem name="image" type="string">
The rendered image data URL.
</APIItem>
<APIItem name="updateNode" type="(data: Partial<CodeDrawingData>) => void">
Function to update the code drawing element's data.
</APIItem>
<APIItem name="removeNode" type="() => void">
Function to remove the code drawing element.
</APIItem>
</APIReturns>
</API>

## Types

### `TCodeDrawingElement`

The code drawing element type.

<API name="TCodeDrawingElement">
<APIAttributes>
<APIItem name="type" type="string">
The element type. Always `KEYS.codeDrawing`.
</APIItem>
<APIItem name="data" type="CodeDrawingData" optional>
The data for the code drawing element.
</APIItem>
</APIAttributes>
</API>

### `CodeDrawingData`

The data structure for code drawing elements.

<API name="CodeDrawingData">
<APIAttributes>
<APIItem name="drawingType" type="CodeDrawingType" optional>
The type of diagram to render.

- **Options:** `'PlantUml'`, `'Graphviz'`, `'Flowchart'`, `'Mermaid'`

</APIItem>
<APIItem name="drawingMode" type="ViewMode" optional>
The view mode for the code drawing.

- **Options:** `'Both'`, `'Code'`, `'Image'`

</APIItem>
<APIItem name="code" type="string" optional>
The code content for the diagram.
</APIItem>
</APIAttributes>
</API>

### `CodeDrawingType`

The type of diagram supported.

<API name="CodeDrawingType">
<APIReturns>
<APIItem type="'PlantUml' | 'Graphviz' | 'Flowchart' | 'Mermaid'">
The diagram type.
</APIItem>
</APIReturns>
</API>

### `ViewMode`

The view mode for code drawing elements.

<API name="ViewMode">
<APIReturns>
<APIItem type="'Both' | 'Code' | 'Image'">
The view mode.

- `'Both'`: Shows both code editor and preview side by side (horizontal on desktop, vertical on mobile with preview on top)
- `'Code'`: Shows only the code editor
- `'Image'`: Shows only the rendered preview

</APIItem>
</APIReturns>
</API>

## Utilities

### `renderCodeDrawing`

Renders a diagram from code based on the drawing type.

<API name="renderCodeDrawing">
<APIParameters>
<APIItem name="type" type="CodeDrawingType">
The type of diagram to render.
</APIItem>
<APIItem name="content" type="string">
The code content for the diagram.
</APIItem>
</APIParameters>

<APIReturns>
<APIItem type="Promise<string>">
A promise that resolves to the rendered image data URL.
</APIItem>
</APIReturns>
</API>

### `downloadImage`

Downloads an image from a data URL.

<API name="downloadImage">
<APIParameters>
<APIItem name="imageDataUrl" type="string">
The image data URL to download.
</APIItem>
<APIItem name="filename" type="string" optional>
The filename for the downloaded image.

- **Default:** `'code-drawing.png'`

</APIItem>
</APIParameters>
</API>


# Column

Source: https://platejs.org/docs/column

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Column
docs:
  - route: /docs/components/column-node
    title: Column Nodes
---

[column-demo registry content](https://platejs.org/r/column-demo)

<PackageInfo>

## Features

- Add columns to your document.
- Choose from a variety of column layouts using `column-group-node` toolbar.
- [ ] Resizable columns

</PackageInfo>

## Kit Usage

<Steps>

### Installation

The fastest way to add column functionality is with the `ColumnKit`, which includes pre-configured `ColumnPlugin` and `ColumnItemPlugin` with [Plate UI](/docs/installation/plate-ui) components.

[column-kit registry content](https://platejs.org/r/column-kit)

- [`ColumnGroupElement`](/docs/components/column-node): Renders column group containers.
- [`ColumnElement`](/docs/components/column-node): Renders individual column items.

### Add Kit

Add the kit to your plugins:

```tsx
import { createPlateEditor } from 'platejs/react';
import { ColumnKit } from '@/components/editor/plugins/column-kit';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    ...ColumnKit,
  ],
});
```

</Steps>

## Manual Usage

<Steps>

### Installation

```bash
npm install @platejs/layout
```

### Add Plugins

Include the column plugins in your Plate plugins array when creating the editor.

```tsx
import { ColumnPlugin, ColumnItemPlugin } from '@platejs/layout/react';
import { createPlateEditor } from 'platejs/react';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    ColumnPlugin,
    ColumnItemPlugin,
  ],
});
```

### Configure Plugins

Configure the plugins with custom components to render column layouts.

```tsx
import { ColumnPlugin, ColumnItemPlugin } from '@platejs/layout/react';
import { createPlateEditor } from 'platejs/react';
import { ColumnGroupElement, ColumnElement } from '@/components/ui/column-node';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    ColumnPlugin.withComponent(ColumnGroupElement),
    ColumnItemPlugin.withComponent(ColumnElement),
  ],
});
```

- `withComponent`: Assigns [`ColumnGroupElement`](/docs/components/column-node) to render column group containers and [`ColumnElement`](/docs/components/column-node) to render individual columns.

### Turn Into Toolbar Button

You can add this item to the [Turn Into Toolbar Button](/docs/toolbar#turn-into-toolbar-button) to convert blocks into column layouts:

```tsx
{
  icon: <Columns3Icon />,
  label: '3 columns',
  value: 'action_three_columns',
}
```

</Steps>

## Plugins

### `ColumnPlugin`

Add Column Plugin to your document.

### `ColumnItemPlugin`

Add Column Item Plugin to your document.

## Types

### `TColumnGroupElement`

Extends `TElement`.

### `TColumnElement`

Extends `TElement`.

<API name="TColumnElement">
<APIAttributes>
  <APIItem name="width" type="string" optional>
    The column's width (must end with `%`)
  </APIItem>
</APIAttributes>
</API>

## Transforms

### `insertColumnGroup`

Insert a columnGroup with two empty columns.

<API name="insertColumnGroup">
<APIOptions type="InsertNodesOptions & { columns?: number[] | number }">
    - `columns`: Array of column widths or number of equal-width columns (default: 2)
    - Other `InsertNodesOptions` to control insert behavior
  <APIItem name="columns" type="number[] | number" optional>
    Array of column widths or number of equal-width columns (default: 2)
  </APIItem>
  <APIItem name="...InsertNodesOptions" type="InsertNodesOptions">
    Other options to control insert behavior
  </APIItem>
</APIOptions>
</API>

### `insertColumn`

Insert an empty column.

<API name="insertColumn">
<APIOptions type="InsertNodesOptions & { width?: string }">
  <APIItem name="width" type="string" optional>
    Column width (default: "33%")
  </APIItem>
  <APIItem name="...InsertNodesOptions" type="InsertNodesOptions">
    Other options to control insert behavior
  </APIItem>
</APIOptions>
</API>

### `moveMiddleColumn`

Move the middle column to the left or right.

<API name="moveMiddleColumn">
<APIParameters>
  <APIItem name="nodeEntry" type="NodeEntry">
    The node entry of `column` element
  </APIItem>
  <APIItem name="options" type="{ direction: 'left' | 'right' }">
    Control the direction the middle column moves to
  </APIItem>
</APIParameters>

<APIReturns type="boolean">
  Returns `false` if the middle node is empty (and removes it), `true` otherwise.
</APIReturns>
</API>

### `toggleColumnGroup`

Convert a block into a column group layout or update an existing column group's layout.

<API name="toggleColumnGroup">
- If the target block is not a column group, wraps it in a new column group with the specified number of columns
- If the target block is already a column group, updates its column layout using `setColumns`
- The original content becomes the content of the first column
- Additional columns are created with empty paragraphs
<APIOptions type="object">
  <APIItem name="at" type="Location" optional>
    The location to toggle the column group at.
  </APIItem>
  <APIItem name="columns" type="number" optional>
    Number of equal-width columns to create (default: 2)
  </APIItem>
  <APIItem name="widths" type="string[]" optional>
    Array of column widths (e.g., ['50%', '50%']). Takes precedence over `columns`.
  </APIItem>
</APIOptions>
</API>

### `setColumns`

Update the column layout of an existing column group.

<API name="setColumns">
- When increasing columns:
  - Keeps existing column content
  - Adds new empty columns with specified widths
- When decreasing columns:
  - Merges content from removed columns into the last remaining column
  - Updates widths of remaining columns
- When keeping same number of columns:
  - Only updates column widths
<APIOptions type="object">
  <APIItem name="at" type="Path">
    The path to the column group element.
  </APIItem>
  <APIItem name="columns" type="number" optional>
    Number of equal-width columns to create.
  </APIItem>
  <APIItem name="widths" type="string[]" optional>
    Array of column widths (e.g., ['33%', '67%']). Takes precedence over `columns`.
  </APIItem>
</APIOptions>
</API>


## Hooks

### `useDebouncePopoverOpen`

<API name="useDebouncePopoverOpen">
<APIReturns type="boolean">
  Whether the popover is open.
</APIReturns>
</API>

# Date

Source: https://platejs.org/docs/date

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Date
description: Inline void date elements with canonical and raw date storage.
docs:
  - route: /docs/components/date-node
    title: Date Element
  - route: https://pro.platejs.org/docs/components/date-node
    title: Plus
---

Date adds inline void elements that display a date label inside text. Canonical dates are stored as `YYYY-MM-DD`; non-normalizable input is kept as `rawDate`. This page covers kit setup, insertion, value shape, picker behavior, Markdown serialization, and the small query API.

[date-demo registry content](https://platejs.org/r/date-demo)

<PackageInfo>

## Features

- Inline void `date` element.
- Bound `editor.tf.insert.date` transform.
- Direct `insertDate(editor, options)` helper.
- Canonical `date` storage with `rawDate` fallback.
- Calendar editing in the registry UI.
- Static renderer for read-only output.
- Markdown round-trip through `<date value="YYYY-MM-DD" />` and child-text date tags.

</PackageInfo>

## Fast Path

<Steps>

### Add The Kit

`DateKit` installs `DatePlugin` with the registry `DateElement`.

[date-kit registry content](https://platejs.org/r/date-kit)

```tsx
import { createPlateEditor } from 'platejs/react';

import { DateKit } from '@/components/editor/plugins/date-kit';

export const editor = createPlateEditor({
  plugins: DateKit,
});
```

### Render The Element

`date-node` owns the inline wrapper, display label, popover, calendar picker, and static element.

[date-node registry content](https://platejs.org/r/date-node)

### Add An Insert Action

The registry insert toolbar maps `KEYS.date` to `insertDate(editor, { select: true })`.

```tsx title="components/editor/transforms.ts"
import { insertDate } from '@platejs/date';
import { KEYS } from 'platejs';

export const insertInlineMap = {
  [KEYS.date]: (editor) => insertDate(editor, { select: true }),
};
```

</Steps>

## Ownership

| Layer | Owner | What It Does |
|-------|-------|--------------|
| `@platejs/date` | Package | Exports `BaseDatePlugin`, `insertDate`, date value helpers, and `isPointNextToNode`. |
| `@platejs/date/react` | Package | Exports `DatePlugin`. |
| `date-kit` | Registry | Adds `DatePlugin.withComponent(DateElement)`. |
| `date-base-kit` | Registry | Adds `BaseDatePlugin.withComponent(DateElementStatic)`. |
| `date-node` | Registry UI | Renders the editable popover/calendar element and static element. |
| `@platejs/markdown` | Package | Converts date MDX tags to canonical `date` or fallback `rawDate` values. |

`BaseDatePlugin` is inline and void. The text child exists only to satisfy Slate's element shape.

## Manual Setup

<Steps>

### Install Package

```bash
npm install @platejs/date
```

### Add The Plugin

Use the React plugin when the editor renders the calendar popover.

```tsx
import { DatePlugin } from '@platejs/date/react';
import { createPlateEditor } from 'platejs/react';

import { DateElement } from '@/components/ui/date-node';

export const editor = createPlateEditor({
  plugins: [DatePlugin.withComponent(DateElement)],
});
```

### Add Static Rendering

Use the base kit when rendering read-only output with `platejs/static`.

[date-base-kit registry content](https://platejs.org/r/date-base-kit)

### Insert A Date

`DatePlugin` binds `insertDate` to `editor.tf.insert.date`.

```tsx
editor.tf.insert.date({
  date: '2026-03-23',
  select: true,
});
```

Use the package helper directly when you are outside plugin-bound transform access.

```tsx
import { insertDate } from '@platejs/date';

insertDate(editor, {
  date: '2026-03-23',
  select: true,
});
```

</Steps>

## Value Shape

Canonical date values live in `date`. Invalid or intentionally loose date text lives in `rawDate`.

```tsx
const value = [
  {
    children: [
      { text: 'Due ' },
      {
        children: [{ text: '' }],
        date: '2026-03-23',
        type: 'date',
      },
      { text: '.' },
    ],
    type: 'p',
  },
];
```

| Field | Type | Notes |
|-------|------|-------|
| `type` | `'date'` | Plugin key and node type from `KEYS.date`. |
| `children` | `[{ text: '' }]` | Required Slate child for the inline void element. |
| `date` | `string` | Canonical `YYYY-MM-DD` value. |
| `rawDate` | `string` | Fallback for non-normalizable input. |

## Date Normalization

`normalizeDateValue` decides which field is written.

| Input | Stored Value |
|-------|--------------|
| `Date` object | `date: formatDateValue(value)` when the object is valid. |
| `YYYY-MM-DD` | `date` when the calendar date is valid. |
| Invalid canonical string | `rawDate`. |
| `Mon Mar 23 2026` | `date: '2026-03-23'` when JavaScript can parse it. |
| Blank string | no date fields. |
| Other text | `rawDate`. |

`getDateDisplayLabel` returns `Today`, `Yesterday`, `Tomorrow`, a localized long date, or the raw fallback string.

## Picker Behavior

The registry element is display-only while read-only. In editable mode, clicking the inline label opens a calendar popover.

| State | Behavior |
|-------|----------|
| `date` exists | The trigger shows `getDateDisplayLabel(element)`. |
| `rawDate` exists | The trigger shows the raw string. |
| no date fields | The trigger shows `Pick a date`. |
| calendar selection | The node is set to `{ date: formatDateValue(date), rawDate: undefined }`. |

The registry element uses `contentEditable={false}` on the inline wrapper, so users edit the date through the calendar instead of typing inside the void node.

## Markdown

Canonical values serialize as a self-closing date tag with a `value` attribute.

```mdx
Date: <date value="2026-03-23" />
```

Raw fallback values serialize as child text.

```mdx
Date: <date>sometime next week</date>
```

The deserializer also accepts child text such as `<date>Mon Mar 23 2026</date>` and normalizes it to `date: '2026-03-23'` when the date is safe to parse.

## API Reference

| API | Package | Use |
|-----|---------|-----|
| `BaseDatePlugin` | `@platejs/date` | Headless inline void date plugin. |
| `DatePlugin` | `@platejs/date/react` | React date plugin. |
| `insertDate(editor, options)` | `@platejs/date` | Inserts a date element plus a trailing text space. |
| `editor.tf.insert.date(options)` | plugin-bound transform | Bound transform registered by `BaseDatePlugin`. |
| `normalizeDateValue(value)` | `@platejs/date` | Returns `{ date }`, `{ rawDate }`, or an empty object. |
| `formatDateValue(date)` | `@platejs/date` | Formats a `Date` object as `YYYY-MM-DD`. |
| `parseCanonicalDateValue(value)` | `@platejs/date` | Parses only valid canonical date strings. |
| `getDateDisplayLabel(options)` | `@platejs/date` | Builds the visible date label. |
| `isPointNextToNode(editor, options)` | `@platejs/date` | Checks whether a point is adjacent to a node type. Throws when neither `options.at` nor editor selection exists. |
| `TDateElement` | `platejs` | Element shape with optional `date` and `rawDate`. |


# Equation

Source: https://platejs.org/docs/equation

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Equation
description: Block and inline LaTeX equation nodes rendered with KaTeX.
docs:
  - route: /docs/components/equation-node
    title: Equation Element
  - route: /docs/components/equation-toolbar-button
    title: Equation Toolbar Button
  - route: https://pro.platejs.org/docs/examples/equation
    title: Plus
---

Equation adds block and inline void nodes for LaTeX expressions. Both nodes store source in `texExpression` and render through KaTeX. This page covers kit setup, block versus inline ownership, insertion, input rules, Markdown serialization, and registry UI behavior.

[equation-demo registry content](https://platejs.org/r/equation-demo)

<PackageInfo>

## Features

- Block `equation` element.
- Inline void `inline_equation` element.
- Bound `editor.tf.insert.equation` and `editor.tf.insert.inlineEquation` transforms.
- Direct `insertEquation` and `insertInlineEquation` helpers.
- KaTeX rendering in editable and static UI.
- `$...$` inline input rule and `$$` block input rule.
- Markdown round-trip for inline math and block math.

</PackageInfo>

## Fast Path

<Steps>

### Add The Kit

`MathKit` installs both equation plugins, their registry components, and the default math input rules.

[math-kit registry content](https://platejs.org/r/math-kit)

```tsx
import { createPlateEditor } from 'platejs/react';

import { MathKit } from '@/components/editor/plugins/math-kit';

export const editor = createPlateEditor({
  plugins: MathKit,
});
```

### Render The Nodes

`equation-node` owns the block equation, inline equation, editable popover, textarea input, KaTeX render target, static elements, and DOCX fallback elements.

[equation-node registry content](https://platejs.org/r/equation-node)

### Add The Toolbar Button

`equation-toolbar-button` inserts an inline equation with `insertInlineEquation(editor)`.

[equation-toolbar-button registry content](https://platejs.org/r/equation-toolbar-button)

</Steps>

## Ownership

| Layer | Owner | What It Does |
|-------|-------|--------------|
| `@platejs/math` | Package | Exports base plugins, transforms, `MathRules`, and `getEquationHtml`. |
| `@platejs/math/react` | Package | Exports React plugins plus `useEquationElement` and `useEquationInput`. |
| `math-kit` | Registry | Adds block and inline React plugins with input rules and interactive UI components. |
| `math-base-kit` | Registry | Adds static equation components for read-only rendering. |
| `equation-node` | Registry UI | Renders editable, static, and DOCX equation elements. |
| `equation-toolbar-button` | Registry UI | Inserts inline equations from the toolbar. |
| `@platejs/markdown` | Package | Serializes and deserializes `math` and `inlineMath` nodes when `remark-math` is configured. |

Block and inline equations share the `TEquationElement` shape, but they are different node types with different plugin keys.

## Manual Setup

<Steps>

### Install Package

```bash
npm install @platejs/math
```

### Add Plugins

Use both React plugins when your editor supports block and inline equations.

```tsx
import { MathRules } from '@platejs/math';
import {
  EquationPlugin,
  InlineEquationPlugin,
} from '@platejs/math/react';
import { createPlateEditor } from 'platejs/react';

import {
  EquationElement,
  InlineEquationElement,
} from '@/components/ui/equation-node';

export const editor = createPlateEditor({
  plugins: [
    InlineEquationPlugin.configure({
      inputRules: [MathRules.markdown({ variant: '$' })],
      node: { component: InlineEquationElement },
    }),
    EquationPlugin.configure({
      inputRules: [MathRules.markdown({ on: 'break', variant: '$$' })],
      node: { component: EquationElement },
    }),
  ],
});
```

### Add Static Rendering

Use the base kit when rendering read-only output with `platejs/static`.

[math-base-kit registry content](https://platejs.org/r/math-base-kit)

### Insert Equations

Use plugin-bound transforms when you already have a configured editor.

```tsx
editor.tf.insert.equation({ select: true });
editor.tf.insert.inlineEquation('E = mc^2', { select: true });
```

Use package helpers directly from toolbar, slash-command, or app-local action code.

```tsx
import { insertEquation, insertInlineEquation } from '@platejs/math';

insertEquation(editor, { select: true });
insertInlineEquation(editor, 'E = mc^2', { select: true });
```

</Steps>

## Value Shape

Both equation nodes store source in `texExpression`. The child text is only the Slate-required child for a void element.

```tsx
const value = [
  {
    children: [
      { text: 'Mass-energy equivalence: ' },
      {
        children: [{ text: '' }],
        texExpression: 'E = mc^2',
        type: 'inline_equation',
      },
      { text: '.' },
    ],
    type: 'p',
  },
  {
    children: [{ text: '' }],
    texExpression: '\\\\int_{a}^{b} f(x) \\\\, dx = F(b) - F(a)',
    type: 'equation',
  },
];
```

| Node | Type | Behavior |
|------|------|----------|
| `BaseEquationPlugin` | `equation` | Block void equation. |
| `BaseInlineEquationPlugin` | `inline_equation` | Inline void equation. |
| `TEquationElement.texExpression` | `string` | LaTeX source rendered by KaTeX. |

## Input Rules

`MathRules.markdown` creates editor input rules. It is separate from Markdown serialization.

| Rule | Trigger | Behavior |
|------|---------|----------|
| `MathRules.markdown({ variant: '$' })` | `$...$` | Deletes the delimited text and inserts an inline equation with the matched expression. |
| `MathRules.markdown({ on: 'break', variant: '$$' })` | `$$` then line break | Replaces the paragraph fence with a block equation. |
| `MathRules.markdown({ on: 'match', variant: '$$' })` | `$$...$$` match | Creates a block equation on match. |

Math input rules are disabled inside code blocks, block equations, and inline equations.

## Rendering

The registry components render KaTeX and keep source editing in a popover.

| Surface | Behavior |
|---------|----------|
| Editable block equation | `useEquationElement` calls `katex.render` with display-mode options. |
| Editable inline equation | Opens a popover when the inline void node is selected and the selection is collapsed. |
| Popover input | `useEquationInput` writes `texExpression` as the textarea changes. |
| `Enter` | Submits and closes the input. |
| `Escape` | Dismisses; inline equations restore the initial expression. |
| Inline left/right edge arrows | Move selection out of the inline equation. |
| Static rendering | `getEquationHtml` calls `katex.renderToString`. |

KaTeX is configured with `throwOnError: false`, `strict: 'warn'`, and `trust: false` in the registry UI.

## Markdown

Markdown math support comes from `@platejs/markdown` plus `remark-math`, as configured by the registry `MarkdownKit`.

```mdx
Inline $x+1$ math
```

```mdx
$$
x+1
$$
```

Inline math deserializes to `inline_equation`. Block math deserializes to `equation`. Serialization writes the same Markdown math shapes from `texExpression`.

## Plate Plus

[equation-pro registry content](https://platejs.org/r/equation-pro)

## API Reference

| API | Package | Use |
|-----|---------|-----|
| `BaseEquationPlugin` | `@platejs/math` | Headless block equation plugin. |
| `BaseInlineEquationPlugin` | `@platejs/math` | Headless inline equation plugin. |
| `EquationPlugin` | `@platejs/math/react` | React block equation plugin. |
| `InlineEquationPlugin` | `@platejs/math/react` | React inline equation plugin. |
| `insertEquation(editor, options)` | `@platejs/math` | Inserts a blank block equation. |
| `insertInlineEquation(editor, texExpression?, options?)` | `@platejs/math` | Inserts an inline equation. Defaults to the selected string when no expression is passed. |
| `editor.tf.insert.equation(options)` | plugin-bound transform | Bound block equation insert transform. |
| `editor.tf.insert.inlineEquation(texExpression?, options?)` | plugin-bound transform | Bound inline equation insert transform. |
| `MathRules.markdown(options)` | `@platejs/math` | Creates inline or block math input rules. |
| `useEquationElement(options)` | `@platejs/math/react` | Renders an equation into a KaTeX DOM target. |
| `useEquationInput(options)` | `@platejs/math/react` | Wires the equation textarea and keyboard behavior. |
| `getEquationHtml(options)` | `@platejs/math` | Returns static KaTeX HTML. |
| `TEquationElement` | `platejs` | Element shape with `texExpression`. |


# Excalidraw

Source: https://platejs.org/docs/excalidraw

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Excalidraw
description: Void Excalidraw drawing blocks stored inside Plate values.
docs:
  - route: /docs/components/excalidraw-node
    title: Excalidraw Element
---

Excalidraw adds a void `excalidraw` element that embeds the Excalidraw canvas in the editor. The node stores Excalidraw `elements` and `state` under `data`. This page covers kit setup, insertion, persistence shape, and the client-only registry UI.

[excalidraw-demo registry content](https://platejs.org/r/excalidraw-demo)

<PackageInfo>

## Features

- Void `excalidraw` block element.
- Direct `insertExcalidraw(editor, props, options)` helper.
- Excalidraw `elements` and app `state` stored on the node.
- Dynamic Excalidraw component loading in the React hook.
- Change deduplication before writing canvas data back to Slate.
- Read-only mode through Excalidraw `viewModeEnabled`.

</PackageInfo>

## Fast Path

<Steps>

### Add The Kit

`ExcalidrawKit` installs `ExcalidrawPlugin` with the registry `ExcalidrawElement`.

[excalidraw-kit registry content](https://platejs.org/r/excalidraw-kit)

```tsx
import { createPlateEditor } from 'platejs/react';

import { ExcalidrawKit } from '@/components/editor/plugins/excalidraw-kit';

export const editor = createPlateEditor({
  plugins: ExcalidrawKit,
});
```

### Render The Element

`excalidraw-node` owns the client component, Excalidraw CSS import, fixed canvas frame, and read-only view mode.

[excalidraw-node registry content](https://platejs.org/r/excalidraw-node)

### Add An Insert Action

The registry insert toolbar maps `KEYS.excalidraw` to `insertExcalidraw(editor, {}, { select: true })`.

```tsx title="components/editor/transforms.ts"
import { insertExcalidraw } from '@platejs/excalidraw';
import { KEYS } from 'platejs';

export const insertBlockMap = {
  [KEYS.excalidraw]: (editor) =>
    insertExcalidraw(editor, {}, { select: true }),
};
```

</Steps>

## Ownership

| Layer | Owner | What It Does |
|-------|-------|--------------|
| `@platejs/excalidraw` | Package | Exports `BaseExcalidrawPlugin`, `TExcalidrawElement`, `ExcalidrawDataState`, and `insertExcalidraw`. |
| `@platejs/excalidraw/react` | Package | Exports `ExcalidrawPlugin`, `useExcalidrawElement`, and React Excalidraw prop types. |
| `excalidraw-kit` | Registry | Adds `ExcalidrawPlugin.withComponent(ExcalidrawElement)`. |
| `excalidraw-node` | Registry UI | Dynamically renders `@excalidraw/excalidraw` inside a Plate element. |
| App persistence | App code | Stores the Plate value that contains Excalidraw element data. |

`ExcalidrawPlugin` does not bind an `editor.tf.insert.excalidraw` transform. Use `insertExcalidraw` directly.

## Manual Setup

<Steps>

### Install Package

```bash
npm install @platejs/excalidraw
```

### Add The Plugin

Use the React plugin when the editor renders the Excalidraw canvas.

```tsx
import { ExcalidrawPlugin } from '@platejs/excalidraw/react';
import { createPlateEditor } from 'platejs/react';

import { ExcalidrawElement } from '@/components/ui/excalidraw-node';

export const editor = createPlateEditor({
  plugins: [ExcalidrawPlugin.withComponent(ExcalidrawElement)],
});
```

### Insert A Drawing

`insertExcalidraw` inserts after the current selection parent with `nextBlock: true`. If the editor has no selection or no selection parent, it returns without inserting.

```tsx
import { insertExcalidraw } from '@platejs/excalidraw';

insertExcalidraw(
  editor,
  {
    data: {
      elements: [],
      state: {
        viewBackgroundColor: '#ffffff',
      },
    },
  },
  { select: true }
);
```

</Steps>

## Value Shape

`TExcalidrawElement` is a void element. The drawing payload lives in `data`, not in text children.

```tsx
const value = [
  {
    children: [{ text: '' }],
    data: {
      elements: [
        {
          id: 'shape-1',
          type: 'rectangle',
          x: 100,
          y: 100,
        },
      ],
      state: {
        viewBackgroundColor: '#ffffff',
      },
    },
    type: 'excalidraw',
  },
];
```

| Field | Type | Notes |
|-------|------|-------|
| `type` | `'excalidraw'` | Plugin key and node type from `KEYS.excalidraw`. |
| `children` | `[{ text: '' }]` | Required Slate child for the void element. |
| `data.elements` | Excalidraw elements | Stored as partial Excalidraw elements. |
| `data.state` | Excalidraw app state | Stored as imported Excalidraw app state. |

Markdown serialization is not owned by `@platejs/excalidraw`. Persist the Plate value when you need to keep drawings.

## UI Behavior

`useExcalidrawElement` bridges the Plate node and the Excalidraw React component.

| Surface | Behavior |
|---------|----------|
| Component loading | Dynamically imports `@excalidraw/excalidraw` and returns the loaded component. |
| Initial data | Deep-clones `element.data.state`, `element.data.elements`, `libraryItems`, and `scrollToContent`. |
| Editing | `onChange` writes `{ elements, state }` back to the node. |
| Deduplication | Uses deep equality to skip writes when canvas data did not change. |
| Read-only mode | Removes the write handler and enables Excalidraw `viewModeEnabled`. |
| Canvas frame | Registry UI renders a bordered `aspect-video` frame capped at `600px`. |

The registry element imports `@excalidraw/excalidraw/index.css`, so custom copies need the same stylesheet.

## API Reference

| API | Package | Use |
|-----|---------|-----|
| `BaseExcalidrawPlugin` | `@platejs/excalidraw` | Headless void element plugin. |
| `ExcalidrawPlugin` | `@platejs/excalidraw/react` | React Excalidraw plugin. |
| `insertExcalidraw(editor, props?, options?)` | `@platejs/excalidraw` | Inserts a void Excalidraw node after the current selection parent. |
| `useExcalidrawElement(options)` | `@platejs/excalidraw/react` | Returns the dynamically loaded `Excalidraw` component and props for the registry element. |
| `TExcalidrawElement` | `@platejs/excalidraw` | Element shape with optional `data`. |
| `ExcalidrawDataState` | `@platejs/excalidraw` | Data shape for stored Excalidraw elements and app state. |


# Footnote

Source: https://platejs.org/docs/footnote

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Footnote
docs:
  - route: /docs/markdown
    title: Markdown
  - route: /docs/navigation-feedback
    title: Navigation Feedback
---

[footnote-demo registry content](https://platejs.org/r/footnote-demo)

Footnote turns GFM footnote markup (`[^1]` references and `[^1]: text` definitions) into dedicated Plate nodes you can insert, repair, and jump between. The reference is an inline void `<sup>`; the definition is a block at the end of the document. Paired with `MarkdownPlugin` and `remark-gfm`, references and definitions round-trip as real footnote markdown instead of fallback text.

<PackageInfo>

## Features

- GFM-compatible footnote references and definitions as dedicated Plate nodes.
- One-transform insertion with automatic numeric identifier allocation.
- `[^` inline combobox for insertion from the default UI kit.
- Recreate a missing definition from an unresolved reference without duplicating.
- Keep the first duplicate definition canonical; renumber later duplicates on demand.
- Navigation helpers that jump between reference and definition with a landed-target flash.

</PackageInfo>

## Kit Usage

<Steps>

### Installation

The fastest way to add footnote-aware markdown is with the `MarkdownKit`, which includes `MarkdownPlugin`, the footnote plugins wired for the default markdown profile, and works with [Plate UI](/docs/installation/plate-ui).

[markdown-kit registry content](https://platejs.org/r/markdown-kit)

### Add Kit

```tsx
import { createPlateEditor } from 'platejs/react';
import { MarkdownKit } from '@/components/editor/plugins/markdown-kit';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    ...MarkdownKit,
  ],
});
```

</Steps>

## Manual Usage

<Steps>

### Installation

```bash
npm install @platejs/footnote @platejs/markdown remark-gfm
```

### Add Plugins

Three plugins ship together: the inline reference, the block definition, and the combobox input. Pair them with `MarkdownPlugin` and `remark-gfm` so `[^1]` round-trips correctly.

```tsx
import {
  FootnoteDefinitionPlugin,
  FootnoteReferencePlugin,
} from '@platejs/footnote/react';
import { MarkdownPlugin } from '@platejs/markdown';
import { createPlateEditor } from 'platejs/react';
import remarkGfm from 'remark-gfm';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    FootnoteReferencePlugin,
    FootnoteDefinitionPlugin,
    MarkdownPlugin.configure({
      options: {
        remarkPlugins: [remarkGfm],
      },
    }),
  ],
});
```

`FootnoteReferencePlugin` pulls in `FootnoteInputPlugin` automatically — that's the inline void rendered while the reader is typing inside the `[^` combobox.

### Insert a Footnote

Call `tf.insert.footnote` at the current selection. It inserts the reference, creates a matching definition at the end of the document, and moves the caret into the definition body so the reader can start writing:

```tsx
editor.tf.insert.footnote();
```

When the selection is expanded, the expanded fragment seeds the definition body so you can select text and "footnote-ify" it in one shot.

Pass `focusDefinition: false` when the reference should stay inline (for example, inside a larger template):

```tsx
editor.tf.insert.footnote({ focusDefinition: false });
```

Pass `identifier` to reuse an existing identifier; the transform skips creating a duplicate definition when one already exists.

### Repair an Unresolved Reference

When a reference points at an identifier with no definition (e.g. pasted from elsewhere), use `tf.footnote.createDefinition` to create just the definition — without inserting another reference:

```tsx
editor.tf.footnote.createDefinition({ identifier: '3' });
```

Pass `focus: false` when you want to leave the caret where it was:

```tsx
editor.tf.footnote.createDefinition({ focus: false, identifier: '3' });
```

### Navigate Between Reference and Definition

`tf.footnote.focusDefinition` and `tf.footnote.focusReference` jump the selection, scroll the target into view, and flash it through [Navigation Feedback](/docs/navigation-feedback). No extra wiring needed:

```tsx
editor.tf.footnote.focusDefinition({ identifier: '3' });
editor.tf.footnote.focusReference({ identifier: '3' });
```

When a single definition is pointed at by multiple references, pass `index` to pick which one to land on:

```tsx
editor.tf.footnote.focusReference({ identifier: '3', index: 1 });
```

Both transforms return `false` when the identifier doesn't resolve, so you can branch on stale links without throwing.

### Handle Duplicate Definitions

Two definitions with the same identifier is a resolvable edit state, not an error. The **first** definition in document order stays canonical; later ones are flagged as duplicates. Renumber a later duplicate with:

```tsx
const nextIdentifier = editor.tf.footnote.normalizeDuplicateDefinition({
  path: duplicatePath,
});
```

The transform returns the newly assigned identifier string on success, or `false` when the path isn't a duplicate definition or the requested identifier is already taken. Pass `identifier` to target a specific free identifier instead of the next available one.

### Customize Rendering

Swap in your own React components with `withComponent`:

```tsx
import {
  FootnoteDefinitionPlugin,
  FootnoteReferencePlugin,
} from '@platejs/footnote/react';
import { createPlateEditor } from 'platejs/react';

const editor = createPlateEditor({
  plugins: [
    FootnoteReferencePlugin.withComponent(MyFootnoteReference),
    FootnoteDefinitionPlugin.withComponent(MyFootnoteDefinition),
  ],
});
```

The package owns node semantics, identifier allocation, and navigation helpers. App-level surfaces — hover previews, the `[^` combobox, slash-command entries, toolbar buttons — are built on top of the transforms and API methods below.

</Steps>

## Plugins

### `FootnoteReferencePlugin`

Inline void node rendered as `<sup>`. Owns the `[^` combobox trigger, identifier registry, navigation transforms, and query API. Automatically includes `FootnoteInputPlugin`.

<API name="FootnoteReferencePlugin">
<APIOptions>
  <APIItem name="trigger" type="RegExp | string[] | string" optional>
    Character that opens the footnote combobox.
    - **Default:** `'^'`
  </APIItem>
  <APIItem name="triggerPreviousCharPattern" type="RegExp" optional>
    Only trigger when the previous character matches. The default requires `[` so bare `^` in prose doesn't open the combobox.
    - **Default:** `/^\[$/`
  </APIItem>
  <APIItem name="createComboboxInput" type="(trigger: string) => TElement" optional>
    Factory for the node inserted when the combobox opens. Defaults to a `footnoteInput` element.
  </APIItem>
  <APIItem name="triggerQuery" type="(editor: SlateEditor) => boolean" optional>
    Extra predicate gating the combobox. Return `false` to suppress triggering at the current selection.
  </APIItem>
</APIOptions>
</API>

### `FootnoteDefinitionPlugin`

Block node for footnote definitions. Lives at the bottom of the document and carries the identifier + body content.

<API name="FootnoteDefinitionPlugin" />

### `FootnoteInputPlugin`

Inline void used as the live combobox input while the reader is typing `[^…`. Pulled in automatically by `FootnoteReferencePlugin`; add it directly only if you render the combobox yourself.

<API name="FootnoteInputPlugin" />

## API

All API methods hang off `editor.api.footnote`. Reads go through a lazy per-editor registry that rebuilds only when a footnote operation invalidates it, so hover previews and navigation stay cheap even when a single definition has many references.

### `api.footnote.definition`

Get the canonical (first-in-document-order) definition entry for an identifier.

<API name="definition">
<APIParameters>
  <APIItem name="identifier" type="string">
    Footnote identifier.
  </APIItem>
</APIParameters>
<APIReturns>
  <APIItem name="return" type="NodeEntry<TElement> | undefined">
    Canonical definition entry, or `undefined` when nothing matches.
  </APIItem>
</APIReturns>
</API>

### `api.footnote.definitions`

Get every definition entry that shares an identifier, in document order. When duplicates exist, the first entry is canonical; later entries are duplicates.

<API name="definitions">
<APIParameters>
  <APIItem name="identifier" type="string">
    Footnote identifier.
  </APIItem>
</APIParameters>
<APIReturns>
  <APIItem name="return" type="NodeEntry<TElement>[]">
    Definition entries in document order.
  </APIItem>
</APIReturns>
</API>

### `api.footnote.definitionText`

Get the plain-text content of the canonical definition. Ideal for hover previews — reads straight from live definition nodes, no copied state.

<API name="definitionText">
<APIParameters>
  <APIItem name="identifier" type="string">
    Footnote identifier.
  </APIItem>
</APIParameters>
<APIReturns>
  <APIItem name="return" type="string | undefined">
    Definition text, or `undefined` when no definition exists.
  </APIItem>
</APIReturns>
</API>

### `api.footnote.references`

Get every reference entry that points at an identifier, in document order.

<API name="references">
<APIParameters>
  <APIItem name="identifier" type="string">
    Footnote identifier.
  </APIItem>
</APIParameters>
<APIReturns>
  <APIItem name="return" type="NodeEntry<TElement>[]">
    Reference entries in document order.
  </APIItem>
</APIReturns>
</API>

### `api.footnote.identifiers`

List every identifier that has at least one definition, in document order.

<API name="identifiers">
<APIReturns>
  <APIItem name="return" type="string[]">
    Defined identifiers.
  </APIItem>
</APIReturns>
</API>

### `api.footnote.nextId`

Compute the next free numeric identifier. Used by `tf.insert.footnote` when the caller doesn't supply one.

<API name="nextId">
<APIReturns>
  <APIItem name="return" type="string">
    Next free identifier (e.g. `'1'`, `'2'`).
  </APIItem>
</APIReturns>
</API>

### `api.footnote.isResolved`

Check whether an identifier has at least one definition.

<API name="isResolved">
<APIParameters>
  <APIItem name="identifier" type="string">
    Footnote identifier.
  </APIItem>
</APIParameters>
<APIReturns>
  <APIItem name="return" type="boolean">
    `true` when at least one definition exists for the identifier.
  </APIItem>
</APIReturns>
</API>

### `api.footnote.duplicateDefinitions`

Get every non-canonical definition entry for an identifier — that is, every definition after the first in document order.

<API name="duplicateDefinitions">
<APIParameters>
  <APIItem name="identifier" type="string">
    Footnote identifier.
  </APIItem>
</APIParameters>
<APIReturns>
  <APIItem name="return" type="NodeEntry<TElement>[]">
    Definition entries past the canonical one.
  </APIItem>
</APIReturns>
</API>

### `api.footnote.duplicateIdentifiers`

List every identifier that has more than one definition.

<API name="duplicateIdentifiers">
<APIReturns>
  <APIItem name="return" type="string[]">
    Identifiers with duplicate definitions.
  </APIItem>
</APIReturns>
</API>

### `api.footnote.hasDuplicateDefinitions`

Check whether an identifier has more than one definition.

<API name="hasDuplicateDefinitions">
<APIParameters>
  <APIItem name="identifier" type="string">
    Footnote identifier.
  </APIItem>
</APIParameters>
<APIReturns>
  <APIItem name="return" type="boolean">
    `true` when two or more definitions share the identifier.
  </APIItem>
</APIReturns>
</API>

### `api.footnote.isDuplicateDefinition`

Check whether a given definition path is a later duplicate (not the canonical one).

<API name="isDuplicateDefinition">
<APIParameters>
  <APIItem name="path" type="number[]">
    Path of the definition to check.
  </APIItem>
</APIParameters>
<APIReturns>
  <APIItem name="return" type="boolean">
    `true` when the node at `path` is a footnote definition past the canonical one.
  </APIItem>
</APIReturns>
</API>

## Transforms

### `tf.insert.footnote`

Insert a footnote reference at the current selection, create a matching definition if one doesn't already exist, and focus the definition body.

When the selection is expanded, the expanded fragment seeds the new definition body so you can convert selected prose into a footnote in one call.

<API name="insert.footnote">
<APIParameters>
  <APIItem name="identifier" type="string" optional>
    Reuse an existing identifier. Defaults to `api.footnote.nextId()`.
  </APIItem>
  <APIItem name="focusDefinition" type="boolean" optional>
    Focus the definition body after insertion. Pass `false` to keep the caret inline after the reference.
    - **Default:** `true`
  </APIItem>
  <APIItem name="...options" type="InsertNodesOptions" optional>
    Standard insert-nodes options (`at`, `select`, etc.) forwarded to the reference insert.
  </APIItem>
</APIParameters>
</API>

### `tf.footnote.createDefinition`

Create the missing definition for an existing identifier without inserting another reference. Returns the path of the definition — the newly created one, or the existing one when the identifier already resolves.

<API name="footnote.createDefinition">
<APIParameters>
  <APIItem name="identifier" type="string">
    Identifier to create a definition for.
  </APIItem>
  <APIItem name="focus" type="boolean" optional>
    Focus the definition body after creation.
    - **Default:** `true`
  </APIItem>
</APIParameters>
<APIReturns>
  <APIItem name="return" type="number[]">
    Path of the resolved definition.
  </APIItem>
</APIReturns>
</API>

### `tf.footnote.focusDefinition`

Jump the selection into the canonical definition body, scroll it into view, and flash it through Navigation Feedback.

<API name="footnote.focusDefinition">
<APIParameters>
  <APIItem name="identifier" type="string">
    Footnote identifier.
  </APIItem>
</APIParameters>
<APIReturns>
  <APIItem name="return" type="boolean">
    `false` when no definition resolves, `true` otherwise.
  </APIItem>
</APIReturns>
</API>

### `tf.footnote.focusReference`

Jump the selection to the matching reference, scroll it into view, and flash it through Navigation Feedback.

<API name="footnote.focusReference">
<APIParameters>
  <APIItem name="identifier" type="string">
    Footnote identifier.
  </APIItem>
  <APIItem name="index" type="number" optional>
    Pick a specific reference when the definition is pointed at by several. Indexed by document order.
    - **Default:** `0`
  </APIItem>
</APIParameters>
<APIReturns>
  <APIItem name="return" type="boolean">
    `false` when the reference doesn't resolve, `true` otherwise.
  </APIItem>
</APIReturns>
</API>

### `tf.footnote.normalizeDuplicateDefinition`

Renumber a later duplicate definition so the canonical definition stays intact. Pass the path of the duplicate; optionally pass a specific `identifier` to target, otherwise the transform picks `api.footnote.nextId()`.

<API name="footnote.normalizeDuplicateDefinition">
<APIParameters>
  <APIItem name="path" type="number[]">
    Path of the duplicate definition to renumber.
  </APIItem>
  <APIItem name="identifier" type="string" optional>
    Target identifier. Must be free. Defaults to `api.footnote.nextId()`.
  </APIItem>
</APIParameters>
<APIReturns>
  <APIItem name="return" type="false | string">
    The assigned identifier on success, or `false` when the path isn't a duplicate definition or the target identifier is already taken.
  </APIItem>
</APIReturns>
</API>

## Related Docs

- [Markdown](/docs/markdown)
- [Navigation Feedback](/docs/navigation-feedback)
- [Editor Methods](/docs/editor-methods)


# Heading

Source: https://platejs.org/docs/heading

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Heading
description: H1 through H6 block elements with shortcuts, input rules, and static renderers.
docs:
  - route: /docs/components/heading-node
    title: Heading Element
  - route: /docs/basic-blocks
    title: Basic Blocks
  - route: https://pro.platejs.org/docs/components/heading-node
    title: Plus
---

Heading adds six block element types, `h1` through `h6`, for document structure. Each level is its own plugin with the same block behavior, HTML parser, toggle transform, and optional Markdown shorthand rule. This page covers registry setup, manual setup, value shape, shortcuts, input rules, and Markdown serialization.

[basic-blocks-demo registry content](https://platejs.org/r/basic-blocks-demo)

<PackageInfo>

## Features

- Block `h1` through `h6` elements.
- Individual `H1Plugin` through `H6Plugin` exports.
- Grouping `HeadingPlugin` and `BaseHeadingPlugin` with configurable levels.
- Bound `editor.tf.h1.toggle()` through `editor.tf.h6.toggle()` transforms.
- `# ` through `###### ` input rules with `HeadingRules.markdown()`.
- `mod+alt+1` through `mod+alt+6` shortcuts in the registry kit.
- Editable and static registry heading components.

</PackageInfo>

## Fast Path

<Steps>

### Add Basic Blocks

`BasicBlocksKit` installs paragraph, H1-H6, blockquote, and horizontal rule plugins with Plate UI components. For headings, it configures every level with `HeadingRules.markdown()`, `H*Element`, a reset-on-empty break rule, and `mod+alt+<level>` shortcuts.

[basic-blocks-kit registry content](https://platejs.org/r/basic-blocks-kit)

```tsx
import { createPlateEditor } from 'platejs/react';

import { BasicBlocksKit } from '@/components/editor/plugins/basic-blocks-kit';

export const editor = createPlateEditor({
  plugins: BasicBlocksKit,
});
```

### Render Headings

`heading-node` exports `H1Element` through `H6Element`. Each component renders a `PlateElement` with the matching heading tag and navigation-highlight styles.

[heading-node registry content](https://platejs.org/r/heading-node)

### Add Static Rendering

Use `BaseBasicBlocksKit` when rendering read-only content with `platejs/static`.

[basic-blocks-base-kit registry content](https://platejs.org/r/basic-blocks-base-kit)

</Steps>

## Ownership

| Layer | Owner | What It Does |
|-------|-------|--------------|
| `@platejs/basic-nodes` | Package | Exports base H1-H6 plugins, `BaseHeadingPlugin`, `HeadingRules`, and shared heading rules. |
| `@platejs/basic-nodes/react` | Package | Exports `H1Plugin` through `H6Plugin`, plus the grouping `HeadingPlugin`. |
| `basic-blocks-kit` | Registry | Adds H1-H6 React plugins with components, input rules, shortcuts, and reset-on-empty break behavior. |
| `basic-blocks-base-kit` | Registry | Adds static H1-H6 components for server/static rendering. |
| `heading-node` | Registry UI | Renders editable and static heading components. |
| Toolbar and slash UI | Registry UI | Provides H1-H6 turn-into items, H1-H3 insert items, and H1-H3 slash-command items. |
| `@platejs/markdown` | Package | Serializes and deserializes `h1` through `h6` as Markdown headings. |

`BasicBlocksPlugin` and `BaseBasicBlocksPlugin` are package grouping plugins. They do not install registry UI components; use the registry kits when you want the Plate UI heading styles.

## Manual Setup

<Steps>

### Install Package

```bash
npm install @platejs/basic-nodes
```

### Add Individual Levels

Use individual level plugins when you want registry components, shortcuts, or per-level configuration.

```tsx
import { HeadingRules } from '@platejs/basic-nodes';
import {
  H1Plugin,
  H2Plugin,
  H3Plugin,
  H4Plugin,
  H5Plugin,
  H6Plugin,
} from '@platejs/basic-nodes/react';
import { createPlateEditor } from 'platejs/react';

import {
  H1Element,
  H2Element,
  H3Element,
  H4Element,
  H5Element,
  H6Element,
} from '@/components/ui/heading-node';

export const editor = createPlateEditor({
  plugins: [
    H1Plugin.configure({
      inputRules: [HeadingRules.markdown()],
      node: { component: H1Element },
      rules: { break: { empty: 'reset' } },
      shortcuts: { toggle: { keys: 'mod+alt+1' } },
    }),
    H2Plugin.configure({
      inputRules: [HeadingRules.markdown()],
      node: { component: H2Element },
      rules: { break: { empty: 'reset' } },
      shortcuts: { toggle: { keys: 'mod+alt+2' } },
    }),
    H3Plugin.configure({
      inputRules: [HeadingRules.markdown()],
      node: { component: H3Element },
      rules: { break: { empty: 'reset' } },
      shortcuts: { toggle: { keys: 'mod+alt+3' } },
    }),
    H4Plugin.configure({
      inputRules: [HeadingRules.markdown()],
      node: { component: H4Element },
      rules: { break: { empty: 'reset' } },
      shortcuts: { toggle: { keys: 'mod+alt+4' } },
    }),
    H5Plugin.configure({
      inputRules: [HeadingRules.markdown()],
      node: { component: H5Element },
      rules: { break: { empty: 'reset' } },
      shortcuts: { toggle: { keys: 'mod+alt+5' } },
    }),
    H6Plugin.configure({
      inputRules: [HeadingRules.markdown()],
      node: { component: H6Element },
      rules: { break: { empty: 'reset' } },
      shortcuts: { toggle: { keys: 'mod+alt+6' } },
    }),
  ],
});
```

### Use A Headless Group

Use `BaseHeadingPlugin` when you want to install several heading levels without configuring each level by hand.

```tsx
import { BaseHeadingPlugin } from '@platejs/basic-nodes';
import { createSlateEditor } from 'platejs';

export const editor = createSlateEditor({
  plugins: [
    BaseHeadingPlugin.configure({
      options: {
        levels: [1, 2, 3],
      },
    }),
  ],
});
```

</Steps>

## Value Shape

Headings are normal block elements. The heading level is the node `type`.

```tsx
const value = [
  {
    children: [{ text: 'Installation' }],
    type: 'h1',
  },
  {
    children: [{ text: 'Install packages' }],
    type: 'h2',
  },
  {
    children: [{ text: 'Configure editor plugins' }],
    type: 'h3',
  },
];
```

| Type | HTML Parser | Default Render Tag |
|------|-------------|--------------------|
| `h1` | `H1` | `<h1>` |
| `h2` | `H2` | `<h2>` |
| `h3` | `H3` | `<h3>` |
| `h4` | `H4` | `<h4>` |
| `h5` | `H5` | `<h5>` |
| `h6` | `H6` | `<h6>` |

`BaseHeadingPlugin.configure({ options: { levels: 3 } })` creates H1 through H3. Passing an array such as `[1, 3, 5]` creates only those levels.

## Editing Behavior

All heading levels share the same base behavior.

| Behavior | Source |
|----------|--------|
| Toggle transform | Each base plugin binds `editor.tf.<level>.toggle()` to `editor.tf.toggleBlock(type)`. |
| Enter split | Base rules set `break.splitReset: true`; the registry kit also resets an empty heading on break. |
| Backspace at start | Base rules set `delete.start: 'reset'`. |
| Empty merge | Base rules set `merge.removeEmpty: true`. |
| HTML paste | Each level deserializes its matching `H1` through `H6` tag. |

## Input Rules And Shortcuts

`HeadingRules.markdown()` creates a block-start input rule for the configured plugin key.

| Input | Result |
|-------|--------|
| `# ` | H1 |
| `## ` | H2 |
| `### ` | H3 |
| `#### ` | H4 |
| `##### ` | H5 |
| `###### ` | H6 |

The registry kit also binds `mod+alt+1` through `mod+alt+6` to the matching toggle transform.

## Registry UI

| Surface | Heading Levels |
|---------|----------------|
| Turn Into toolbar | H1-H6 |
| Insert toolbar | H1-H3 |
| Slash command | H1-H3 |
| Editable element | `H1Element` through `H6Element` |
| Static element | `H1ElementStatic` through `H6ElementStatic` |

Static heading elements preserve an `id` field by rendering an internal anchor span. That anchor is used by DOCX table-of-contents links.

## Markdown

`@platejs/markdown` maps Markdown heading depth to the matching Plate heading type.

```mdx
# H1
## H2
### H3
```

Serialization uses the node type to choose Markdown depth. For example, `type: 'h2'` serializes as `##`.

## API Reference

| API | Package | Use |
|-----|---------|-----|
| `BaseH1Plugin` through `BaseH6Plugin` | `@platejs/basic-nodes` | Headless heading level plugins. |
| `BaseHeadingPlugin` | `@platejs/basic-nodes` | Grouping plugin that creates nested heading levels from `options.levels`. |
| `HeadingRules.markdown()` | `@platejs/basic-nodes` | Creates the `# ` through `###### ` block-start input rules. |
| `H1Plugin` through `H6Plugin` | `@platejs/basic-nodes/react` | React heading level plugins. |
| `HeadingPlugin` | `@platejs/basic-nodes/react` | React grouping plugin for heading levels. |
| `editor.tf.h1.toggle()` through `editor.tf.h6.toggle()` | plugin-bound transforms | Toggle selected blocks to the matching heading level. |


# Horizontal Rule

Source: https://platejs.org/docs/horizontal-rule

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Horizontal Rule
description: Void divider blocks rendered as horizontal rules.
docs:
  - route: /docs/components/hr-node
    title: Horizontal Rule Element
  - route: /docs/basic-blocks
    title: Basic Blocks
  - route: https://pro.platejs.org/docs/components/hr-node
    title: Plus
---

Horizontal Rule adds a void `hr` block for separating sections. The package owns the element type, HTML parser, default `<hr>` render tag, and Markdown-style input rules. The registry kit adds the Plate UI divider component, static renderer, and insert toolbar item.

[basic-blocks-demo registry content](https://platejs.org/r/basic-blocks-demo)

<PackageInfo>

## Features

- Void block `hr` element.
- HTML deserialization from `<hr>`.
- Default render tag of `<hr>`.
- `---` and `___ ` input rules through `HorizontalRuleRules.markdown()`.
- Editable and static registry divider components.
- Insert toolbar item labeled `Divider`.

</PackageInfo>

## Fast Path

<Steps>

### Add Basic Blocks

`BasicBlocksKit` installs `HorizontalRulePlugin` with the registry `HrElement` and both default input rules.

[basic-blocks-kit registry content](https://platejs.org/r/basic-blocks-kit)

```tsx
import { createPlateEditor } from 'platejs/react';

import { BasicBlocksKit } from '@/components/editor/plugins/basic-blocks-kit';

export const editor = createPlateEditor({
  plugins: BasicBlocksKit,
});
```

### Render The Divider

`hr-node` renders the editable divider with selected/focused ring styles and a static companion component.

[hr-node registry content](https://platejs.org/r/hr-node)

### Add Static Rendering

Use `BaseBasicBlocksKit` when rendering read-only content with `platejs/static`.

[basic-blocks-base-kit registry content](https://platejs.org/r/basic-blocks-base-kit)

</Steps>

## Ownership

| Layer | Owner | What It Does |
|-------|-------|--------------|
| `@platejs/basic-nodes` | Package | Exports `BaseHorizontalRulePlugin` and `HorizontalRuleRules`. |
| `@platejs/basic-nodes/react` | Package | Exports `HorizontalRulePlugin`. |
| `basic-blocks-kit` | Registry | Adds `HorizontalRulePlugin` with dash and underscore input rules plus `HrElement`. |
| `basic-blocks-base-kit` | Registry | Adds `BaseHorizontalRulePlugin.withComponent(HrElementStatic)`. |
| `hr-node` | Registry UI | Renders editable and static divider components. |
| Insert toolbar | Registry UI | Inserts `KEYS.hr` through the generic `insertBlock` path. |

There is no package-specific `insertHorizontalRule` helper. App UI usually inserts `KEYS.hr` through the same block insertion helper used by other registry blocks.

## Manual Setup

<Steps>

### Install Package

```bash
npm install @platejs/basic-nodes
```

### Add The Plugin

Use the React plugin when the editor renders the divider UI.

```tsx
import { HorizontalRuleRules } from '@platejs/basic-nodes';
import { HorizontalRulePlugin } from '@platejs/basic-nodes/react';
import { createPlateEditor } from 'platejs/react';

import { HrElement } from '@/components/ui/hr-node';

export const editor = createPlateEditor({
  plugins: [
    HorizontalRulePlugin.configure({
      inputRules: [
        HorizontalRuleRules.markdown({ variant: '-' }),
        HorizontalRuleRules.markdown({ variant: '_' }),
      ],
      node: { component: HrElement },
    }),
  ],
});
```

### Add Static Rendering

Use the base plugin with the static component in static rendering paths.

```tsx
import { BaseHorizontalRulePlugin } from '@platejs/basic-nodes';
import { createStaticEditor } from 'platejs';

import { HrElementStatic } from '@/components/ui/hr-node-static';

export const staticEditor = createStaticEditor({
  plugins: [BaseHorizontalRulePlugin.withComponent(HrElementStatic)],
});
```

</Steps>

## Value Shape

Horizontal rules are void block elements. Keep the empty text child so the node remains a valid Slate element.

```tsx
const value = [
  {
    children: [{ text: 'Before the divider' }],
    type: 'p',
  },
  {
    children: [{ text: '' }],
    type: 'hr',
  },
  {
    children: [{ text: 'After the divider' }],
    type: 'p',
  },
];
```

| Field | Type | Notes |
|-------|------|-------|
| `type` | `'hr'` | Plugin key and node type from `KEYS.hr`. |
| `children` | `[{ text: '' }]` | Required child for the void element. |

## Input Rules

`HorizontalRuleRules.markdown()` converts a paragraph into an `hr` block and inserts an empty paragraph after it.

| Rule | Trigger | Behavior |
|------|---------|----------|
| `HorizontalRuleRules.markdown({ variant: '-' })` | type the third `-` after `--` | Converts `---` to `hr`, then inserts a paragraph. |
| `HorizontalRuleRules.markdown({ variant: '_' })` | type a space after `___` | Converts `___ ` to `hr`, then inserts a paragraph. |

The rule uses `editor.tf.setNodes({ type: KEYS.hr })`, so it transforms the current block instead of inserting a second divider elsewhere.

## Registry UI

| Surface | Behavior |
|---------|----------|
| Editable element | Renders a non-editable padded wrapper with an `<hr>` inside it. |
| Selected + focused | Adds a focus ring around the divider. |
| Read-only | Removes the pointer cursor from the editable component. |
| Static element | Renders the same divider inside `SlateElement`. |
| Insert toolbar | Adds a `Divider` item with `MinusIcon` and `KEYS.hr`. |

The divider component renders `{props.children}` after the non-editable wrapper so Slate can still keep the void child mounted.

## API Reference

| API | Package | Use |
|-----|---------|-----|
| `BaseHorizontalRulePlugin` | `@platejs/basic-nodes` | Headless void `hr` block with HTML deserialization and default render tag. |
| `HorizontalRulePlugin` | `@platejs/basic-nodes/react` | React horizontal rule plugin. |
| `HorizontalRuleRules.markdown({ variant: '-' })` | `@platejs/basic-nodes` | Creates the dash input rule for `---`. |
| `HorizontalRuleRules.markdown({ variant: '_' })` | `@platejs/basic-nodes` | Creates the underscore input rule for `___ `. |


# Link

Source: https://platejs.org/docs/link

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Link
docs:
  - route: https://pro.platejs.org/docs/examples/link
    title: Plus
  - route: /docs/components/link-node
    title: Link Element
  - route: /docs/components/link-toolbar
    title: Link Floating Toolbar
  - route: /docs/components/link-toolbar-button
    title: Link Toolbar Button
---

[link-demo registry content](https://platejs.org/r/link-demo)

<PackageInfo>

## Features

- Insert, edit, and remove hyperlinks.
- Markdown shortcut: type `[text](url)` and close with `)` to turn it into a link.
- Plain URL autolink: paste a URL, or type a URL then press space or `Enter`.

</PackageInfo>

## Kit Usage

<Steps>

### Installation

The fastest way to add link functionality is with the `LinkKit`, which includes pre-configured `LinkPlugin` with floating toolbar, autolink rules, and [Plate UI](/docs/installation/plate-ui) components.

[link-kit registry content](https://platejs.org/r/link-kit)

- [`LinkElement`](/docs/components/link-node): Renders link elements.
- [`LinkFloatingToolbar`](/docs/components/link-toolbar): Provides floating toolbar for link editing.

### Add Kit

Add the kit to your plugins:

```tsx
import { createPlateEditor } from 'platejs/react';
import { LinkKit } from '@/components/editor/plugins/link-kit';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    ...LinkKit,
  ],
});
```

</Steps>

## Manual Usage

<Steps>

### Installation

```bash
npm install @platejs/link
```

### Add Plugin

Include `LinkPlugin` in your Plate plugins array when creating the editor.

```tsx
import { LinkRules } from '@platejs/link';
import { LinkPlugin } from '@platejs/link/react';
import { createPlateEditor } from 'platejs/react';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    LinkPlugin,
  ],
});
```

### Configure Plugin

Configure the plugin with floating toolbar and custom components.

```tsx
import { LinkPlugin } from '@platejs/link/react';
import { createPlateEditor } from 'platejs/react';
import { LinkElement } from '@/components/ui/link-node';
import { LinkFloatingToolbar } from '@/components/ui/link-toolbar';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    LinkPlugin.configure({
      render: {
        node: LinkElement,
        afterEditable: () => <LinkFloatingToolbar />,
      },
    }),
  ],
});
```

- `render.afterEditable`: Renders [`LinkFloatingToolbar`](/docs/components/link-toolbar) after the editable area for link editing.
- `render.node`: Assigns [`LinkElement`](/docs/components/link-node) to render link elements.

### Input Rules

Configure `LinkPlugin` to enable the built-in link input presets:

```tsx
import { LinkPlugin } from '@platejs/link/react';

const editor = createPlateEditor({
  plugins: [
    LinkPlugin.configure({
      inputRules: [
        LinkRules.markdown(),
        LinkRules.autolink({ variant: 'paste' }),
        LinkRules.autolink({ variant: 'space' }),
        LinkRules.autolink({ variant: 'break' }),
      ],
    }),
  ],
});
```

- `LinkRules.autolink({ variant: 'paste' | 'space' | 'break' })`: Enables plain URL autolink.
- `LinkRules.markdown()`: Enables `[text](url)` source-entry conversion on the closing `)`.

### Add Toolbar Button

You can add [`LinkToolbarButton`](/docs/components/link-toolbar-button) to your [Toolbar](/docs/toolbar) to insert and edit links.

</Steps>

## Keyboard Shortcuts

<KeyTable>
  <KeyTableItem hotkey="Cmd + K">Add a link on the selected text.</KeyTableItem>
</KeyTable>

## Plate Plus

[link-pro registry content](https://platejs.org/r/link-pro)

## Plugins

### `LinkPlugin`

Plugin for link formatting.

<API name="LinkPlugin">
<APIOptions type="object">
<APIItem name="forceSubmit" type="boolean" optional>
Determines whether to force the submission of the link form.
</APIItem>
<APIItem name="rangeBeforeOptions" type="RangeBeforeOptions" optional>
Allows custom configurations for rangeBeforeOptions.
- **Default:**
```ts
{
  matchString: ' ',
  skipInvalid: true,
  afterMatch: true,
}
```
</APIItem>
<APIItem name="triggerFloatingLinkHotkeys" type="string | string[]" optional>
Hotkeys to trigger floating link.
- **Default:** **`'meta+k, ctrl+k'`**
</APIItem>
<APIItem name="allowedSchemes" type="string[]" optional>
List of allowed URL schemes.
- **Default:** **`['http', 'https', 'mailto', 'tel']`**
</APIItem>
<APIItem name="dangerouslySkipSanitization" type="boolean" optional>
Determines whether the sanitation of links should be skipped.
- **Default:** **`false`**
</APIItem>
<APIItem name="defaultLinkAttributes" type="AnchorHTMLAttributes&lt;HTMLAnchorElement&gt;" optional>
Default HTML attributes for link elements.
- **Default:** **`{}`**
</APIItem>
<APIItem name="keepSelectedTextOnPaste" type="boolean" optional>
Keeps selected text on pasting links by default.
- **Default:** **`true`**
</APIItem>
<APIItem name="isUrl" type="(text: string) => boolean" optional>
Callback function to validate a URL.
- **Default:** **`isUrl`**
</APIItem>
<APIItem name="getUrlHref" type="(url: string) => string | undefined" optional>
Callback function to optionally get the href for a URL. It returns an optional link that is different from the text content. For example, returns `https://google.com` for `google.com`.
</APIItem>
<APIItem name="transformInput" type="(url: string | null) => string | undefined" optional>
Callback function to optionally transform the submitted URL provided by the user to the URL input before validation.
</APIItem>
<APIItem name="getLinkUrl" type="(prevUrl: string | null) => Promise<string | null>" optional>
On keyboard shortcut or toolbar mousedown, this function is called to get the link URL. The default behavior is to use the browser's native `prompt`.
</APIItem>
</APIOptions>
</API>

## Transforms

### `tf.insert.link`

Inserts a link node into the editor.

<API name="insert.link">
<APIParameters>
  <APIItem name="options" type="object">
    Options for inserting the link.
  </APIItem>
</APIParameters>
<APIOptions type="InsertLinkOptions">
  <APIItem name="createLinkNodeOptions" type="CreateLinkNodeOptions">
    Options for creating the link node.
  </APIItem>
  <APIItem name="insertOptions" type="InsertNodesOptions" optional>
    Additional options for inserting nodes.
  </APIItem>
 </APIOptions>
</API>

## API

### `api.floatingLink.hide`

Hides the floating link and resets its state.

### `api.floatingLink.reset`

Resets the floating link state without changing the openEditorId.

### `api.floatingLink.show`

Shows the floating link for the specified mode and editor ID.

<API name="floatingLink.show">
<APIParameters>
<APIItem name="mode" type="FloatingLinkMode">
The mode to set for the floating link ('edit' or 'insert').
</APIItem>
<APIItem name="editorId" type="string">
The ID of the editor where the floating link should be shown.
</APIItem>
</APIParameters>
</API>

### `api.link.getAttributes`

Gets the attributes for a link element.

<API name="link.getAttributes">
<APIParameters>
<APIItem name="element" type="TLinkElement">
The link element for which to get attributes.
</APIItem>
</APIParameters>

<APIReturns type="React.AnchorHTMLAttributes<HTMLAnchorElement>">
The HTML attributes for the link element.
</APIReturns>
</API>

### `api.link.submitFloatingLink`

Inserts a link if the URL is valid, closes the floating link, and focuses the editor.

<APIReturns type="boolean">
Returns `true` if the link was inserted successfully.
</APIReturns>

### `insertLink`

Inserts a link node into the editor.

<API name="insertLink">
<APIParameters>
  <APIItem name="createLinkNodeOptions" type="CreateLinkNodeOptions">
    Options for creating link node.
  </APIItem>
  <APIItem name="options" type="InsertNodesOptions" optional>
    Additional options for node insertion.
  </APIItem>
</APIParameters>
</API>

### `submitFloatingLink`

Inserts a link if the URL is valid, closes the floating link, and focuses the editor.

- Insert link if url is valid.
- Text is url if empty.
- Close floating link.
- Focus editor.

<API name="submitFloatingLink">
<APIReturns type="boolean">
Returns `true` if the link was inserted.
</APIReturns>
</API>

### `triggerFloatingLink`

Triggers the floating link.

<API name="triggerFloatingLink">
<APIOptions type="object">
<APIItem name="focused" type="boolean" optional>
  Whether the floating link should be focused.
</APIItem>
</APIOptions>
</API>

### `triggerFloatingLinkEdit`

Triggers the floating link edit.

<API name="triggerFloatingLinkEdit">
<APIReturns type="boolean">
Returns `true` if the link was edited.
</APIReturns>
</API>

### `triggerFloatingLinkInsert`

Trigger floating link. Do not trigger when:
- Selection is across blocks
- Selection has more than one leaf node
- Lowest selection is not text
- Selection has a link node

<API name="triggerFloatingLinkInsert">
<APIOptions type="TriggerFloatingLinkOptions">
  <APIItem name="focused" type="boolean" optional>
    Whether the floating link should be focused.
  </APIItem>
</APIOptions>

<APIReturns type="boolean">
  Returns `true` if the link was inserted.
</APIReturns>
</API>

### `unwrapLink`

Unwraps a link node.

<API name="unwrapLink">
<APIOptions type="UnwrapLinkOptions">
  <APIItem name="split" type="boolean" optional>
    If `true`, split the nodes if the selection is inside the link.
  </APIItem>
</APIOptions>
</API>

### `upsertLink`

Insert or update a link node. The behavior depends on the current selection and options:

- If selection is in a link or not a URL:
  - With `insertTextInLink: true`, inserts URL as text in link
  - Otherwise, if `text` is empty, sets it to URL
  - Validates URL unless `skipValidation: true`
- If selection is expanded or `update: true` in a link:
  - Removes link node and gets link text
- Then:
  - Inserts link node with updated URL and target
  - If `text` is provided, replaces link text

<API name="upsertLink">
<APIParameters>
  <APIItem name="options" type="UpsertLinkOptions">
    Options for upserting the link.
  </APIItem>
</APIParameters>

<APIOptions type="UpsertLinkOptions">
  <APIItem name="url" type="string">
    The URL of the link.
  </APIItem>
  <APIItem name="text" type="string" optional>
    The text content of the link.
  </APIItem>
  <APIItem name="target" type="string" optional>
    The target attribute of the link.
  </APIItem>
  <APIItem name="insertTextInLink" type="boolean" optional>
    If `true`, insert the URL as text in the link.
  </APIItem>
  <APIItem name="insertNodesOptions" type="InsertNodesOptions" optional>
    The options for inserting nodes.
  </APIItem>
  <APIItem name="skipValidation" type="boolean" optional>
    If `true`, skips URL validation.
    - **Default:** `false`
  </APIItem>
</APIOptions>

<APIReturns type="boolean">
  Returns `true` if the link was inserted or updated.
</APIReturns>
</API>

### `upsertLinkText`

If the text is different from the link above text, replaces the link children with a new text node. The new text node has the same marks as the first text node in the link.

<API name="upsertLinkText">
<APIOptions type="UpsertLinkTextOptions">
      <APIItem name="text" type="string" optional>
        The new text to replace the link children with.
      </APIItem>
</APIOptions>
</API>

### `validateUrl`

Validates a URL based on the plugin options.

<API name="validateUrl">
<APIOptions type="ValidateUrlOptions">
  <APIItem name="url" type="string">
    The URL to validate.
  </APIItem>
</APIOptions>

<APIReturns type="boolean">
  Returns `true` if the URL is valid.
</APIReturns>
</API>

### `wrapLink`

Wrap a link node with split.

<API name="wrapLink">
<APIOptions type="WrapLinkOptions">
  <APIItem name="url" type="string">
    The URL of the link.
  </APIItem>
  <APIItem name="target" type="string" optional>
    The target attribute of the link.
  </APIItem>
</APIOptions>
</API>

### `CreateLinkNodeOptions`

Options for creating a new link node.

<API name="CreateLinkNodeOptions">
<APIOptions type="object">
  <APIItem name="url" type="string">
    The URL of the link node that is being created.
  </APIItem>
  <APIItem name="text" type="string" optional>
    The text that is displayed for the link node. If not provided, the URL is used as the display text.
  </APIItem>
  <APIItem name="target" type="string" optional>
    Specifies where to open the URL:
    - `_blank`: new tab
    - `_self`: same frame
    - `_parent`: parent frame
    - `_top`: full window
  </APIItem>
  <APIItem name="children" type="TText[]" optional>
    An array of text nodes that represent the link content.
  </APIItem>
</APIOptions>
</API>

## API Components

### `FloatingLinkNewTabInput`

The input component for controlling whether a link opens in a new tab.

<API name="FloatingLinkNewTabInput">
<APIState>
  <APIItem name="checked" type="boolean">
    Whether the link should open in a new tab.
  </APIItem>
  <APIItem name="setChecked" type="React.Dispatch<React.SetStateAction<boolean>>">
    Function to update the checked state.
  </APIItem>
  <APIItem name="ref" type="RefObject<HTMLInputElement>">
    Reference to the input element.
  </APIItem>
</APIState>
</API>

### `FloatingLinkUrlInput`

The input component for entering and editing link URLs.

<API name="FloatingLinkUrlInput">
<APIState>
  <APIItem name="ref" type="RefObject<HTMLInputElement>">
    Reference to the input element.
  </APIItem>
</APIState>
</API>

### `LinkOpenButton`

The button component for opening the link URL.

<API name="LinkOpenButton">
<APIState>
  <APIItem name="element" type="TLinkElement">
    The link element containing the URL to open.
  </APIItem>
</APIState>
</API>

### `useFloatingLinkEdit`

The behavior hook for the floating link edit functionality.

<API name="useFloatingLinkEdit">
<APIState>
  <APIItem name="floating" type="object" optional>
    The virtual floating returned object.
  </APIItem>
</APIState>

<APIReturns type="object">
  <APIItem name="ref" type="function">
    The ref callback for the floating element.
  </APIItem>
  <APIItem name="props" type="object">
    Props for the floating element.
    <APISubList>
      <APISubListItem parent="props" name="style" type="object">
        The style of the floating link.
      </APISubListItem>
    </APISubList>
  </APIItem>
  <APIItem name="editButtonProps" type="object">
    Props for the edit button.
    <APISubList>
      <APISubListItem parent="editButtonProps" name="onClick" type="function">
        The function to call when the edit button is clicked.
      </APISubListItem>
    </APISubList>
  </APIItem>
  <APIItem name="unlinkButtonProps" type="object">
    Props for the unlink button.
    <APISubList>
      <APISubListItem parent="unlinkButtonProps" name="onClick" type="function">
        The function to call when the unlink button is clicked.
      </APISubListItem>
    </APISubList>
  </APIItem>
</APIReturns>
</API>

### `useFloatingLinkEnter`

Listens for the Enter key press event and submits the floating link in the editor.

### `useFloatingLinkEscape`

Listens for the Escape key press event and handles the behavior of the floating link in the editor.

### `useFloatingLinkInsert`

The behavior hook for inserting a link.

<API name="useFloatingLinkInsert">
<APIState>
  <APIItem name="floating" type="ReturnType<typeof useFloatingLinkInsertState>">
    The virtual floating returned object.
  </APIItem>
  <APIItem name="refClickOutside" type="React.Ref">
    The ref of the floating element.
  </APIItem>
</APIState>

<APIReturns type="object">
  <APIItem name="ref" type="function">
    The ref callback for the floating element.
  </APIItem>
  <APIItem name="props" type="object">
    Props for the floating element.
    <APISubList>
      <APISubListItem parent="props" name="style" type="object">
        The style of the floating link.
      </APISubListItem>
    </APISubList>
  </APIItem>
  <APIItem name="textInputProps" type="object">
    Props for the text input.
    <APISubList>
      <APISubListItem parent="textInputProps" name="onChange" type="function">
        The function to call when the text input value changes.
      </APISubListItem>
      <APISubListItem parent="textInputProps" name="defaultValue" type="string">
        The default value of the text input.
      </APISubListItem>
    </APISubList>
  </APIItem>
</APIReturns>
</API>

### `useLink`

The behavior hook for the link element.

<API name="useLink">
<APIOptions type="UseLinkOptions">
  <APIItem name="element" type="TLinkElement">
    The link element.
  </APIItem>
</APIOptions>

<APIReturns type="object">
  <APIItem name="props" type="object">
    Props for the link element.
    <APISubList>
      <APISubListItem parent="props" name="onMouseOver" type="function">
        The function to call when the mouse is over the link.
      </APISubListItem>
    </APISubList>
  </APIItem>
</APIReturns>
</API>

### `useLinkToolbarButton`

The behavior hook for the link toolbar button.

<API name="useLinkToolbarButton">
<APIState>
  <APIItem name="pressed" type="boolean">
    Whether the selection is in a link.
  </APIItem>
</APIState>

<APIReturns type="object">
  <APIItem name="props" type="object">
    Props for the toolbar button.
    <APISubList>
      <APISubListItem parent="props" name="pressed" type="boolean">
        Whether the link is pressed.
      </APISubListItem>
      <APISubListItem parent="props" name="onClick" type="function">
        The function to call when the button is clicked.
      </APISubListItem>
    </APISubList>
  </APIItem>
</APIReturns>
</API>

### `useVirtualFloatingLink`

Custom hook for managing virtual floating of a link.

<API name="useVirtualFloatingLink">
<APIOptions type="object">
  <APIItem name="editorId" type="string">
    The ID of the editor to which the link belongs.
  </APIItem>
  <APIItem name="floatingOptions" type="UseVirtualFloatingOptions" optional>
    Options for virtual floating.
  </APIItem>
</APIOptions>

<APIReturns type="UseVirtualFloatingReturn">
  The return value of the `useVirtualFloating` hook.
</APIReturns>
</API>


# List Classic

Source: https://platejs.org/docs/list-classic

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: List Classic
docs:
  - route: /docs/components/list-classic-node
    title: List Nodes
  - route: /docs/components/list-classic-toolbar-button
    title: List Toolbar Button
---

[list-classic-demo registry content](https://platejs.org/r/list-classic-demo)

<Callout type="info" title="Choose Your List Plugin">
  Plate offers two approaches for implementing lists:

  1. **This List Classic plugin** - Traditional HTML-spec lists with strict nesting rules:
     - Follows standard HTML list structure (`ul`/`ol` > `li`)
     - Maintains consistent list hierarchy
     - Best for content that may be exported to HTML/markdown
     - Highest complexity

  2. The [**List plugin**](/docs/list) - Flexible indentation-based lists:
     - More like Word/Google Docs behavior
     - Any block can be indented to create list-like structures
     - Used in the [AI editor](/editors#editor-ai)
     - Supports nested todo lists
     - Better for free-form content organization

  Choose based on your needs:
  - Use the **List Classic plugin** when you need standard HTML list compatibility
  - Use the **List plugin** when you want more flexible indentation behavior

</Callout>

<PackageInfo>


## Features

- **HTML-compliant lists**:
  - Standard `ul`/`ol` > `li` structure
  - Proper nesting and hierarchy
  - SEO-friendly markup
  - Clean HTML/markdown export

- **List types**:
  - Unordered (bulleted) lists
  - Ordered (numbered) lists
  - Task lists with checkboxes
  - Nested sublists

- **Drag & drop**:
  - Currently supports root-level list items only
  - Sibling and nested items drag & drop not yet supported

- **Shortcuts**:
  - Register the shipped input rules to use markdown shortcuts (**`-`**, **`*`**, **`1.`**, **`[ ]`**) to create lists
  - Tab/Shift+Tab for indentation control

- **Limitations (use the [List plugin](/docs/list) for these features)**:
  - Drag & drop only supports root-level lists
  - List items cannot be aligned

For a more flexible, Word-like approach, see the [List plugin](/docs/list).

</PackageInfo>

## Kit Usage

<Steps>

### Installation

The fastest way to add list functionality is with the `ListKit` export from `list-classic-kit`, which includes pre-configured list plugins, the classic markdown entry rules, [Plate UI](/docs/installation/plate-ui) components, and keyboard shortcuts.

[list-classic-kit registry content](https://platejs.org/r/list-classic-kit)

- [`BulletedListElement`](/docs/components/list-classic-node): Renders unordered list elements.
- [`NumberedListElement`](/docs/components/list-classic-node): Renders ordered list elements.
- [`TaskListElement`](/docs/components/list-classic-node): Renders task list elements with checkboxes.

### Add Kit

Add the kit to your plugins:

```tsx
import { createPlateEditor } from 'platejs/react';
import { ListKit } from '@/components/editor/plugins/list-classic-kit';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    ...ListKit,
  ],
});
```

</Steps>

The shipped `ListKit` also wires the classic markdown entry rules for bulleted, ordered, and task lists. See [Plugin Input Rules](/docs/plugin-input-rules) for the runtime model.

## Manual Usage

<Steps>

### Installation

```bash
npm install @platejs/list-classic
```

### Add Plugins

Include the list plugins in your Plate plugins array when creating the editor.

```tsx
import { ListPlugin, BulletedListPlugin, NumberedListPlugin, TaskListPlugin, ListItemPlugin } from '@platejs/list-classic/react';
import { createPlateEditor } from 'platejs/react';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    ListPlugin,
    BulletedListPlugin,
    NumberedListPlugin,
    TaskListPlugin,
    ListItemPlugin,
  ],
});
```

### Configure Plugins

Configure the plugins with custom components and keyboard shortcuts.

```tsx
import {
  BulletedListRules,
  OrderedListRules,
  TaskListRules,
} from '@platejs/list-classic';
import { ListPlugin, BulletedListPlugin, NumberedListPlugin, TaskListPlugin, ListItemPlugin } from '@platejs/list-classic/react';
import { createPlateEditor } from 'platejs/react';
import { BulletedListElement, NumberedListElement, TaskListElement } from '@/components/ui/list-classic-node';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    ListPlugin.configure({
      inputRules: [
        BulletedListRules.markdown({ variant: '-' }),
        BulletedListRules.markdown({ variant: '*' }),
        OrderedListRules.markdown({ variant: '.' }),
        OrderedListRules.markdown({ variant: ')' }),
        TaskListRules.markdown({ checked: false }),
        TaskListRules.markdown({ checked: true }),
      ],
    }),
    BulletedListPlugin.configure({
      node: { component: BulletedListElement },
      shortcuts: { toggle: { keys: 'mod+alt+5' } },
    }),
    NumberedListPlugin.configure({
      node: { component: NumberedListElement },
      shortcuts: { toggle: { keys: 'mod+alt+6' } },
    }),
    TaskListPlugin.configure({
      node: { component: TaskListElement },
      shortcuts: { toggle: { keys: 'mod+alt+7' } },
    }),
    ListItemPlugin,
  ],
});
```

- `inputRules`: Registers the classic markdown entry rules for bulleted, ordered, and task lists.
- `node.component`: Assigns [`BulletedListElement`](/docs/components/list-classic-node), [`NumberedListElement`](/docs/components/list-classic-node), and [`TaskListElement`](/docs/components/list-classic-node) to render list elements.
- `shortcuts.toggle`: Defines keyboard [shortcuts](/docs/plugin-shortcuts) to toggle list types (`mod+alt+5` for bulleted, `mod+alt+6` for numbered, `mod+alt+7` for task lists).

### Add Toolbar Button

You can add [`ListToolbarButton`](/docs/components/list-classic-toolbar-button) to your [Toolbar](/docs/toolbar) to create and manage lists.

### Turn Into Toolbar Button

When using the `ListPlugin`, use the [`turn-into-toolbar-classic-button`](/docs/components/turn-into-toolbar-classic-button) which includes all list types (bulleted, numbered, and task lists).

### Insert Toolbar Button

When using the `ListPlugin`, use the [`insert-toolbar-classic-button`](/docs/components/insert-toolbar-classic-button) which includes all list types (bulleted, numbered, and task lists).

</Steps>

## Plugins

### `ListPlugin`

<API name="ListPlugin">
Contains the following element plugins:
- `BulletedListPlugin`
- `NumberedListPlugin`
- `TaskListPlugin`
- `ListItemPlugin`
- `ListItemContentPlugin`

<APIOptions type="object">
  <APIItem name="validLiChildrenTypes" type="string[]" optional>
    Valid child node types for list items (besides `p` and `ul`).
  </APIItem>
  <APIItem name="enableResetOnShiftTab" type="boolean" optional>
    Whether Shift+Tab should reset list indent level.
  </APIItem>
  <APIItem name="inheritCheckStateOnLineEndBreak" type="boolean" optional>
    Whether to inherit the checked state of above node after insert break at the end. Only applies to task lists.
    - **Default:** `false`
  </APIItem>
  <APIItem name="inheritCheckStateOnLineStartBreak" type="boolean" optional>
    Whether to inherit the checked state of below node after insert break at the start. Only applies to task lists.
    - **Default:** `false`
  </APIItem>
</APIOptions>
</API>

### `BulletedListPlugin`

Plugin for unordered (bulleted) lists.

### `NumberedListPlugin`

Plugin for ordered (numbered) lists.

### `TaskListPlugin`

Plugin for task lists with checkboxes.

### `ListItemPlugin`

Plugin for list items.

### `ListItemContentPlugin`

Plugin for list item content.

## Transforms

### `tf.ul.toggle()`

Toggles a bulleted list (ul).

Example Shortcut: `Mod+Alt+5`

### `tf.ol.toggle()`

Toggles an ordered list (ol).

Example Shortcut: `Mod+Alt+6`

### `tf.taskList.toggle()`

Toggles a task list with checkboxes.

Example Shortcut: `Mod+Alt+7`

## API

### `getHighestEmptyList`

Finds the highest end list that can be deleted. The path of the list should be different from `diffListPath`. If the highest end list has 2 or more items, returns `liPath`. It traverses up the parent lists until:
- The list has less than 2 items
- Its path is not equal to `diffListPath`

<API name="getHighestEmptyList">
<APIOptions type="object">
  <APIItem name="liPath" type="Path">
    Path of list item.
  </APIItem>
  <APIItem name="diffListPath" type="Path" optional>
    Path of different list.
  </APIItem>
</APIOptions>

<APIReturns type="Path | undefined">
  Path of highest deletable end list.
</APIReturns>
</API>

### `getListItemEntry`

Returns the nearest `li` and `ul`/`ol` wrapping node entries for a given path (`default = selection`).

<API name="getListItemEntry">
<APIOptions type="object">
  <APIItem name="at" type="Location | null" optional>
    Location to get entries from.
    - **Default:** `editor.selection`
  </APIItem>
</APIOptions>

<APIReturns type="ElementEntry | undefined">
  Nearest `li` and `ul`/`ol` wrapping node entries.
</APIReturns>
</API>

### `getListRoot`

Searches upward for root list element.

<API name="getListRoot">
<APIParameters>
  <APIItem name="at" type="Path | TRange | Point | null" optional>
    Location to start search from.
    - **Default:** `editor.selection`
  </APIItem>
</APIParameters>

<APIReturns type="ElementEntry | undefined">
  Root list element entry.
</APIReturns>
</API>

### `getListTypes`

Gets array of supported list types.

<API name="getListTypes">
<APIReturns type="string[]">
  Array of supported list types.
</APIReturns>
</API>

### `moveListSiblingsAfterCursor`

Moves list siblings after cursor to specified path.

<API name="moveListSiblingsAfterCursor">
<APIOptions type="options">
  <APIItem name="at" type="Path">
    Cursor position path.
  </APIItem>
  <APIItem name="to" type="Path">
    Destination path.
  </APIItem>
</APIOptions>

<APIReturns type="number">
  Number of siblings moved.
</APIReturns>
</API>

### `removeFirstListItem`

Removes first list item if not nested and not first child.

<API name="removeFirstListItem">
<APIOptions type="options">
  <APIItem name="list" type="ElementEntry">
    List entry containing item.
  </APIItem>
  <APIItem name="listItem" type="ElementEntry">
    List item to remove.
  </APIItem>
</APIOptions>

<APIReturns type="boolean">
  Whether item was removed.
</APIReturns>
</API>

### `removeListItem`

Removes list item and moves sublist to parent if any.

<API name="removeListItem">
<APIOptions type="RemoveListItemOptions">
  <APIItem name="list" type="ElementEntry">
    List entry containing item.
  </APIItem>
  <APIItem name="listItem" type="ElementEntry">
    List item to remove.
  </APIItem>
  <APIItem name="reverse" type="boolean" optional>
    Whether to reverse sublist items.
    - **Default:** `true`
  </APIItem>
</APIOptions>

<APIReturns type="boolean">
  Whether item was removed.
</APIReturns>
</API>

### `someList`

Checks if selection is inside list of specific type.

<API name="someList">
<APIParameters>
  <APIItem name="type" type="string">
    List type to check.
  </APIItem>
</APIParameters>

<APIReturns type="boolean">
  Whether selection is in specified list type.
</APIReturns>
</API>

### `unindentListItems`

Decreases indentation level of list items.

<API name="unindentListItems">
<APIOptions type="UnindentListItemsOptions">
    Target path for unindenting.
</APIOptions>
</API>

### `unwrapList`

Removes list formatting from selected items.

<API name="unwrapList">
<APIOptions type="options">
  <APIItem name="at" type="Path" optional>
    Target path for unwrapping.
  </APIItem>
</APIOptions>
</API>

## Hooks

### `useListToolbarButton`

A behavior hook for a list toolbar button.

<API name="useListToolbarButton">
<APIState>
  <APIItem name="pressed" type="boolean">
    Button pressed state.
  </APIItem>
  <APIItem name="nodeType" type="string">
    List node type.
    - **Default:** `BulletedListPlugin.key`
  </APIItem>
</APIState>

<APIReturns type="object">
  <APIItem name="props" type="object">
    Props for toolbar button.
  </APIItem>
  <APISubList>
    <APISubListItem parent="props" name="pressed" type="boolean">
      Button pressed state.
    </APISubListItem>
    <APISubListItem parent="props" name="onClick" type="function">
      Handler to toggle list and focus editor.
    </APISubListItem>
  </APISubList>
</APIReturns>
</API>

### `useTodoListElementState`

Hook to manage task list item state.

<API name="useTodoListElementState">
<APIState>
  <APIItem name="element" type="TTodoListItemElement">
    Task list item element.
  </APIItem>
</APIState>

<APIReturns type="object">
  <APIItem name="checked" type="boolean">
    Whether the task item is checked.
  </APIItem>
  <APIItem name="readOnly" type="boolean">
    Whether the editor is in read-only mode.
  </APIItem>
  <APIItem name="onCheckedChange" type="function">
    Handler to toggle the checked state.
  </APIItem>
</APIReturns>
</API>

### `useTodoListElement`

Hook to get props for task list item checkbox.

<API name="useTodoListElement">
<APIState>
  <APIItem name="checked" type="boolean">
    Whether the task item is checked.
  </APIItem>
  <APIItem name="readOnly" type="boolean">
    Whether the editor is in read-only mode.
  </APIItem>
  <APIItem name="onCheckedChange" type="function">
    Handler to toggle the checked state.
  </APIItem>
</APIState>

<APIReturns type="object">
  <APIItem name="checkboxProps" type="object">
    Props to be spread on the checkbox component.
  </APIItem>
</APIReturns>
</API>


# Media

Source: https://platejs.org/docs/media

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Media
docs:
  - route: https://pro.platejs.org/docs/examples/media
    title: Plus
  - route: /docs/components/media-image-node
    title: Image Element
  - route: /docs/components/media-video-node
    title: Video Element
  - route: /docs/components/media-audio-node
    title: Audio Element
  - route: /docs/components/media-file-node
    title: File Element
  - route: /docs/components/media-embed-node
    title: Media Embed Element
  - route: /docs/components/media-toolbar
    title: Media Popover
  - route: /docs/components/media-placeholder-node
    title: Media Placeholder Element
  - route: /docs/components/media-upload-toast
    title: Media Upload Toast
  - route: /docs/components/media-toolbar-button
    title: Media Toolbar Button
---

[media-demo registry content](https://platejs.org/r/media-demo)

<PackageInfo>

## Features

### Media Support
- **File types**: 
  - Image
  - Video
  - Audio
  - Others (PDF, Word, etc.)
- **Video providers**:
  - Local video files
  - YouTube, Vimeo, Dailymotion, Youku, Coub
- **Embed providers**: 
  - Tweets

### Media Features
- Editable captions
- Resizable elements
- Embed URLs are normalized into `url`, `provider`, and `id` props, with an optional `sourceUrl` preserved for reversible editing.

### Upload
- **Multiple upload methods**:
  - Toolbar button with file picker
  - Drag and drop from file system
  - Paste from clipboard (images)
  - URL embedding for external media
- **Upload experience**:
  - Real-time progress tracking
  - Preview during upload
  - Automatically converts the placeholder to the appropriate media element (image, video, audio, file) once the upload or embed is submitted
  - Error handling
  - File size validation
  - Type validation

</PackageInfo>

## Kit Usage

<Steps>

### Installation

The fastest way to add comprehensive media support is with the `MediaKit`, which includes pre-configured `ImagePlugin`, `VideoPlugin`, `AudioPlugin`, `FilePlugin`, `MediaEmbedPlugin`, `PlaceholderPlugin`, and `CaptionPlugin` with their [Plate UI](/docs/installation/plate-ui) components.

[media-kit registry content](https://platejs.org/r/media-kit)

- [`ImageElement`](/docs/components/media-image-node): Renders image elements.
- [`VideoElement`](/docs/components/media-video-node): Renders video elements.
- [`AudioElement`](/docs/components/media-audio-node): Renders audio elements.
- [`FileElement`](/docs/components/media-file-node): Renders file elements.
- [`MediaEmbedElement`](/docs/components/media-embed-node): Renders embedded media.
- [`PlaceholderElement`](/docs/components/media-placeholder-node): Renders upload placeholders.
- [`MediaUploadToast`](/docs/components/media-upload-toast): Shows upload progress notifications.
- [`MediaPreviewDialog`](/docs/components/media-preview-dialog): Provides media preview functionality.

### Add Kit

Add the kit to your plugins:

```tsx
import { createPlateEditor } from 'platejs/react';
import { MediaKit } from '@/components/editor/plugins/media-kit';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    ...MediaKit,
  ],
});
```

### Add API Routes

<ComponentInstallation name="media-uploadthing-api" inline />

### Environment Setup

Get your secret key from [UploadThing](https://uploadthing.com/dashboard/settings) and add it to `.env`:

```bash title=".env"
UPLOADTHING_TOKEN=xxx
```

</Steps>

## Manual Usage

<Steps>

### Installation

```bash
npm install @platejs/media
```

### Add Plugins

Include the media plugins in your Plate plugins array when creating the editor.

```tsx
import {
  AudioPlugin,
  FilePlugin,
  ImagePlugin,
  MediaEmbedPlugin,
  PlaceholderPlugin,
  VideoPlugin,
} from '@platejs/media/react';
import { createPlateEditor } from 'platejs/react';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    ImagePlugin,
    VideoPlugin,
    AudioPlugin,
    FilePlugin,
    MediaEmbedPlugin,
    PlaceholderPlugin,
  ],
});
```

### Configure Plugins

Configure the plugins with custom components and upload settings.

```tsx
import {
  AudioPlugin,
  FilePlugin,
  ImagePlugin,
  MediaEmbedPlugin,
  PlaceholderPlugin,
  VideoPlugin,
} from '@platejs/media/react';
import { KEYS } from 'platejs';
import { createPlateEditor } from 'platejs/react';
import { 
  AudioElement, 
  FileElement, 
  ImageElement, 
  MediaEmbedElement, 
  PlaceholderElement, 
  VideoElement 
} from '@/components/ui/media-nodes';
import { MediaUploadToast } from '@/components/ui/media-upload-toast';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    ImagePlugin.withComponent(ImageElement),
    VideoPlugin.withComponent(VideoElement),
    AudioPlugin.withComponent(AudioElement),
    FilePlugin.withComponent(FileElement),
    MediaEmbedPlugin.withComponent(MediaEmbedElement),
    PlaceholderPlugin.configure({
      options: { disableEmptyPlaceholder: true },
      render: { afterEditable: MediaUploadToast, node: PlaceholderElement },
    }),
  ],
});
```

- `withComponent`: Assigns custom components to render each media type.
- `options.disableEmptyPlaceholder`: Prevents showing placeholder when no file is uploading.
- `render.afterEditable`: Renders upload progress toast outside the editor.

<Callout type="info">
  **Note:** When serialized to Markdown or MDX, embeds persist the canonical `url`, `provider`, and `id`, plus an optional `sourceUrl` so edits remain reversible. Allowlisted provider snippets (e.g. YouTube, Tweet) are reduced to canonical URLs on paste. Raw `<script>` or custom embed chrome is out of scope — add your own rules if you need to preserve it.
</Callout>

### Caption Support

To enable media captions, add the [Caption Plugin](/docs/caption):

```tsx
import { CaptionPlugin } from '@platejs/caption/react';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    // ...media plugins,
    CaptionPlugin.configure({
      options: {
        query: {
          allow: [KEYS.img, KEYS.video, KEYS.audio, KEYS.file, KEYS.mediaEmbed],
        },
      },
    }),
  ],
});
```

### Custom Upload Implementation

For custom upload implementations, create an upload hook that matches this interface:

```ts
interface UseUploadFileProps {
  onUploadComplete?: (file: UploadedFile) => void;
  onUploadError?: (error: unknown) => void;
  headers?: Record<string, string>;
  onUploadBegin?: (fileName: string) => void;
  onUploadProgress?: (progress: { progress: number }) => void;
  skipPolling?: boolean;
}

interface UploadedFile {
  key: string;    // Unique identifier
  url: string;    // Public URL of the uploaded file
  name: string;   // Original filename
  size: number;   // File size in bytes
  type: string;   // MIME type
}
```

Example implementation with S3 presigned URLs:

```ts
export function useUploadFile({ 
  onUploadComplete, 
  onUploadError, 
  onUploadProgress 
}: UseUploadFileProps = {}) {
  const [uploadedFile, setUploadedFile] = useState<UploadedFile>();
  const [uploadingFile, setUploadingFile] = useState<File>();
  const [progress, setProgress] = useState(0);
  const [isUploading, setIsUploading] = useState(false);

  async function uploadFile(file: File) {
    setIsUploading(true);
    setUploadingFile(file);

    try {
      // Get presigned URL and final URL from your backend
      const { presignedUrl, fileUrl, fileKey } = await fetch('/api/upload', {
        method: 'POST',
        body: JSON.stringify({
          filename: file.name,
          contentType: file.type,
        }),
      }).then(r => r.json());

      // Upload to S3 using presigned URL
      await axios.put(presignedUrl, file, {
        headers: { 'Content-Type': file.type },
        onUploadProgress: (progressEvent) => {
          const progress = (progressEvent.loaded / progressEvent.total) * 100;
          setProgress(progress);
          onUploadProgress?.({ progress });
        },
      });

      const uploadedFile = {
        key: fileKey,
        url: fileUrl,
        name: file.name,
        size: file.size,
        type: file.type,
      };

      setUploadedFile(uploadedFile);
      onUploadComplete?.(uploadedFile);
      
      return uploadedFile;
    } catch (error) {
      onUploadError?.(error);
      throw error;
    } finally {
      setProgress(0);
      setIsUploading(false);
      setUploadingFile(undefined);
    }
  }

  return {
    isUploading,
    progress,
    uploadFile,
    uploadedFile,
    uploadingFile,
  };
}
```

Then integrate your custom upload hook with the media components:

```tsx
import { useUploadFile } from '@/hooks/use-upload-file'; // Your custom hook

// In your PlaceholderElement component
export function PlaceholderElement({ className, children, element, ...props }) {
  const { uploadFile, isUploading, progress } = useUploadFile({
    onUploadComplete: (uploadedFile) => {
      // Replace placeholder with actual media element
      const { url, type } = uploadedFile;
      
      // Transform placeholder to appropriate media type
      editor.tf.replace.placeholder({
        id: element.id,
        url,
        type: getMediaType(type), // image, video, audio, file
      });
    },
    onUploadError: (error) => {
      console.error('Upload failed:', error);
      // Handle upload error, maybe show toast
    },
  });

  // Use uploadFile when files are dropped or selected
  // This integrates with the PlaceholderPlugin's file handling
}
```

### Add Toolbar Button

You can add [`MediaToolbarButton`](/docs/components/media-toolbar-button) to your [Toolbar](/docs/toolbar) to upload and insert media.

### Insert Toolbar Button

You can add these items to the [Insert Toolbar Button](/docs/toolbar#insert-toolbar-button) to insert media elements:

```tsx
{
  icon: <ImageIcon />,
  label: 'Image',
  value: KEYS.img,
}
```

</Steps>

## Plate Plus

[media-pro registry content](https://platejs.org/r/media-pro)

## Plugins

### `ImagePlugin`

Plugin for void image elements.

<API name="ImagePlugin">
<APIOptions type="ImagePluginOptions">
  <APIItem name="uploadImage" type="(dataUrl: string | ArrayBuffer) => Promise<string | ArrayBuffer> | string | ArrayBuffer" optional>
    Function to upload image to a server. Receives:
    - Data URL (string) from `FileReader.readAsDataURL`
    - ArrayBuffer from clipboard data
    Returns:
    - URL string to uploaded image
    - Original data URL/ArrayBuffer if no upload needed
    - **Default:** Returns original input
  </APIItem>
  <APIItem name="disableUploadInsert" type="boolean" optional>
    Disables file upload on data insertion.
    - **Default:** `false`
  </APIItem>
  <APIItem name="disableEmbedInsert" type="boolean" optional>
    Disables URL embed on data insertion.
    - **Default:** `false`
  </APIItem>
  <APIItem name="isUrl" type="function" optional>
    A function to check whether a text string is a URL.
  </APIItem>
  <APIItem name="transformUrl" type="function" optional>
    A function to transform the URL.
  </APIItem>
</APIOptions>
</API>

### `VideoPlugin`

Plugin for void video elements. Extends `MediaPluginOptions`.

### `AudioPlugin`

Plugin for void audio elements. Extends `MediaPluginOptions`.

### `FilePlugin`

Plugin for void file elements. Extends `MediaPluginOptions`.

### `MediaEmbedPlugin`

Plugin for void media embed elements. Extends `MediaPluginOptions`.

### `PlaceholderPlugin`

Plugin for managing media placeholders during upload. Handles file uploads, drag & drop, and clipboard paste events.

<API name="PlaceholderPlugin">
<APIOptions type="object">
  <APIItem name="uploadConfig" type="Partial<Record<AllowedFileType, MediaItemConfig>>" optional>
Configuration for different file types. Default configuration:
```ts
{
  audio: {
    maxFileCount: 1,
    maxFileSize: '8MB',
    mediaType: KEYS.audio,
    minFileCount: 1,
  },
  blob: {
    maxFileCount: 1,
    maxFileSize: '8MB',
    mediaType: KEYS.file,
    minFileCount: 1,
  },
  image: {
    maxFileCount: 3,
    maxFileSize: '4MB',
    mediaType: KEYS.image,
    minFileCount: 1,
  },
  pdf: {
    maxFileCount: 1,
    maxFileSize: '4MB',
    mediaType: KEYS.file,
    minFileCount: 1,
  },
  text: {
    maxFileCount: 1,
    maxFileSize: '64KB',
    mediaType: KEYS.file,
    minFileCount: 1,
  },
  video: {
    maxFileCount: 1,
    maxFileSize: '16MB',
    mediaType: KEYS.video,
    minFileCount: 1,
  },
}
```
Supported file types: `'image' | 'video' | 'audio' | 'pdf' | 'text' | 'blob'`
<APISubList>
  <APISubListItem parent="uploadConfig" name="mediaType" type="MediaKeys">
    The media plugin keys that this config is for: `'audio' | 'file' | 'image' | 'video'`
  </APISubListItem>
  <APISubListItem parent="uploadConfig" name="maxFileCount" type="number" optional>
    The maximum number of files of this type that can be uploaded.
  </APISubListItem>
  <APISubListItem parent="uploadConfig" name="maxFileSize" type="FileSize" optional>
    The maximum file size for a file of this type. Format: `${1|2|4|8|16|32|64|128|256|512|1024}${B|KB|MB|GB}`
  </APISubListItem>
  <APISubListItem parent="uploadConfig" name="minFileCount" type="number" optional>
    The minimum number of files of this type that must be uploaded.
  </APISubListItem>
</APISubList>
</APIItem>
<APIItem name="disableEmptyPlaceholder" type="boolean" optional>
Disable empty placeholder when no file is uploading.
- **Default:** `false`
</APIItem>
<APIItem name="disableFileDrop" type="boolean" optional>
Disable drag and drop file upload functionality.
- **Default:** `false`
</APIItem>
<APIItem name="maxFileCount" type="number" optional>
Maximum number of files that can be uploaded at once, if not specified by `uploadConfig`.
- **Default:** `5`
</APIItem>
<APIItem name="multiple" type="boolean" optional>
Allow multiple files of the same type to be uploaded.
- **Default:** `true`
</APIItem>
</APIOptions>
</API>

## API

### `api.placeholder.addUploadingFile`

Tracks a file that is currently being uploaded.

<API name="addUploadingFile">
<APIParameters>
  <APIItem name="id" type="string">
    Unique identifier for the placeholder element.
  </APIItem>
  <APIItem name="file" type="File">
    The file being uploaded.
  </APIItem>
</APIParameters>
</API>

### `api.placeholder.getUploadingFile`

Gets a file that is currently being uploaded.

<API name="getUploadingFile">
<APIParameters>
  <APIItem name="id" type="string">
    Unique identifier for the placeholder element.
  </APIItem>
</APIParameters>

<APIReturns>
  <APIItem type="File | undefined">
    The uploading file if found, undefined otherwise.
  </APIItem>
</APIReturns>
</API>

### `api.placeholder.removeUploadingFile`

Removes a file from the uploading tracking state after upload completes or fails.

<API name="removeUploadingFile">
<APIParameters>
  <APIItem name="id" type="string">
    Unique identifier for the placeholder element to remove.
  </APIItem>
</APIParameters>
</API>

## Transforms

### `tf.insert.media`

Inserts media files into the editor with upload placeholders.

<API name="insertMedia">
<APIParameters>
  <APIItem name="files" type="FileList">
    Files to upload. Validates against configured file types and limits.
  </APIItem>
  <APIItem name="options" type="object" optional>
    Options for the insert nodes transform.
  </APIItem>
</APIParameters>

<APIOptions type="object">
  <APIItem name="at" type="Path" optional>
    Location to insert the media. Defaults to current selection.
  </APIItem>
  <APIItem name="nextBlock" type="boolean" optional>
    Whether to insert a new block after the media.
    - **Default:** `true`
  </APIItem>
</APIOptions>
</API>

Validates files against configured limits (size, count, type), creates placeholder elements for each file, handles multiple file uploads sequentially, maintains upload history for undo/redo operations, and triggers error handling if validation fails.

Error codes:
```ts
enum UploadErrorCode {
  INVALID_FILE_TYPE = 400,
  TOO_MANY_FILES = 402,
  INVALID_FILE_SIZE = 403,
  TOO_LESS_FILES = 405,
  TOO_LARGE = 413,
}
```

### `tf.insert.imagePlaceholder`

Inserts a placeholder that converts to an image element when completed.

### `tf.insert.videoPlaceholder`

Inserts a placeholder that converts to a video element when completed.

### `tf.insert.audioPlaceholder`

Inserts a placeholder that converts to an audio element when completed.

### `tf.insert.filePlaceholder`

Inserts a placeholder that converts to a file element when completed.

### `tf.insert.image`

Inserts an image element into the editor.

<API name="insertImage">
<APIParameters>
  <APIItem name="url" type="string | ArrayBuffer">
    The URL or ArrayBuffer of the image.
  </APIItem>
  <APIItem name="options" type="InsertNodesOptions" optional>
    Additional options for inserting the image element.
  </APIItem>
</APIParameters>

<APIOptions type="InsertImageOptions">
  <APIItem name="nextBlock" type="boolean" optional>
    If true, the image will be inserted in the next block.
  </APIItem>
</APIOptions>
</API>

### `tf.insert.mediaEmbed`

Inserts a media embed element at the current selection.

<API name="insertMediaEmbed">
<APIOptions type="InsertMediaEmbedOptions">
  <APIItem name="url" type="string" optional>
    The URL of the media embed.
    - **Default:** `''`
  </APIItem>
  <APIItem name="key" type="string" optional>
    The key of the media embed element.
    - **Default:** `KEYS.mediaEmbed`
  </APIItem>
  <APIItem name="insertNodesOptions" type="InsertNodesOptions" optional>
    Additional options for inserting nodes.
  </APIItem>
</APIOptions>
</API>

## Hooks

### `useResizable`

Handles the resizable properties of a media element.

<API name="useResizable">
<APIState>
  <APIItem name="align" type="'left' | 'center' | 'right'">
    The alignment of the content within the resizable element.
  </APIItem>
  <APIItem name="minWidth" type="ResizeLength">
    The minimum width that the resizable element can be adjusted to.
  </APIItem>
  <APIItem name="maxWidth" type="ResizeLength">
    The maximum width that the resizable element can be adjusted to.
  </APIItem>
  <APIItem name="setNodeWidth" type="(width: number | string) => void">
    Function to set the width of the node when resizing.
  </APIItem>
  <APIItem name="setWidth" type="(width: number | string) => void">
    Function to set the width of the resizable element directly.
  </APIItem>
  <APIItem name="width" type="Property.Width<string | number> | undefined">
    The current width of the resizable element (percentage, 'auto', or pixels).
  </APIItem>
</APIState>

<APIReturns type="object">
  <APIItem name="wrapperRef" type="React.RefObject<HTMLDivElement>">
    React reference to the outermost wrapper div.
  </APIItem>
  <APIItem name="wrapperProps.style" type="CSSProperties">
    CSS styles for the wrapper div.
  </APIItem>
  <APIItem name="props.style" type="CSSProperties">
    CSS styles for the resizable element.
  </APIItem>
  <APIItem name="context.onResize" type="() => void">
    Callback function called when the element is resized.
  </APIItem>
</APIReturns>
</API>

### `useMediaState`

A state hook for a media element.

<API name="useMediaState">
<APIParameters>
  <APIItem name="options.urlParsers" type="EmbedUrlParser[]" optional>
    Array of URL parsers to parse the media element URL.
  
    - **`EmbedUrlParser`:** `(url: string) => EmbedUrlData | undefined`
  </APIItem>
</APIParameters>

<APIReturns type="object">
  <APIItem name="align" type="string">
    The alignment of the media element.
  </APIItem>
  <APIItem name="focus" type="boolean">
    Whether the media element is currently focused.
  </APIItem>
  <APIItem name="selected" type="boolean">
    Whether the media element is currently selected.
  </APIItem>
  <APIItem name="readOnly" type="boolean">
    Whether the editor is in read-only mode.
  </APIItem>
  <APIItem name="embed" type="EmbedUrlData">
    The parsed embed data of the media element.
  </APIItem>
  <APIItem name="isTweet" type="boolean">
    Whether the media element is a tweet.
  </APIItem>
  <APIItem name="isVideo" type="boolean">
    Whether the media element is a video.
  </APIItem>
  <APIItem name="isYoutube" type="boolean">
    Whether the media element is a YouTube video.
  </APIItem>
</APIReturns>
</API>

### `useMediaToolbarButton`

A behavior hook for a media toolbar button.

<API name="useMediaToolbarButton">
<APIParameters>
  <APIItem name="options.nodeType" type="string" optional>
    The type of media node to insert.
  </APIItem>
</APIParameters>

<APIReturns type="object">
  <APIItem name="props.onClick" type="() => void">
    Callback function that inserts the media node and focuses the editor.
  </APIItem>
</APIReturns>
</API>

### `useFloatingMediaEditButton`

Handles the floating media edit button.

<API name="useFloatingMediaEditButton">
<APIReturns type="object">
  <APIItem name="props.onClick" type="() => void">
    Callback function to handle the button click.
  </APIItem>
</APIReturns>
</API>

### `useFloatingMediaUrlInput`

Handles the URL input field for media elements.

<API name="useFloatingMediaUrlInput">
<APIProps>
  <APIItem name="defaultValue" type="string">
    The default value for the URL input field.
  </APIItem>
</APIProps>

<APIReturns type="object">
  <APIItem name="props.onChange" type="() => void">
    Callback function to handle input changes.
  </APIItem>
  <APIItem name="props.autoFocus" type="boolean">
    Whether the URL input field should be focused on mount.
  </APIItem>
  <APIItem name="props.defaultValue" type="string">
    The default value for the URL input field.
  </APIItem>
</APIReturns>
</API>

### `useImage`

A hook for image elements.

<API name="useImage">
<APIReturns type="object">
  <APIItem name="props.src" type="string">
    The URL of the media element.
  </APIItem>
  <APIItem name="props.alt" type="string">
    The caption string for the image.
  </APIItem>
  <APIItem name="props.draggable" type="boolean">
    Whether the image is draggable.
  </APIItem>
</APIReturns>
</API>

## Utilities

### `parseMediaUrl`

Parses a media URL for plugin-specific handling.

<API name="parseMediaUrl">
<APIParameters>
  <APIItem name="options.pluginKey" type="string">
    The key of the media plugin.
  </APIItem>
  <APIItem name="options.url" type="string" optional>
    The URL of the media to be parsed.
  </APIItem>
</APIParameters>
</API>

### `parseVideoUrl`

Parses a video URL and extracts the video ID and provider-specific embed URL.

<API name="parseVideoUrl">
<APIParameters>
  <APIItem name="url" type="string">
    The video URL to parse.
  </APIItem>
</APIParameters>

<APIReturns type="EmbedUrlData | undefined">
  An object containing the video ID and provider if parsing is successful, undefined if URL is invalid or unsupported.
</APIReturns>
</API>

### `parseTwitterUrl`

Parses a Twitter URL and extracts the tweet ID.

<API name="parseTwitterUrl">
<APIParameters>
  <APIItem name="url" type="string">
    The Twitter URL.
  </APIItem>
</APIParameters>

<APIReturns>
  <APIItem type="EmbedUrlData | undefined">
    An object containing the tweet ID and provider if the parsing is successful.
    Returns undefined if the URL is not valid or does not match any supported video providers.
  </APIItem>
</APIReturns>
</API>

### `parseIframeUrl`

Parses the URL of an iframe embed.

<API name="parseIframeUrl">
<APIParameters>
  <APIItem name="url" type="string">
    The URL or embed code of the iframe.
  </APIItem>
</APIParameters>
</API>

### `isImageUrl`

Checks if a URL is a valid image URL.

<API name="isImageUrl">
<APIParameters>
  <APIItem name="url" type="string">
    The URL to check.
  </APIItem>
</APIParameters>

<APIReturns type="boolean">
  Whether the URL is a valid image URL.
</APIReturns>
</API>

### `submitFloatingMedia`

Submits a floating media element.

<API name="submitFloatingMedia">
<APIParameters>
  <APIItem name="options.element" type="TMediaElement">
    The floating media element to be submitted.
  </APIItem>
  <APIItem name="options.pluginKey" type="string" optional>
    The key of the media plugin.
  </APIItem>
</APIParameters>
</API>

### `withImageUpload`

Enhances the editor instance with image upload functionality.

<API name="withImageUpload">
<APIParameters>
  <APIItem name="plugin" type="PlatePlugin">
    The plate plugin.
  </APIItem>
</APIParameters>
</API>

### `withImageEmbed`

Enhances the editor instance with image-related functionality.

<API name="withImageEmbed">
<APIParameters>
  <APIItem name="plugin" type="PlatePlugin">
    The plate plugin.
  </APIItem>
</APIParameters>
</API>

## Types

### `TMediaElement`

```tsx
export interface TMediaElement extends TElement {
  url: string;
  id?: string;
  align?: 'center' | 'left' | 'right';
  isUpload?: boolean;
  name?: string;
  placeholderId?: string;
}
```

### `TPlaceholderElement`

```tsx
export interface TPlaceholderElement extends TElement {
  mediaType: string;
}
```

### `EmbedUrlData`

```tsx
export interface EmbedUrlData {
  url?: string;
  provider?: string;
  id?: string;
  component?: React.FC<EmbedUrlData>;
}
```


# Mention

Source: https://platejs.org/docs/mention

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Mention
description: Inline markable void mentions backed by trigger combobox input.
docs:
  - route: /docs/combobox
    title: Combobox
  - route: /docs/components/mention-node
    title: Mention Nodes
  - route: /docs/components/inline-combobox
    title: Inline Combobox
---

Mention turns trigger text such as `@` into an inline combobox input and inserts a markable void `mention` node when the user selects an item. The package owns trigger detection, input node creation, mention insertion, selection movement, and Markdown mention serialization. The registry owns the demo item list and the inline combobox UI.

[mention-demo registry content](https://platejs.org/r/mention-demo)

<PackageInfo>

## Features

- Inline void `mention` nodes with `value` and optional `key`.
- Inline void `mention_input` nodes created by trigger text.
- Trigger combobox support from `@platejs/combobox`.
- Configurable trigger strings, regexes, and trigger queries.
- Markable void rendering so bold, italic, and underline can style a mention.
- Optional trailing space after selected mention items.
- Markdown format through `[display text](mention:id)` plus bare `@name` deserialization.

</PackageInfo>

## Fast Path

<Steps>

### Add The Kit

`MentionKit` installs `MentionPlugin`, `MentionInputPlugin`, the registry mention nodes, and a trigger rule that allows `@` at the start of a line, after whitespace, or after quotes.

[mention-kit registry content](https://platejs.org/r/mention-kit)

```tsx
import { createPlateEditor } from 'platejs/react';

import { MentionKit } from '@/components/editor/plugins/mention-kit';

export const editor = createPlateEditor({
  plugins: MentionKit,
});
```

### Render Mentions

`mention-node` renders both the selected mention and the temporary combobox input. The demo data lives in that registry UI file, so replace it with your app users, pages, or records.

[mention-node registry content](https://platejs.org/r/mention-node)

### Add Static Rendering

`mention-base-kit` uses `BaseMentionPlugin` with the static mention node for read-only output.

[mention-base-kit registry content](https://platejs.org/r/mention-base-kit)

</Steps>

## Ownership

| Layer | Owner | What It Does |
|-------|-------|--------------|
| `@platejs/mention` | Package | Exports `BaseMentionPlugin`, `BaseMentionInputPlugin`, and `getMentionOnSelectItem`. |
| `@platejs/mention/react` | Package | Exports `MentionPlugin` and `MentionInputPlugin`. |
| `@platejs/combobox` | Package | Provides `withTriggerCombobox`, trigger options, and combobox input hooks. |
| `mention-kit` | Registry | Adds mention plugins with editable mention and input components. |
| `mention-base-kit` | Registry | Adds `BaseMentionPlugin.withComponent(MentionElementStatic)`. |
| `mention-node` | Registry UI | Renders mention atoms, the inline combobox input, and demo items. |
| `inline-combobox` | Registry UI | Renders the Ariakit-backed popover, input, groups, items, and empty state. |
| `@platejs/markdown` | Package | Serializes mentions as `mention:` links and deserializes mention links or bare mentions. |

## Manual Setup

<Steps>

### Install Package

```bash
npm install @platejs/mention
```

### Add Plugins

Configure the mention plugin with the trigger behavior and render both node types.

```tsx
import { MentionInputPlugin, MentionPlugin } from '@platejs/mention/react';
import { createPlateEditor } from 'platejs/react';

import {
  MentionElement,
  MentionInputElement,
} from '@/components/ui/mention-node';

export const editor = createPlateEditor({
  plugins: [
    MentionPlugin.configure({
      options: {
        triggerPreviousCharPattern: /^$|^[\s"']$/,
      },
    }).withComponent(MentionElement),
    MentionInputPlugin.withComponent(MentionInputElement),
  ],
});
```

### Select An Item

Use `getMentionOnSelectItem` from your combobox item renderer. It inserts the mention, moves the cursor after it, and inserts a trailing space only when `insertSpaceAfterMention` is enabled and the mention lands at the end of the block.

```tsx
import { getMentionOnSelectItem } from '@platejs/mention';

const onSelectItem = getMentionOnSelectItem();

<InlineComboboxItem
  value={item.text}
  onClick={() => onSelectItem(editor, item, search)}
>
  {item.text}
</InlineComboboxItem>;
```

</Steps>

## Value Shape

`BaseMentionPlugin` uses `KEYS.mention`, which resolves to the `mention` node type. The input plugin uses `KEYS.mentionInput`, which resolves to `mention_input`.

```tsx
const value = [
  {
    children: [
      { text: 'Assigned to ' },
      {
        children: [{ text: '' }],
        key: 'user_123',
        type: 'mention',
        value: 'Jane Smith',
      },
      { text: '.' },
    ],
    type: 'p',
  },
];
```

| Field | Type | Notes |
|-------|------|-------|
| `type` | `'mention'` | Inline void mention node. |
| `value` | `string` | Display text rendered by the registry node. |
| `key` | `unknown` | Optional stable id used by selection handlers and Markdown serialization. |
| `children` | `[{ text: '' }]` | Empty child required for Slate inline void nodes. |

The mention node is `isMarkableVoid`, so marks on its empty child can style the rendered mention.

## Trigger Flow

`withTriggerCombobox` overrides `insertText`. It creates a combobox input only when every gate passes.

| Gate | Source |
|------|--------|
| Inserted text matches `trigger` | `string`, `string[]`, or `RegExp`. |
| Insert is not using `options.at` | Programmatic text insertion bypasses the trigger. |
| Editor has a selection | No selection means no inline input target. |
| `triggerQuery(editor)` returns true | Optional app veto for custom contexts. |
| Previous character matches `triggerPreviousCharPattern` | Defaults to `/^\s?$/`; registry kit uses `/^$\|^[\s"']$/`. |

The default `createComboboxInput` creates:

```tsx
{
  children: [{ text: '' }],
  trigger: '@',
  type: KEYS.mentionInput,
}
```

If `editor.meta.userId` exists, the combobox input stores that `userId` so only the creator sees the transient input in collaborative editors.

## Markdown

`@platejs/markdown` serializes mentions as link-style `mention:` URLs. It uses `key` for the URL when present and `value` for the visible text.

```md
Hello [Jane Smith](mention:user_123).
```

Deserialization supports link-style mentions and bare `@alice` text. Normal links such as `[@docs](/docs/mention)` stay links.

## API Reference

| API | Package | Use |
|-----|---------|-----|
| `BaseMentionPlugin` | `@platejs/mention` | Headless inline markable void mention plugin with trigger-combobox behavior. |
| `BaseMentionInputPlugin` | `@platejs/mention` | Inline void input node inserted while the combobox is active. |
| `MentionPlugin` | `@platejs/mention/react` | React mention plugin. |
| `MentionInputPlugin` | `@platejs/mention/react` | React mention input plugin. |
| `editor.tf.insert.mention({ key, value })` | `BaseMentionPlugin` transform | Inserts the mention node at the current selection. |
| `getMentionOnSelectItem({ key? })` | `@platejs/mention` | Returns an item handler for mention combobox selection. |
| `withTriggerCombobox` | `@platejs/combobox` | Creates temporary combobox input nodes from trigger text. |
| `useComboboxInput` | `@platejs/combobox/react` | Handles focus, cancellation, arrow/backspace/escape behavior, and undo/redo forwarding for custom input UI. |


# Table

Source: https://platejs.org/docs/table

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Table
docs:
  - route: https://pro.platejs.org/docs/examples/table
    title: Plus
  - route: /docs/components/table-toolbar-button
    title: Table Toolbar Button
  - route: /docs/components/table-node
    title: Table Nodes
---

[table-demo registry content](https://platejs.org/r/table-demo)

<PackageInfo>

## Features

- Enables creation and editing of tables with advanced behaviors.
- Arrow navigation (up/down).
- Grid cell selection.
- Cell selection expansion with `Shift+Arrow` keys.
- Copying and pasting cells.
- Row drag-and-drop reordering
- Row selection via drag handle

</PackageInfo>

## Kit Usage

<Steps>

### Installation

The fastest way to add table functionality is with the `TableKit`, which includes pre-configured `TablePlugin`, `TableRowPlugin`, `TableCellPlugin`, and `TableCellHeaderPlugin` with their [Plate UI](/docs/installation/plate-ui) components.

[table-kit registry content](https://platejs.org/r/table-kit)

- [`TableElement`](/docs/components/table-node): Renders table containers.
- [`TableRowElement`](/docs/components/table-node): Renders table rows.
- [`TableCellElement`](/docs/components/table-node): Renders table cells.
- [`TableCellHeaderElement`](/docs/components/table-node): Renders table header cells.

### Add Kit

Add the kit to your plugins:

```tsx
import { createPlateEditor } from 'platejs/react';
import { TableKit } from '@/components/editor/plugins/table-kit';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    ...TableKit,
  ],
});
```

</Steps>

## Manual Usage

<Steps>

### Installation

```bash
npm install @platejs/table
```

### Add Plugin

Include `TablePlugin` in your Plate plugins array when creating the editor.

```tsx
import { TablePlugin } from '@platejs/table/react';
import { createPlateEditor } from 'platejs/react';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    TablePlugin,
  ],
});
```

### Configure Plugins

Configure the table plugins with custom components and options.

```tsx
import {
  TableCellHeaderPlugin,
  TableCellPlugin,
  TablePlugin,
  TableRowPlugin,
} from '@platejs/table/react';
import { createPlateEditor } from 'platejs/react';
import {
  TableCellElement,
  TableCellHeaderElement,
  TableElement,
  TableRowElement,
} from '@/components/ui/table-node';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    TablePlugin.configure({
      node: { component: TableElement },
      options: {
        initialTableWidth: 600,
        disableMerge: false,
        minColumnWidth: 48,
      },
    }),
    TableRowPlugin.withComponent(TableRowElement),
    TableCellPlugin.withComponent(TableCellElement),
    TableCellHeaderPlugin.withComponent(TableCellHeaderElement),
  ],
});
```

- `node.component`: Assigns [`TableElement`](/docs/components/table-node) to render table containers.
- `withComponent`: Assigns components for table rows, cells, and header cells.
- `options.initialTableWidth`: Sets the initial width for new tables.
- `options.disableMerge`: Disables cell merging functionality.
- `options.minColumnWidth`: Sets the minimum width for table columns.

### Add Toolbar Button

You can add [`TableToolbarButton`](/docs/components/table-toolbar-button) to your [Toolbar](/docs/toolbar) to insert tables.

### Insert Toolbar Button

You can add this item to the [Insert Toolbar Button](/docs/toolbar#insert-toolbar-button) to insert table elements:

```tsx
{
  icon: <TableIcon />,
  label: 'Table',
  value: KEYS.table,
}
```

### Disable Merging Example

[table-nomerge-demo registry content](https://platejs.org/r/table-nomerge-demo)

</Steps>

## Plugins

### TablePlugin

<API name="TablePlugin">
<APIOptions>
  <APIItem name="disableMerge" type="boolean" optional>
    Disables the merging behavior of cells.
  </APIItem>
  <APIItem name="disableExpandOnInsert" type="boolean" optional>
    Disables the expansion of the table when inserting cells.
  </APIItem>
  <APIItem name="disableMarginLeft" type="boolean" optional>
    Disables the left resizer of the first column in the table.
  </APIItem>
  <APIItem name="enableUnsetSingleColSize" type="boolean" optional>
    Disables unsetting the width of the first column when the table has only one column. Set this to `true` if you want to resize the table width when there's only one column. Leave it `false` if you have a full-width table.
  </APIItem>
  <APIItem name="initialTableWidth" type="number" optional>
    If defined, a normalizer will set each undefined table `colSizes` to this value divided by the number of columns. Note that merged cells are not yet supported.
  </APIItem>
  <APIItem name="minColumnWidth" type="number" optional>
    The minimum width of a column in the table.
    - **Default:** `48`
  </APIItem>
</APIOptions>
</API>

### TableRowPlugin

Plugin for table rows.

### TableCellPlugin

Plugin for table cells.

### TableCellHeaderPlugin

Plugin for table header cells.

## API

### editor.api.create.table

<API name="create.table">
<APIParameters>
<APIItem name="options" type="GetEmptyTableNodeOptions" optional>
Extends `GetEmptyRowNodeOptions`.
</APIItem>
</APIParameters>

<APIOptions>
<APIItem name="header" type="boolean" optional>
Specify `true` if the table has a header row.
</APIItem>
<APIItem name="rowCount" type="number" optional>
The number of rows in the table.

- **Default:** `0`

</APIItem>
<APIItem name="colCount" type="number | undefined" optional>
The number of columns in the table.
</APIItem>
</APIOptions>

<APIReturns>
<APIItem type="TElement">

The table node.

</APIItem>
</APIReturns>
</API>

### editor.api.create.tableCell

Creates an empty cell node for a table.

<API name="create.tableCell">
<APIOptions>
<APIItem name="header" type="boolean" optional>
Specify `true` if the cell is a header cell.
</APIItem>
<APIItem name="row" type="TTableRowElement" optional>
The row element. If `header` is not specified, it will determine if the cell is a header cell based on the row's children.
</APIItem>
<APIItem name="children" type="Descendant[]" optional>
The children of the new cell node.

- **Default:** `[editor.api.create.block()]`

</APIItem>
</APIOptions>

<APIReturns>
<APIItem type="TElement">

The cell node.

</APIItem>
</APIReturns>
</API>

### editor.api.create.tableRow

Creates an empty row node with the specified number of columns.

<API name="create.tableRow">
<APIOptions>
<APIItem name="header" type="boolean" optional>
Specify `true` if the row is a header row.
</APIItem>
<APIItem name="colCount" type="number" optional>
The number of columns in the row.

- **Default:** `1`

</APIItem>
</APIOptions>

<APIReturns>
<APIItem type="TElement">

The row node.

</APIItem>
</APIReturns>
</API>

### editor.api.table.getCellBorders

Gets the border styles for a table cell, handling special cases for first row and first column cells.

<API name="getCellBorders">
<APIOptions>
<APIItem name="element" type="TTableCellElement">
The table cell element to get the border styles for.
</APIItem>
<APIItem name="defaultBorder" type="Required<TTableCellElementBorder>" optional>
The default border style to use when cell borders are not defined.
<APISubList>
<APISubListItem parent="defaultBorder" name="color" type="string">
  The border color.
  - **Default:** `'rgb(209 213 219)'`
</APISubListItem>
<APISubListItem parent="defaultBorder" name="size" type="number">
  The border size.
  - **Default:** `1`
</APISubListItem>
<APISubListItem parent="defaultBorder" name="style" type="string">
  The border style.
  - **Default:** `'solid'`
</APISubListItem>
</APISubList>
</APIItem>
</APIOptions>

<APIReturns>
  <APIItem type="BorderStylesDefault">
    An object containing:
    <APISubList>
      <APISubListItem parent="return" name="bottom" type="Required<TTableCellElementBorder>">
        The bottom border style.
      </APISubListItem>
      <APISubListItem parent="return" name="right" type="Required<TTableCellElementBorder>">
        The right border style.
      </APISubListItem>
      <APISubListItem parent="return" name="left" type="Required<TTableCellElementBorder>" optional>
        The left border style. Only present for cells in the first column.
      </APISubListItem>
      <APISubListItem parent="return" name="top" type="Required<TTableCellElementBorder>" optional>
        The top border style. Only present for cells in the first row.
      </APISubListItem>
    </APISubList>
  </APIItem>
</APIReturns>
</API>

### editor.api.table.getCellChildren

Gets the children of a table cell.

<API name="getCellChildren">
<APIParameters>
<APIItem name="cell" type="TElement">
The table cell element.
</APIItem>
</APIParameters>

<APIReturns>
<APIItem type="Descendant[]">

The children of the table cell.

</APIItem>
</APIReturns>
</API>

### editor.api.table.getCellSize

Gets the width and minimum height of a table cell, taking into account column spans and column sizes.

<API name="getCellSize">
<APIOptions>
<APIItem name="element" type="TTableCellElement">
The table cell element to get the size for.
</APIItem>
<APIItem name="colSizes" type="number[]" optional>
Optional array of column sizes. If not provided, will use the table's overridden column sizes.
</APIItem>
</APIOptions>

<APIReturns>
<APIItem name="width" type="number">
The total width of the cell, calculated by summing the widths of all columns it spans.
</APIItem>
<APIItem name="minHeight" type="number | undefined">
The minimum height of the cell, derived from the row's size property.
</APIItem>
</APIReturns>
</API>

### editor.api.table.getColSpan

Gets the column span of a table cell.

<API name="getColSpan">
<APIParameters>
<APIItem name="element" type="TTableCellElement">
The table cell element to get the column span for.
</APIItem>
</APIParameters>

<APIReturns>
  <APIItem type="number">
    The number of columns this cell spans.
    - **Default:** `1`
  </APIItem>
</APIReturns>
</API>  

### editor.api.table.getRowSpan

Gets the row span of a table cell.

<API name="getRowSpan">
<APIParameters>
  <APIItem name="element" type="TTableCellElement">
    The table cell element to get the row span for.
  </APIItem>
</APIParameters>

<APIReturns>
  <APIItem type="number">
    The number of rows this cell spans.
    - **Default:** `1`
  </APIItem>
</APIReturns>
</API>

### getCellType

Get the plugin cell types.

<API name="getCellType">
<APIReturns>

<APIItem type="string[]">
  An array of element types for table cells (td and th) in the editor.
</APIItem>

</APIReturns>
</API>

### getNextTableCell

Gets the next cell in the table.
  
<API name="getNextTableCell">
<APIParameters>
  <APIItem name="currentCell" type="NodeEntry">
    The entry of the current cell.
  </APIItem>
  <APIItem name="currentPath" type="Path">
    The path of the current cell.
  </APIItem>
  <APIItem name="currentRow" type="NodeEntry">
    The entry of the current row.
  </APIItem>
</APIParameters>

<APIReturns>
  <APIItem type="NodeEntry | undefined">
    The node entry of the cell in the next row, or `undefined` if the current
    row is the last row.
  </APIItem>
</APIReturns>
</API>

### getPreviousTableCell

Gets the previous cell in the table.

<API name="getPreviousTableCell">
<APIParameters>
  <APIItem name="currentCell" type="NodeEntry">
    The entry of the current cell.
  </APIItem>
  <APIItem name="currentPath" type="Path">
    The path of the current cell.
  </APIItem>
  <APIItem name="currentRow" type="NodeEntry">
    The entry of the current row.
  </APIItem>
</APIParameters>

<APIReturns>
  <APIItem type="NodeEntry | undefined">
    The node entry of the cell in the previous row, or `undefined` if the
    current row is the first row.
  </APIItem>
</APIReturns>
</API>

### getTableColumnCount

Gets the number of columns in a table.

<API name="getTableColumnCount">
<APIParameters>
  <APIItem name="tableNode" type="TElement">
    The table node for which to retrieve the column count.
  </APIItem>
</APIParameters>

<APIReturns>
<APIItem type="number">

The number of columns in the table.

</APIItem>
</APIReturns>
</API>
### getTableColumnIndex

Gets the column index of a cell node within a table.

<API name="getTableColumnIndex">
<APIParameters>
  <APIItem name="cellNode" type="TElement">
    The cell node for which to retrieve the column index.
  </APIItem>
</APIParameters>

<APIReturns>
<APIItem type="number">

The column index of the cell node.

</APIItem>
</APIReturns>
</API>

### getTableEntries

Gets the table, row, and cell node entries based on the current selection or a specified location.

<API name="getTableEntries">
<APIOptions>
<APIItem name="at" type="Location | null" optional>
The location where the table cell is located.

- **Default:** `editor.selection`
</APIItem>
</APIOptions>

<APIReturns>
  <APIItem name="table" type="NodeEntry | undefined">
    The table node entry.
  </APIItem>
  <APIItem name="row" type="NodeEntry | undefined">
    The row node entry.
  </APIItem>
  <APIItem name="cell" type="NodeEntry | undefined">
    The cell node entry.
  </APIItem>
</APIReturns>
</API>


### getTableGridAbove

Gets the sub table above the anchor and focus positions based on the specified format (tables or cells).

<API name="getTableGridAbove">
<APIOptions>
<APIItem name="format" type="string" optional>
The format of the sub table to retrieve.

- **Default:** `'table'`

</APIItem>
</APIOptions>

<APIReturns>
  <APIItem type="ElementEntry[]">The sub table entries.</APIItem>
</APIReturns>
</API>
### getTableGridByRange

Gets the sub table between two cell paths within a given range.

<API name="getTableGridByRange">
<APIOptions>
<APIItem name="at" type="TRange">
The range specifying the start and end cell paths.
</APIItem>
<APIItem name="format" type="'table' | 'cell'" optional>
The format of the output.

- **Default:** `'table'`

</APIItem>
</APIOptions>

<APIReturns>
  <APIItem type="ElementEntry[]">The sub table entries.</APIItem>
</APIReturns>
</API>

### getTableRowIndex

Gets the row index of a cell node within a table.

<API name="getTableRowIndex">
<APIParameters>
  <APIItem name="cellNode" type="TElement">
    The cell node for which to retrieve the row index.
  </APIItem>
</APIParameters>

<APIReturns>
<APIItem type="number">

The row index of the cell node.

</APIItem>
</APIReturns>
</API>

### getTopTableCell

Gets the cell above the current cell in the table.

<API name="getTopTableCell">
<APIParameters>
  <APIItem name="at" type="Path" optional>
    The path to the current cell. If not provided, the function will search for
    the current cell in the editor.
  </APIItem>
</APIParameters>

<APIReturns>
<APIItem type="ElementEntry | undefined">

The cell node entry.

</APIItem>
</APIReturns>
</API>
### isTableBorderHidden

Checks if the border of a table cell or the table itself is hidden based on the specified border direction.

<API name="isTableBorderHidden">
<APIParameters>
  <APIItem name="border" type="'top' | 'left' | 'bottom' | 'right'">
    The border direction to check.
  </APIItem>
</APIParameters>

<APIReturns>
<APIItem type="boolean">

`true` if the border is hidden, `false` otherwise.

</APIItem>
</APIReturns>
</API>

## Editing Behavior

Table editing behavior is split across table transforms and plugin extensions. Use `tf.table.merge` and `tf.table.split` for merge controls, `tf.moveSelectionFromCell` for keyboard navigation out of cells, and the table extension hooks below for deletion, paste, normalization, and fragment handling.

## Transforms

### `tf.insert.table`

Inserts a table at the current selection if there is no existing table in the editor. Selects the start of the inserted table.

<API name="insert.table">
<APIParameters>
<APIItem name="getEmptyTableNodeOptions" type="GetEmptyTableNodeOptions" optional>
Extends `GetEmptyRowNodeOptions`.
<APISubList>
<APISubListItem parent="getEmptyTableNodeOptions" name="rowCount" type="number" optional>
The number of rows in the table.

- **Default:** `2`

</APISubListItem>
<APISubListItem parent="getEmptyTableNodeOptions" name="colCount" type="number" optional>
The number of columns in the table.

- **Default:** `2`

</APISubListItem>
<APISubListItem parent="getEmptyTableNodeOptions" name="header" type="boolean" optional>
If `true`, the first row of the table will be treated as a header row.
</APISubListItem>
</APISubList>

</APIItem>

<APIItem name="options" type="InsertNodesOptions" optional>
The options for inserting the table nodes.
</APIItem>
</APIParameters>
</API>

### `tf.insert.tableColumn`

Inserts a column into the table at the current selection or a specified cell path.

<API name="insert.tableColumn">
<APIOptions>
<APIItem name="at" type="Path" optional>
The exact path of the cell to insert the column at. This overrules the
`fromCell` option.
</APIItem>
<APIItem name="before" type="boolean" optional>
If true, insert the column before the current column instead of after.
</APIItem>
<APIItem name="fromCell" type="Path" optional>
The path of the cell to insert the column from.
</APIItem>
<APIItem name="header" type="boolean" optional>
If true, the inserted column will be treated as a header column.
</APIItem>
<APIItem name="select" type="boolean" optional>
If true, the inserted column will be selected after insertion.
</APIItem>
</APIOptions>
</API>

### `tf.insert.tableRow`

Inserts a row into the table at the current selection or a specified row path.

<API name="insert.tableRow">
<APIOptions>
<APIItem name="at" type="Path" optional>
Exact path of the row to insert the column at. Pass the table path to
insert at the end of the table. Will overrule `fromRow`.
</APIItem>
<APIItem name="before" type="boolean" optional>
If true, insert the row before the current row instead of after.
</APIItem>
<APIItem name="fromRow" type="Path" optional>
The path of the row to insert the new row from.
</APIItem>
<APIItem name="header" type="boolean" optional>
If true, the inserted row will be treated as a header row.
</APIItem>
<APIItem name="select" type="boolean" optional>
If true, the inserted row will be selected after insertion.
</APIItem>
</APIOptions>
</API>

### `tf.remove.tableColumn`

Deletes the column containing the selected cell in a table.

### `tf.remove.tableRow`

Deletes the row containing the selected cell in a table.

### `tf.remove.table`

Deletes the entire table.

### `tf.table.merge`

Merges multiple selected cells into one.

The merged cell will:
- Have a colSpan equal to the number of columns spanned by the selected cells
- Have a rowSpan equal to the number of rows spanned by the selected cells
- Contain the combined content of all merged cells (non-empty cells only)
- Inherit the header status from the first selected cell

### `tf.table.split`

Splits a merged cell back into individual cells.

The split operation will:
- Create new cells for each column and row that was spanned
- Copy the header status from the original merged cell
- Place the original cell's content in the first cell
- Create empty cells for the remaining spaces

### `tf.moveSelectionFromCell`

Moves the selection by cell unit within a table.

<API name="moveSelectionFromCell">
<APIOptions>
<APIItem name="at" type="Location" optional>
The location to move the selection from.
</APIItem>
<APIItem name="reverse" type="boolean" optional>
        Set to `true` to move the selection to the cell above, `false` to move
the selection to the cell below.
</APIItem>
<APIItem name="edge" type="'top' | 'left' | 'right' | 'bottom'" optional>
The edge to expand the cell selection to.
</APIItem>
<APIItem name="fromOneCell" type="boolean" optional>
Set to `true` to move the selection from only one selected cell.
</APIItem>
</APIOptions>
</API>

### `tf.setBorderSize`

Sets the size of the specified border in a table cell.

<API name="setBorderSize">
<APIParameters>
<APIItem name="size" type="number">
The size of the border.
</APIItem>
<APIItem name="options" type="object" optional>
Options for setting the border size.
</APIItem>
</APIParameters>

<APIOptions>
<APIItem name="at" type="Location" optional>
The location of the cell to set the border size.
</APIItem>
<APIItem name="border" type="'all' | 'top' | 'left' | 'bottom' | 'right'" optional>
The border direction to set the size.

- **Default:** `'all'`

</APIItem>
</APIOptions>
</API>

### `tf.setTableColSize`

Sets the width of a specific column in a table.

<API name="setTableColSize">
<APIOptions>
<APIItem name="colIndex" type="number" optional>
The index of the column to set the width.
</APIItem>
<APIItem name="width" type="number" optional>
The desired width of the column.
</APIItem>
<APIItem name="getAboveNodeOptions" type="EditorAboveOptions" optional>
Additional options for finding the table node.
</APIItem>
</APIOptions>
</API>

### `tf.setTableMarginLeft`

Sets the margin left of a table.

<API name="setTableMarginLeft">
<APIOptions>
<APIItem name="marginLeft" type="number">
An object containing the desired margin left value.
</APIItem>
<APIItem name="getAboveNodeOptions" type="EditorAboveOptions" optional>
Additional options for finding the table node.
</APIItem>
</APIOptions>
</API>

### `tf.setTableRowSize`

Sets the size (height) of a table row.

<API name="setTableRowSize">
<APIOptions>
<APIItem name="rowIndex" type="number">
The index of the row to set the size.
</APIItem>
<APIItem name="height" type="number">
The desired height of the row.
</APIItem>
<APIItem name="getAboveNodeOptions" type="EditorAboveOptions" optional>
Additional options for finding the table node.
</APIItem>
</APIOptions>
</API>

## Plugin Extensions

### `onKeyDownTable`

Handles the keyboard events for tables.

<API name="onKeyDownTable">
<APIParameters>
  <APIItem name="plugin" type="PlatePlugin">
    The plate plugin.
  </APIItem>
</APIParameters>

<APIReturns>
  <APIItem type="KeyboardHandlerReturnType">
    The keyboard handler return type.
  </APIItem>
</APIReturns>
</API>

### `withDeleteTable`

Prevents the deletion of cells in tables.

### `withGetFragmentTable`

If the selection is inside a table, it retrieves the subtable above the selection as the fragment. This is useful when copying and pasting table cells.

### `withInsertFragmentTable`

If inserting a table:

- If the block above the anchor of the selection is a table, replace each cell above with the inserted table until out of bounds. Select the inserted cells.
- If there is no table above the anchor, check if the selection is inside a table. If it is, find the cell at the anchor position and replace its children with the inserted fragment.

### `withInsertTextTable`

If the selection is expanded:

- Check if the selection is inside a table. If it is, collapse the selection to the focus edge.

### `withNormalizeTable`

Normalize table structure by performing the following actions:

- Wrap cell children in a paragraph if they are texts.
- Unwrap nodes that are not valid table elements.
- Set initial column sizes for tables if specified.

### `withSelectionTable`

Handle table selections by performing the following actions:

- Adjust the focus of the selection when the anchor is inside a table and the focus is in a block before or after the table.
- Adjust the focus of the selection when the focus is inside a table and the anchor is in a block before or after the table.
- Override the selection from a cell if the previous and new selections are in different cells.

### `withSetFragmentDataTable`

Handle setting data to the clipboard when copying or cutting table data by performing the following actions:

- Check if a table entry and selected cell entries exist.
- Handle single-cell copy or cut operations by copying the cell content instead of the table structure.
- Create a table structure with the selected cells' content.
- Set the text, HTML, CSV, TSV, and Slate fragment data to the clipboard.

### `withTable`

Enhance the editor instance with table-related functionality by applying the following higher-order functions:

- `withNormalizeTable`: Normalize table structure and content.
- `withDeleteTable`: Prevent cell deletion within a table.
- `withGetFragmentTable`: Handle getting the fragment data when copying or cutting table cells.
- `withInsertFragmentTable`: Handle inserting table fragments.
- `withInsertTextTable`: Handle inserting text within a table.
- `withSelectionTable`: Handle adjusting the selection within a table.
- `withSetFragmentDataTable`: Handle setting the fragment data when copying or cutting table data.

## Hooks

### `useTableCellElementResizable`

A hook that provides resizing functionality for table cell elements.

<API name="useTableCellElementResizable">
<APIOptions type="TableCellElementResizableOptions">
<APIItem name="colIndex" type="number">
The index of the column.
</APIItem>
<APIItem name="colSpan" type="number">
The number of columns this cell spans.
</APIItem>
<APIItem name="rowIndex" type="number">
        The index of the row.
</APIItem>
<APIItem name="step" type="number" optional>
Resize by step instead of by pixel.
</APIItem>
<APIItem name="stepX" type="number" optional>
Step size for horizontal resizing.
</APIItem>
<APIItem name="stepY" type="number" optional>
Step size for vertical resizing.

- **Default:** `step`

</APIItem>
</APIOptions>

<APIReturns>
  <APIItem name="bottomProps" type="ResizeHandleProps">
    Props for the bottom resize handle, including resize direction and handler.
  </APIItem>
  <APIItem name="hiddenLeft" type="boolean">
    Whether the left resize handle should be hidden. True if not the first column or margin left is disabled.
  </APIItem>
  <APIItem name="leftProps" type="ResizeHandleProps">
    Props for the left resize handle, including resize direction and handler.
  </APIItem>
  <APIItem name="rightProps" type="ResizeHandleProps">
    Props for the right resize handle, including resize direction, initial size, and handler.
  </APIItem>
</APIReturns>
</API>
  

### `useTableStore`

The table store stores the state of the table plugin.

<API name="useTableStore">
<APIAttributes>
  <APIItem name="colSizeOverrides" type="TableStoreSizeOverrides">
    The column size overrides.
  </APIItem>
  <APIItem name="rowSizeOverrides" type="TableStoreSizeOverrides">
    The row size overrides.
  </APIItem>
  <APIItem name="marginLeftOverride" type="number | null">
    The margin left override.
  </APIItem>
  <APIItem name="selectedCells" type="TElement[] | null">
    The selected cells.
  </APIItem>
  <APIItem name="selectedTables" type="TElement[] | null">
    The selected tables.
  </APIItem>
</APIAttributes>
</API>

### `useIsCellSelected`

Custom hook that checks if a table cell is selected.

<API name="useIsCellSelected">
<APIParameters>
  <APIItem name="element" type="TElement">
    The table cell element to check.
  </APIItem>
</APIParameters>
</API>

### `useSelectedCells`

A hook that manages the selection of cells in a table.

It keeps track of the currently selected cells and updates them based on changes in editor selection.

### `useTableBordersDropdownMenuContentState`

A state hook for the table borders dropdown menu content.

<API name="useTableBordersDropdownMenuContentState">
<APIReturns>
An object with the following properties:
<APIItem name="hasBottomBorder" type="boolean">
Indicates whether the selected table cells have a bottom border.
</APIItem>
<APIItem name="hasTopBorder" type="boolean">
Indicates whether the selected table cells have a top border.
</APIItem>
<APIItem name="hasLeftBorder" type="boolean">
Indicates whether the selected table cells have a left border.
</APIItem>
<APIItem name="hasRightBorder" type="boolean">
Indicates whether the selected table cells have a right border.
</APIItem>
<APIItem name="hasNoBorders" type="boolean">
Indicates whether the selected table cells have no borders.
</APIItem>
<APIItem name="hasOuterBorders" type="boolean">
Indicates whether the selected table cells have outer borders (i.e.,
borders on all sides).
</APIItem>
<APIItem
  name="getOnSelectTableBorder"
  type="function"
>
A factory function that returns the `onSelectTableBorder` handler for a
specific border type.

- The `onSelectTableBorder` handler is responsible for setting the border style for the selected table cells.

</APIItem>
</APIReturns>
</API>

### `useTableColSizes`

Custom hook that returns the column sizes of a table with overrides applied. If the `colCount` of the table updates to 1 and the `enableUnsetSingleColSize` option is enabled, it unsets the `colSizes` node.

<API name="useTableColSizes">
<APIOptions>
<APIItem name="disableOverrides" type="boolean" optional>
If `true`, disables applying overrides to the column sizes.
- **Default:** `false`
</APIItem>
</APIOptions>

<APIReturns>
  <APIItem name="overriddenColSizes" type="number[]">
    The column sizes of the table with overrides applied.
  </APIItem>
</APIReturns>
</API>

### `useTableElement`

A hook for a table element that handles cell selection and margin left calculations.

<API name="useTableElement">
<APIReturns>
  <APIItem name="isSelectingCell" type="boolean">
    Whether cells are currently being selected.
  </APIItem>
  <APIItem name="marginLeft" type="number">
    The margin left of the table, considering overrides and plugin options.
  </APIItem>
  <APIItem name="props" type="object">
    Props for the table element:
    <APISubList>
      <APISubListItem parent="props" name="onMouseDown" type="function">
        Handler that collapses selection when clicking on the table while cells are selected.
      </APISubListItem>
    </APISubList>
  </APIItem>
</APIReturns>
</API>
  
### `useTableCellElement`

A hook for a table cell element that provides state and functionality for table cells.

<API name="useTableCellElement">
<APIReturns>
  <APIItem name="borders" type="BorderStylesDefault">
    The border styles of the table cell.
  </APIItem>
  <APIItem name="colIndex" type="number">
    The ending column index (considering colSpan).
  </APIItem>
  <APIItem name="colSpan" type="number">
    The number of columns this cell spans.
  </APIItem>
  <APIItem name="isSelectingCell" type="boolean">
    Whether cells are currently being selected.
  </APIItem>
  <APIItem name="minHeight" type="number | undefined">
    The minimum height of the cell.
  </APIItem>
  <APIItem name="rowIndex" type="number">
    The ending row index (considering rowSpan).
  </APIItem>
  <APIItem name="selected" type="boolean">
    Whether this cell is currently selected.
  </APIItem>
  <APIItem name="width" type="number | string">
    The width of the cell.
  </APIItem>
</APIReturns>
</API>

### `useTableCellBorders`

A hook that returns the border styles for a table cell.

<API name="useTableCellBorders">
<APIReturns>
  <APIItem type="BorderStylesDefault">
    An object containing the border styles for the cell:
    <APISubList>
      <APISubListItem parent="return" name="bottom" type="Required<TTableCellElementBorder>">
        The bottom border style.
      </APISubListItem>
      <APISubListItem parent="return" name="right" type="Required<TTableCellElementBorder>">
        The right border style.
      </APISubListItem>
      <APISubListItem parent="return" name="left" type="Required<TTableCellElementBorder>" optional>
        The left border style. Only present for cells in the first column.
      </APISubListItem>
      <APISubListItem parent="return" name="top" type="Required<TTableCellElementBorder>" optional>
        The top border style. Only present for cells in the first row.
      </APISubListItem>
    </APISubList>
  </APIItem>
</APIReturns>
</API>

### `useTableCellSize`

A hook that returns the size (width and minimum height) of a table cell.

<API name="useTableCellSize">
<APIReturns>
  <APIItem type="object">
    An object containing:
    <APISubList>
      <APISubListItem parent="return" name="width" type="number">
        The total width of the cell, calculated by summing the widths of all columns it spans.
      </APISubListItem>
      <APISubListItem parent="return" name="minHeight" type="number | undefined">
        The minimum height of the cell, derived from the row's size property.
      </APISubListItem>
    </APISubList>
  </APIItem>
</APIReturns>
</API>


# Table of Contents

Source: https://platejs.org/docs/toc

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Table of Contents
docs:
  - route: https://pro.platejs.org/docs/examples/toc
    title: Plus
  - route: components/toc-node
    title: Toc Element
---

[toc-demo registry content](https://platejs.org/r/toc-demo)

<PackageInfo>

## Features

- Automatically generates a table of contents from document headings
- Smooth scrolling to headings
- Active section tracking for the current heading while you scroll
- Keyboard-accessible heading navigation with `Enter` and `Space`

</PackageInfo>

## Kit Usage

<Steps>

### Installation

The fastest way to add table of contents functionality is with the `TocKit`, which includes pre-configured `TocPlugin` with the [Plate UI](/docs/installation/plate-ui) component.

[toc-kit registry content](https://platejs.org/r/toc-kit)

- [`TocElement`](/docs/components/toc-node): Renders table of contents elements.

### Add Kit

Add the kit to your plugins:

```tsx
import { createPlateEditor } from 'platejs/react';
import { TocKit } from '@/components/editor/plugins/toc-kit';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    ...TocKit,
  ],
});
```

</Steps>

## Manual Usage

<Steps>

### Installation

```bash
npm install @platejs/basic-nodes @platejs/toc
```

### Add Plugins

Include `TocPlugin` and `HnPlugin` in your Plate plugins array when creating the editor.

```tsx
import { TocPlugin } from '@platejs/toc/react';
import { H1Plugin, H2Plugin, H3Plugin } from '@platejs/basic-nodes/react';
import { createPlateEditor } from 'platejs/react';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    H1Plugin,
    H2Plugin,
    H3Plugin,
    TocPlugin,
  ],
});
```

### Configure Plugin

Configure the `TocPlugin` with custom component and scroll options.

```tsx
import { TocPlugin } from '@platejs/toc/react';
import { H1Plugin, H2Plugin, H3Plugin } from '@platejs/basic-nodes/react';
import { createPlateEditor } from 'platejs/react';
import { TocElement } from '@/components/ui/toc-node';
import { H1Element, H2Element, H3Element } from '@/components/ui/heading-node';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    H1Plugin.withComponent(H1Element),
    H2Plugin.withComponent(H2Element),
    H3Plugin.withComponent(H3Element),
    TocPlugin.configure({
      node: { component: TocElement },
      options: {
        topOffset: 80,
        isScroll: true,
      },
    }),
  ],
});
```

- `node.component`: Assigns [`TocElement`](/docs/components/toc-node) to render table of contents elements.
- `options.topOffset`: Sets the top offset when scrolling to headings.
- `options.isScroll`: Enables scrolling behavior to headings.

### Insert Toolbar Button

You can add this item to the [Insert Toolbar Button](/docs/toolbar#insert-toolbar-button) to insert table of contents elements:

```tsx
{
  icon: <TableOfContentsIcon />,
  label: 'Table of contents',
  value: KEYS.toc,
}
```

### Scroll Container Setup

- If your scrolling element is [EditorContainer](/docs/components/editor), you can skip this step.
- If your scrolling element is the editor container, pass `useEditorContainerRef()` as the `ref` prop. For example:

```tsx
// Below <Plate> component
function EditorContainer({ children }: { children: React.ReactNode }) {
  const containerRef = useEditorContainerRef();

  return <div ref={containerRef}>{children}</div>;
}
```

- If your scrolling element is an ancestor of the editor container, pass `useEditorScrollRef()` as the `ref` prop. For example:

```tsx
// Below <Plate> component
function Layout() {
  const scrollRef = useEditorScrollRef();

  return (
    <main ref={scrollRef}>
      <EditorContainer>
        <PlateContent />
      </EditorContainer>
    </main>
  );
}
```

</Steps>

## Plate Plus

[toc-pro registry content](https://platejs.org/r/toc-pro)

## Plugins

### `TocPlugin`

Plugin for generating table of contents.

<API name="TocPlugin">
<APIOptions>
  <APIItem name="isScroll" type="boolean" optional>
    Enable scrolling behavior.
    - **Default:** `true`
  </APIItem>
  <APIItem name="topOffset" type="number" optional>
    Top offset when scrolling to heading.
    - **Default:** `80`
  </APIItem>
  <APIItem name="queryHeading" type="(editor: SlateEditor) => Heading[]" optional>
    Custom function to query headings.
  </APIItem>
</APIOptions>
</API>

## Transforms

### `tf.insertToc`

Insert table of contents element.

<API name="insertToc">
<APIOptions type="InsertNodesOptions<SlateEditor>">
    Node insertion options.
</APIOptions>
</API>

## Hooks

### `useTocElementState`

Manage TOC element state.

<API name="useTocElementState">
<APIReturns>
  <APIItem name="activeContentId" type="string">
    Active heading ID for the current document position.
  </APIItem>
  <APIItem name="headingList" type="Heading[]">
    Document headings array.
  </APIItem>
  <APIItem name="onContentScroll" type="(el: HTMLElement, id: string, behavior: ScrollBehavior) => void">
    Heading scroll handler.
  </APIItem>
</APIReturns>
</API>

### `useTocElement`

Handle TOC element interactions.

<API name="useTocElement">

<APIParameters>
  <APIItem name="onContentScroll" type="(el: HTMLElement, id: string, behavior: ScrollBehavior) => void">
    Scroll handler from useTocElementState.
  </APIItem>
</APIParameters>

<APIReturns>
  <APIItem name="props" type="object">
    Props for TOC element.
  </APIItem>
  <APISubList>
    <APISubListItem parent="props" name="onClick" type="(e: React.MouseEvent, item: Heading, behavior: ScrollBehavior) => void">
      TOC item click handler.
    </APISubListItem>
  </APISubList>
</APIReturns>
</API>

### `useTocSideBarState`

Manage TOC sidebar state.

<API name="useTocSideBarState">
<APIParameters>
  <APIItem name="open" type="boolean" optional>
    Initial open state.
    - **Default:** `true`
  </APIItem>
  <APIItem name="rootMargin" type="string" optional>
    Intersection Observer root margin.
    - **Default:** `'0px 0px 0px 0px'`
  </APIItem>
  <APIItem name="topOffset" type="number" optional>
    Scroll top offset.
    - **Default:** `0`
  </APIItem>
</APIParameters>

<APIReturns>
  <APIItem name="activeContentId" type="string">
    Active section ID.
  </APIItem>
  <APIItem name="headingList" type="Heading[]">
    Document headings.
  </APIItem>
  <APIItem name="mouseInToc" type="boolean">
    Mouse over TOC state.
  </APIItem>
  <APIItem name="open" type="boolean">
    Sidebar open state.
  </APIItem>
  <APIItem name="setIsObserve" type="React.Dispatch<React.SetStateAction<boolean>>">
    Set observation state.
  </APIItem>
  <APIItem name="setMouseInToc" type="React.Dispatch<React.SetStateAction<boolean>>">
    Set mouse over state.
  </APIItem>
  <APIItem name="tocRef" type="React.RefObject<HTMLElement>">
    TOC element ref.
  </APIItem>
  <APIItem name="onContentScroll" type="(options: { id: string; behavior?: ScrollBehavior; el: HTMLElement }) => void">
    Content scroll handler.
  </APIItem>
</APIReturns>
</API>

### `useTocSideBar`

This hook provides props and handlers for the TOC sidebar component.

<API name="useTocSideBar">
<APIParameters>
  <APIItem name="mouseInToc" type="boolean">
    Mouse over TOC state.
  </APIItem>
  <APIItem name="open" type="boolean">
    Sidebar open state.
  </APIItem>
  <APIItem name="setIsObserve" type="React.Dispatch<React.SetStateAction<boolean>>">
    Set observation state.
  </APIItem>
  <APIItem name="setMouseInToc" type="React.Dispatch<React.SetStateAction<boolean>>">
    Set mouse over state.
  </APIItem>
  <APIItem name="tocRef" type="React.RefObject<HTMLElement>">
    TOC element ref.
  </APIItem>
  <APIItem name="onContentScroll" type="(options: { id: string; behavior?: ScrollBehavior; el: HTMLElement }) => void">
    Content scroll handler.
  </APIItem>
</APIParameters>
<APIReturns>
  <APIItem name="navProps" type="object">
    Navigation element props.
  </APIItem>
  <APISubList type="navProps">
    <APISubListItem parent="navProps" name="ref" type="React.RefObject<HTMLElement>">
      TOC element ref.
    </APISubListItem>
    <APISubListItem parent="navProps" name="onMouseEnter" type="() => void">
      Mouse enter handler.
    </APISubListItem>
    <APISubListItem parent="navProps" name="onMouseLeave" type="(e: React.MouseEvent<HTMLElement, MouseEvent>) => void">
      Mouse leave handler.
    </APISubListItem>
  </APISubList>
  <APISubListItem parent="navProps" name="onContentClick" type="(e: React.MouseEvent<HTMLElement, MouseEvent>, item: Heading, behavior?: ScrollBehavior) => void">
    TOC item click handler.
  </APISubListItem>
</APIReturns>
</API>


# Toggle

Source: https://platejs.org/docs/toggle

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Toggle
docs:
  - route: /docs/components/toggle-node
    title: Toggle Element
  - route: /docs/components/toggle-toolbar-button
    title: Toggle Button
---

[toggle-demo registry content](https://platejs.org/r/toggle-demo)

<PackageInfo>

## Features

- Add toggles to your document
- Toggles are closed by default, and can be opened to reveal the content inside

</PackageInfo>

## Kit Usage

<Steps>

### Installation

The fastest way to add toggle functionality is with the `ToggleKit`, which includes pre-configured `TogglePlugin` with indent support and their [Plate UI](/docs/installation/plate-ui) components.

[toggle-kit registry content](https://platejs.org/r/toggle-kit)

- [`IndentKit`](/docs/indent): Provides indent support for toggle elements.
- [`ToggleElement`](/docs/components/toggle-node): Renders toggle elements.

### Add Kit

Add the kit to your plugins:

```tsx
import { createPlateEditor } from 'platejs/react';
import { ToggleKit } from '@/components/editor/plugins/toggle-kit';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    ...ToggleKit,
  ],
});
```

</Steps>

## Manual Usage

<Steps>

### Installation

```bash
npm install @platejs/indent @platejs/toggle
```

### Add Plugins

Include `TogglePlugin` and `IndentPlugin` in your Plate plugins array when creating the editor.

```tsx
import { IndentPlugin } from '@platejs/indent/react';
import { TogglePlugin } from '@platejs/toggle/react';
import { createPlateEditor } from 'platejs/react';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    IndentPlugin,
    TogglePlugin,
  ],
});
```

### Configure Plugins

Configure the `IndentPlugin` and `TogglePlugin` with proper targeting and component assignment.

```tsx
import { IndentPlugin } from '@platejs/indent/react';
import { TogglePlugin } from '@platejs/toggle/react';
import { createPlateEditor } from 'platejs/react';
import { ToggleElement } from '@/components/ui/toggle-node';
import { KEYS } from 'platejs';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    IndentPlugin.configure({
      inject: {
        targetPlugins: [...KEYS.heading, KEYS.p, KEYS.toggle],
      },
    }),
    TogglePlugin.withComponent(ToggleElement),
  ],
});
```

- `withComponent`: Assigns [`ToggleElement`](/docs/components/toggle-node) to render toggle elements.
- `IndentPlugin.inject.targetPlugins`: Configures which element types support indentation, including toggles.

### Add Toolbar Button

You can add [`ToggleToolbarButton`](/docs/components/toggle-toolbar-button) to your [Toolbar](/docs/toolbar) to insert toggle elements.

### Turn Into Toolbar Button

You can add this item to the [Turn Into Toolbar Button](/docs/toolbar#turn-into-toolbar-button) to convert blocks into toggles:

```tsx
{
  icon: <ChevronRightIcon />,
  label: 'Toggle list',
  value: KEYS.toggle,
}
```

### Insert Toolbar Button

You can add this item to the [Insert Toolbar Button](/docs/toolbar#insert-toolbar-button) to insert toggle elements:

```tsx
{
  icon: <ChevronRightIcon />,
  label: 'Toggle list',
  value: KEYS.toggle,
}
```

</Steps>

## Plugins

### `TogglePlugin`

Plugin for managing toggle functionality.

<API name="TogglePlugin">
<APIOptions type="object">
  <APIItem name="openIds" type="Set<string>" optional>
    Set of open toggle IDs.
    - **Default:** `new Set()`
  </APIItem>
  <APIItem name="isOpen" type="(toggleId: string) => boolean" optional>
    Function to check if toggle is open.
    - **Default:** `(id) => openIds.has(id)`
  </APIItem>
  <APIItem name="someClosed" type="(toggleIds: string[]) => boolean" optional>
    Function to check if any toggles are closed.
    - **Default:** `(ids) => ids.some(id => !isOpen(id))`
  </APIItem>
</APIOptions>
</API>

## API

### `api.toggle.toggleIds`

Toggles the open state of specified toggles.

<API name="editor.api.toggle.toggleIds">
Toggle open state of toggles.

<APIParameters>
  <APIItem name="ids" type="string[]">
    Array of element IDs to toggle.
  </APIItem>
  <APIItem name="force" type="boolean | null" optional>
    Force toggle state:
    - `true`: expand all toggles
    - `false`: collapse all toggles
    - `null`: toggle current state
  </APIItem>
</APIParameters>
</API>

### `openNextToggles`

Mark block at current selection as open toggle.

## Hooks

### `useToggleToolbarButtonState`

Hook for getting toggle toolbar button state.

<API name="useToggleToolbarButtonState">
<APIReturns type="object">
  <APIItem name="pressed" type="boolean">
    Whether button is pressed.
  </APIItem>
</APIReturns>
</API>

### `useToggleToolbarButton`

Hook for handling toggle toolbar button behavior.

<API name="useToggleToolbarButton">
<APIState>
  <APIItem name="pressed" type="boolean">
    Whether button is pressed.
  </APIItem>
</APIState>

<APIReturns type="object">
  <APIItem name="props" type="object">
    Props for toggle button.
    <APISubList>
      <APISubListItem parent="props" name="pressed" type="boolean">
        Whether button is pressed.
      </APISubListItem>
      <APISubListItem parent="props" name="onClick" type="function">
        Toggle node type and focus editor.
      </APISubListItem>
      <APISubListItem parent="props" name="onMouseDown" type="function">
        Prevent focus loss on click.
      </APISubListItem>
    </APISubList>
  </APIItem>
</APIReturns>
</API>

### `useToggleButtonState`

Hook for getting toggle button state.

<API name="useToggleButtonState">
Get toggle button state.

<APIParameters>
  <APIItem name="toggleId" type="string">
    Toggle element ID.
  </APIItem>
</APIParameters>

<APIReturns type="object">
  <APIItem name="toggleId" type="string">
    Toggle element ID.
  </APIItem>
  <APIItem name="open" type="boolean">
    Whether toggle is expanded.
  </APIItem>
</APIReturns>
</API>

### `useToggleButton`

Hook for handling toggle button behavior.

<API name="useToggleButton">
Handle toggle button behavior.

<APIParameters>
  <APIItem name="toggleId" type="string">
    Toggle element ID.
  </APIItem>
  <APIItem name="open" type="boolean">
    Whether toggle is expanded.
  </APIItem>
</APIParameters>

<APIReturns type="object">
  <APIItem name="toggleId" type="string">
    Toggle element ID.
  </APIItem>
  <APIItem name="open" type="boolean">
    Whether toggle is expanded.
  </APIItem>
  <APIItem name="buttonProps" type="object">
    Props for toggle button.
    <APISubList>
      <APISubListItem parent="buttonProps" name="onClick" type="function">
        Toggle open state.
      </APISubListItem>
      <APISubListItem parent="buttonProps" name="onMouseDown" type="function">
        Prevent focus loss on click.
      </APISubListItem>
    </APISubList>
  </APIItem>
</APIReturns>
</API>

# Autoformat

Source: https://platejs.org/docs/autoformat

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Autoformat
description: Markdown shortcuts and text substitutions powered by input rules.
docs:
  - route: /docs/plugin-input-rules
    title: Plugin Input Rules
  - route: /docs/basic-blocks
    title: Basic Elements
  - route: /docs/basic-marks
    title: Basic Marks
  - route: /docs/code-block
    title: Code Block
  - route: /docs/list
    title: List
---

For the full runtime — dispatch, ownership, selection context, and custom rule authoring — see the [Plugin Input Rules](/docs/plugin-input-rules) guide. This page is the kit-first entry for markdown shortcuts and text substitutions.

[autoformat-demo registry content](https://platejs.org/r/autoformat-demo)

<PackageInfo>

## Features

- Markdown shortcuts owned by the feature plugins that understand them.
- Text substitutions powered by local `createTextSubstitutionInputRule(...)` definitions.
- Explicit activation through `inputRules`.
- No hidden default shortcut behavior.

</PackageInfo>

## Kit Usage

<Steps>

### Installation

The fastest way to add common text substitutions is with `AutoformatKit`.

[autoformat-kit registry content](https://platejs.org/r/autoformat-kit)

### Add Kit

```tsx
import { createPlateEditor } from 'platejs/react';
import { AutoformatKit } from '@/components/editor/plugins/autoformat-kit';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    ...AutoformatKit,
  ],
});
```

</Steps>

## Manual Usage

<Steps>

### Feature-Owned Markdown Shortcuts

Markdown shortcuts live on the plugins that own those features:

```tsx
import {
  BlockquoteRules,
  HeadingRules,
  HorizontalRuleRules,
} from '@platejs/basic-nodes';
import {
  BlockquotePlugin,
  H1Plugin,
  HorizontalRulePlugin,
} from '@platejs/basic-nodes/react';
import { CodeBlockRules } from '@platejs/code-block';
import { CodeBlockPlugin } from '@platejs/code-block/react';
import { LinkRules } from '@platejs/link';
import { LinkPlugin } from '@platejs/link/react';
import {
  BulletedListRules,
  OrderedListRules,
  TaskListRules,
} from '@platejs/list';
import { ListPlugin } from '@platejs/list/react';
import { MathRules } from '@platejs/math';
import { EquationPlugin, InlineEquationPlugin } from '@platejs/math/react';

const editor = createPlateEditor({
  plugins: [
    H1Plugin.configure({
      inputRules: [HeadingRules.markdown()],
    }),
    BlockquotePlugin.configure({
      inputRules: [BlockquoteRules.markdown()],
    }),
    HorizontalRulePlugin.configure({
      inputRules: [HorizontalRuleRules.markdown({ variant: '-' })],
    }),
    CodeBlockPlugin.configure({
      inputRules: [CodeBlockRules.markdown({ on: 'match' })],
    }),
    ListPlugin.configure({
      inputRules: [
        BulletedListRules.markdown({ variant: '-' }),
        OrderedListRules.markdown({ variant: '.' }),
        TaskListRules.markdown({ checked: false }),
      ],
    }),
    InlineEquationPlugin.configure({
      inputRules: [MathRules.markdown({ variant: '$' })],
    }),
    EquationPlugin.configure({
      inputRules: [MathRules.markdown({ on: 'break', variant: '$$' })],
    }),
    LinkPlugin.configure({
      inputRules: [
        LinkRules.markdown(),
        LinkRules.autolink({ variant: 'paste' }),
        LinkRules.autolink({ variant: 'space' }),
        LinkRules.autolink({ variant: 'break' }),
      ],
    }),
  ],
});
```

- Package rule families own the markdown semantics. Kits register explicit rule instances.

### Local Text Substitutions

Generic substitutions such as smart quotes, arrows, and fractions are best kept
as local copied plugin code:

```tsx
import {
  createSlatePlugin,
  createTextSubstitutionInputRule,
} from 'platejs';

const ShortcutsPlugin = createSlatePlugin({
  key: 'shortcuts',
  inputRules: [
    createTextSubstitutionInputRule({
      patterns: [{ format: '—', match: '--' }],
    }),
  ],
});

const editor = createPlateEditor({
  plugins: [ShortcutsPlugin],
});
```

### Fine-Grained Overrides

Rule names are the override unit:

```tsx
import { ItalicRules } from '@platejs/basic-nodes';

ItalicPlugin.configure({
  inputRules: [ItalicRules.markdown({ variant: '_' })],
});
```

</Steps>


# Block Menu

Source: https://platejs.org/docs/block-menu

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Block Menu
description: Context-menu actions for selected editor blocks.
docs:
  - route: /docs/block-selection
    title: Block Selection
  - route: /docs/components/block-context-menu
    title: Block Context Menu
  - route: /docs/examples/block-menu
    title: Demo
  - route: https://pro.platejs.org/docs/examples/block-menu
    title: Plus
---

Block Menu adds a right-click menu on top of block selection. `BlockMenuPlugin` owns the open state and pointer position; `BlockSelectionPlugin` decides which blocks the menu edits. The registry `BlockContextMenu` renders the menu actions.

[block-menu-demo registry content](https://platejs.org/r/block-menu-demo)

<PackageInfo>

## Features

- Right-click block selection.
- Context menu open state through `openId` and `position`.
- Delete, duplicate, turn-into, indent, outdent, align, and Ask AI actions.
- Touch-device and read-only guards.
- Element-level opt in/out with `data-plate-open-context-menu`.
- Plus menu with drag-handle entry, combobox filtering, nested actions, colors, comments, and AI.

</PackageInfo>

## Fast Path

<Steps>

### Add The Kit

`BlockMenuKit` spreads `BlockSelectionKit` and renders `BlockContextMenu` above the editable.

[block-menu-kit registry content](https://platejs.org/r/block-menu-kit)

```tsx
import { createPlateEditor } from 'platejs/react';

import { BlockMenuKit } from '@/components/editor/plugins/block-menu-kit';

export const editor = createPlateEditor({
  plugins: BlockMenuKit,
});
```

### Render The Menu

`block-context-menu` is the registry UI used by the kit.

[block-context-menu registry content](https://platejs.org/r/block-context-menu)

### Try The Plus Menu

[block-menu-pro registry content](https://platejs.org/r/block-menu-pro)

</Steps>

## Ownership

| Surface | Owner | What It Does |
|---------|-------|--------------|
| `BlockMenuPlugin` | `@platejs/selection/react` | Stores `openId` and pointer `position`, then exposes menu show/hide APIs. |
| `BlockSelectionPlugin` | `@platejs/selection/react` | Selects the block under the context-menu event and applies actions to selected blocks. |
| `BlockSelectionKit` | Registry | Enables context-menu selection and filters non-selectable blocks such as columns, code lines, and table cells. |
| `BlockMenuKit` | Registry | Combines `BlockSelectionKit` with `BlockMenuPlugin.render.aboveEditable`. |
| `BlockContextMenu` | Registry UI | Renders Radix context-menu items and calls block-selection transforms. |
| `block-menu-demo` | Registry example | Shows the default menu in the full editor. |
| `block-menu-pro` | Plus example | Adds drag-handle entry, nested filtering, colors, comments, and AI actions. |

The menu is UI state, not document state. The document stores block ids and node properties; it does not store whether a menu is open.

## Manual Setup

<Steps>

### Install Packages

```bash
npm install @platejs/selection @platejs/ai
```

`@platejs/ai` is needed only when you keep the `Ask AI` item from the registry menu.

### Add Plugins

Use `BlockSelectionKit` when you want to keep the registry selection behavior but replace the menu wiring.

```tsx
import { BlockMenuPlugin } from '@platejs/selection/react';
import { createPlateEditor } from 'platejs/react';

import { BlockSelectionKit } from '@/components/editor/plugins/block-selection-kit';
import { BlockContextMenu } from '@/components/ui/block-context-menu';

export const editor = createPlateEditor({
  plugins: [
    ...BlockSelectionKit,
    BlockMenuPlugin.configure({
      render: { aboveEditable: BlockContextMenu },
    }),
  ],
});
```

Use this lower-level shape only when you are replacing both registry kits.

```tsx
import {
  BlockMenuPlugin,
  BlockSelectionPlugin,
} from '@platejs/selection/react';
import { createPlateEditor } from 'platejs/react';

import { BlockContextMenu } from '@/components/ui/block-context-menu';

export const editor = createPlateEditor({
  plugins: [
    BlockSelectionPlugin.configure({
      options: {
        enableContextMenu: true,
      },
    }),
    BlockMenuPlugin.configure({
      render: { aboveEditable: BlockContextMenu },
    }),
  ],
});
```

</Steps>

## Context Menu Rules

| Case | Behavior |
|------|----------|
| Right-click on a selectable block | Selects that block, then opens the context menu at the pointer position. |
| Shift + right-click | Adds the block to the current block selection. |
| Right-click inside a focused text selection | Leaves the browser context menu unless the block is already selected, void, or explicitly opted in. |
| Left-click while the menu is open | Prevents the click and hides the menu. |
| Touch device | Renders children without the context-menu wrapper. |
| Read-only editor | Prevents the context menu. |

Disable the Plate context menu for a specific surface with `data-plate-open-context-menu={false}`.

```tsx
<PlateElement data-plate-open-context-menu={false} {...props}>
  {children}
</PlateElement>
```

Force it open from a focused block with `data-plate-open-context-menu="true"` when the block should bypass the focused-selection guard.

## Menu Actions

`BlockContextMenu` acts on the current block selection.

| Action | Source |
|--------|--------|
| Ask AI | Opens `AIChatPlugin` after the menu closes. |
| Delete | Calls `editor.getTransforms(BlockSelectionPlugin).blockSelection.removeNodes()`. |
| Duplicate | Calls `editor.getTransforms(BlockSelectionPlugin).blockSelection.duplicate()`. |
| Turn into | Calls the registry `setBlockType` helper for paragraph, headings, blockquote, and code drawing. |
| Indent / Outdent | Calls `blockSelection.setIndent(1)` or `blockSelection.setIndent(-1)`. |
| Align | Calls `blockSelection.setNodes({ align })`. |

The menu focuses block selection after close so keyboard selection remains active.

## API Reference

| API | Package | Use |
|-----|---------|-----|
| `BLOCK_CONTEXT_MENU_ID` | `@platejs/selection/react` | Built-in open id for the registry context menu. |
| `BlockMenuPlugin` | `@platejs/selection/react` | Menu state plugin with `openId` and `position` options. |
| `api.blockMenu.hide()` | `@platejs/selection/react` | Closes the menu and moves its stored position offscreen. |
| `api.blockMenu.show(id, position?)` | `@platejs/selection/react` | Opens a menu by id and optionally sets pointer coordinates. |
| `api.blockMenu.showContextMenu(blockId, position)` | `@platejs/selection/react` | Selects one block by id, then opens the context menu at the pointer coordinates. |
| `BlockSelectionPlugin.options.enableContextMenu` | `@platejs/selection/react` | Enables block selection from right-click events. |
| `api.blockSelection.addOnContextMenu` | `@platejs/selection/react` | Shared right-click handler used by selectable block node props. |
| `BlockContextMenu` | Registry UI | Default context menu component used by `BlockMenuKit`. |


# Block Placeholder

Source: https://platejs.org/docs/block-placeholder

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Block Placeholder
description: Placeholder text for the active empty block.
docs:
  - route: /docs/examples/block-placeholder
    title: Demo
---

Block Placeholder injects a `placeholder` prop into the active empty block. It is block-level UI state, not stored document content. Use the editor-level `placeholder` prop for the globally empty editor state.

[block-placeholder-demo registry content](https://platejs.org/r/block-placeholder-demo)

<PackageInfo>

## Features

- Active-block placeholder text.
- Per-type placeholder map through `placeholders`.
- Root-level filtering through `query`.
- Custom placeholder styling through `className`.
- Focus, read-only, composition, selection, and empty-editor guards.

</PackageInfo>

## Fast Path

<Steps>

### Add The Kit

`BlockPlaceholderKit` configures `BlockPlaceholderPlugin` for paragraph blocks.

[block-placeholder-kit registry content](https://platejs.org/r/block-placeholder-kit)

```tsx
import { createPlateEditor } from 'platejs/react';

import { BlockPlaceholderKit } from '@/components/editor/plugins/block-placeholder-kit';

export const editor = createPlateEditor({
  plugins: BlockPlaceholderKit,
});
```

### Style The Placeholder

The registry kit uses a `before:` pseudo-element that reads the injected `placeholder` attribute.

```tsx
BlockPlaceholderPlugin.configure({
  options: {
    className:
      'before:absolute before:cursor-text before:text-muted-foreground/80 before:content-[attr(placeholder)]',
  },
});
```

</Steps>

## Ownership

| Surface | Owner | What It Does |
|---------|-------|--------------|
| `BlockPlaceholderPlugin` | `platejs/react` / `@platejs/utils/react` | Tracks the current placeholder target and injects block node props. |
| `BlockPlaceholderKit` | Registry | Configures the default paragraph placeholder and styling. |
| `block-placeholder-demo` | Registry example | Shows the placeholder on an empty paragraph inside a non-empty editor. |
| `Editor` `placeholder` prop | `platejs/react` | Covers the globally empty editor state. |

The plugin stores its current target in `_target`. That option is runtime state for rendering; do not serialize it.

## Manual Setup

<Steps>

### Add The Plugin

`BlockPlaceholderPlugin` is available from `platejs/react`.

```tsx
import { KEYS } from 'platejs';
import { BlockPlaceholderPlugin, createPlateEditor } from 'platejs/react';

export const editor = createPlateEditor({
  plugins: [
    BlockPlaceholderPlugin.configure({
      options: {
        className:
          'before:absolute before:cursor-text before:text-muted-foreground/80 before:content-[attr(placeholder)]',
        placeholders: {
          [KEYS.p]: 'Type something...',
        },
        query: ({ path }) => path.length === 1,
      },
    }),
  ],
});
```

### Add Type-Specific Copy

Keys in `placeholders` are plugin keys. The plugin resolves each key with `editor.getType(key)` before matching the active block type.

```tsx
BlockPlaceholderPlugin.configure({
  options: {
    placeholders: {
      [KEYS.p]: 'Type something...',
      [KEYS.h1]: 'Untitled',
      [KEYS.blockquote]: 'Quote',
      [KEYS.codeBlock]: 'Code',
    },
  },
});
```

</Steps>

## Visibility Rules

The plugin shows a placeholder only when every gate passes.

| Gate | Requirement |
|------|-------------|
| Editor mode | Not read-only and not composing. |
| Focus | Editor is focused and has a selection. |
| Selection | Selection is collapsed. |
| Active block | `editor.api.block()` returns an empty block. |
| Whole editor | The editor is not in its pristine single-empty-block state. Empty blocks with visible structural state, such as list metadata, still qualify. |
| Placeholder map | The block type matches one entry in `placeholders`. |
| Query | `query({ editor, node, path, ...ctx })` returns `true`. |

The default `query` returns `true` for root blocks only. The whole-editor guard uses `editor.api.isElementStateEmpty`, so only `type` and props claimed by plugins through `node.isMetadataProp` are treated as pristine metadata.

```tsx
query: ({ path }) => path.length === 1
```

Use `query` when placeholders should skip nested content, tables, columns, or app-specific containers.

## Styling

The plugin injects two props on the target block:

| Prop | Source |
|------|--------|
| `placeholder` | Resolved string from `placeholders`. |
| `className` | `options.className`. |

Use CSS that reads `attr(placeholder)`. Tailwind arbitrary content works well for this because the placeholder text stays in the DOM attribute instead of document data.

```tsx
className:
  'before:absolute before:pointer-events-none before:text-muted-foreground/80 before:content-[attr(placeholder)]'
```

## API Reference

| API | Package | Use |
|-----|---------|-----|
| `BlockPlaceholderPlugin` | `platejs/react` / `@platejs/utils/react` | Adds block placeholders through injected node props. |
| `options.placeholders` | `Record<string, string>` | Maps plugin keys to placeholder text. Default: `{ [KEYS.p]: 'Type something...' }`. |
| `options.query` | `(context) => boolean` | Filters eligible blocks. Default: `({ path }) => path.length === 1`. |
| `options.className` | `string` | Class applied to the block only while its placeholder is active. |
| `options._target` | Internal runtime state | Stores the current target node and placeholder string. |
| `selectors.placeholder(node)` | Plugin selector | Returns the placeholder string for the current target node. |


# Block Selection

Source: https://platejs.org/docs/block-selection

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Block Selection
docs:
  - route: /docs/components/block-selection
    title: Block Selection
---

[block-selection-demo registry content](https://platejs.org/r/block-selection-demo)

<PackageInfo>

The Block Selection feature allows users to select and manipulate entire text blocks, as opposed to individual words or characters.

## Features

- Select entire blocks with a single action.
- Multi-block selection using mouse drag or keyboard shortcuts.
- Copy, cut, and delete operations on selected blocks.
- Keyboard shortcuts for quick selection:
  - `Cmd+A`: Select all blocks.
  - Arrow keys: Select the block above or below.
- Customizable styling for selected blocks.

</PackageInfo>

## Kit Usage

<Steps>

### Installation

The fastest way to add Block Selection is with the `BlockSelectionKit`, which includes the pre-configured `BlockSelectionPlugin` and the [`BlockSelection`](/docs/components/block-selection) UI component.

[block-selection-kit registry content](https://platejs.org/r/block-selection-kit)

- [`BlockSelection`](/docs/components/block-selection): Renders the selection rectangle around selected blocks.

### Add Kit

The `BlockSelectionKit` enables the context menu by default and provides a default `isSelectable` logic to exclude common non-selectable blocks like code lines and table cells.

```tsx
import { createPlateEditor } from 'platejs/react';
import { BlockSelectionKit } from '@/components/editor/plugins/block-selection-kit';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    ...BlockSelectionKit,
  ],
});
```

</Steps>

## Manual Usage

<Steps>

### Installation

```bash
npm install @platejs/selection
```

### Add Plugin

```tsx
import { BlockSelectionPlugin } from '@platejs/selection/react';
import { createPlateEditor } from 'platejs/react';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    BlockSelectionPlugin,
  ],
});
```

Put this plugin before any other plugins overriding `selectAll` – `Cmd+A` (code block, table, column, etc.) to avoid any conflicts.

#### Excluding Blocks from Selection

You can control which blocks are selectable using `options.isSelectable`. This function receives an element and its path, and should return `true` if the block is selectable.

For example, to exclude code lines, columns, and table cells:

```tsx
import { BlockSelectionPlugin } from '@platejs/selection/react';

BlockSelectionPlugin.configure({
  options: {
    isSelectable: (element, path) => {
      if (['code_line', 'column', 'td'].includes(element.type)) {
        return false;
      }
      // Exclude blocks inside table rows
      if (editor.api.block({ above: true, at: path, match: { type: 'tr' } })) {
        return false;
      }
      return true;
    },
  },
});
```

#### Customizing Scroll Behavior

If your editor is inside a scrollable container, you may need to configure the selection area's boundaries and scroll speed.

1.  Add an `id` to your scroll container, e.g., `id={editor.meta.uid}`.
2.  Set `position: relative` on the container.
3.  Use the `areaOptions` to configure the boundaries and scrolling behavior.

```ts
BlockSelectionPlugin.configure({
  options: {
    areaOptions: {
      boundaries: `#${editor.meta.uid}`,
      container: `#${editor.meta.uid}`,
      behaviour: {
        scrolling: {
          // Recommended speed, close to native
          speedDivider: 0.8,
        },
        // Threshold to start selection area
        startThreshold: 4,
      },
    },
  },
});
```

#### Full Page Selection

You can enable block selection for elements outside the `<Editor />` component by adding the `data-plate-selectable` attribute.

```tsx
<Cover data-plate-selectable />
<Sidebar data-plate-selectable />
```

To prevent unselecting blocks when clicking on certain elements (e.g., a toolbar button), add the `data-plate-prevent-unselect` attribute.

```tsx
<YourToolbarButton data-plate-prevent-unselect />
```

To reset the selection when clicking outside selectable areas, you can use a click handler or call the API directly:

```tsx
// 1. Direct API call
editor.api.blockSelection.deselect();

// 2. Click outside handler
const handleClickOutside = (event: MouseEvent) => {
  if (!(event.target as HTMLElement).closest('[data-plate-selectable]')) {
    editor.api.blockSelection.deselect();
  }
};
```

</Steps>

## Styling

### Selection Area

Style the selection area by targeting the `.slate-selection-area` class, which is added to the editor container.

```css
/* Example using Tailwind CSS utility classes */
'[&_.slate-selection-area]:border [&_.slate-selection-area]:border-primary [&_.slate-selection-area]:bg-primary/10'
```

### Selected Element

Use the `useBlockSelected` hook to determine if a block is selected. You can render a visual indicator, like the [`BlockSelection`](/docs/components/block-selection) component, which is designed for this purpose.

Plate UI renders this component for all selectable blocks using `render.belowRootNodes`:

```tsx
render: {
  belowRootNodes: (props) => {
    if (!props.className?.includes('slate-selectable')) return null;

    return <BlockSelection />;
  },
},
```

## Plugins

### `BlockSelectionPlugin`

Plugin for block selection functionality.

<API name="BlockSelectionPlugin">
<APIOptions>
  <APIItem name="areaOptions" type="PartialSelectionOptions" optional>
    Options for the selection area. See [SelectionJS docs](https://github.com/Simonwep/selection-js) for all available options.
    
```ts
{
  boundaries: [`#${editor.meta.uid}`],
  container: [`#${editor.meta.uid}`],
  selectables: [`#${editor.meta.uid} .slate-selectable`],
  selectionAreaClass: 'slate-selection-area',
}
```
    
  </APIItem>
  <APIItem name="enableContextMenu" type="boolean" optional>
    Enables or disables the context menu for block selection.
    - **Default:** `false`
  </APIItem>
  <APIItem name="isSelecting" type="boolean" optional>
    Indicates whether block selection is currently active.
    - **Default:** `false`
  </APIItem>
  <APIItem name="onKeyDownSelecting" type="(e: KeyboardEvent) => void" optional>
    A function to handle the keydown event when selecting.
  </APIItem>
  <APIItem name="query" type="QueryNodeOptions" optional>
    Options for querying nodes during block selection.
    - **Default:** `{ maxLevel: 1 }`
  </APIItem>
  <APIItem name="selectedIds" type="Set<string>" optional>
    A set of IDs for the currently selected blocks.
    - **Default:** `new Set()`
  </APIItem>
  <APIItem name="anchorId" type="string | null" optional>
    (Internal) The ID of the anchor block in the current selection. Used for shift-based selection.
    - **Default:** `null`
  </APIItem>
  <APIItem name="isSelectable" type="(element: TElement, path: Path) => boolean" optional>
    Function to determine if a block element is selectable.
    - **Default:** `() => true`
  </APIItem>
</APIOptions>
</API>

## API

### `api.blockSelection.add`

Adds one or more blocks to the selection.

<API name="add">
  <APIParameters>
    <APIItem name="id" type="string | string[]">
      The ID(s) of the block(s) to be selected.
    </APIItem>
  </APIParameters>
</API>

### `api.blockSelection.clear`

Resets the set of selected IDs to an empty set.

### `api.blockSelection.delete`

Removes one or more blocks from the selection.

<API name="delete">
  <APIParameters>
    <APIItem name="id" type="string | string[]">
      The ID(s) of the block(s) to remove from selection.
    </APIItem>
  </APIParameters>
</API>

### `api.blockSelection.deselect`

Deselects all blocks and sets the `isSelecting` flag to false.

### `api.blockSelection.focus`

Focuses the block selection shadow input. This input handles copy, delete, and paste events for selected blocks.

### `api.blockSelection.getNodes`

Gets the selected blocks in the editor.

<API name="getNodes">
<APIParameters>
  <APIItem name="options" type="{ selectionFallback?: boolean }" optional>
    Options for getting nodes.
  </APIItem>
</APIParameters>

<APIOptions type="object">
  <APIItem name="selectionFallback" type="boolean" optional>
    If true, and no blocks are selected by block selection, the method will use
    the editor's original selection to retrieve blocks. - **Default:** `false`
  </APIItem>
</APIOptions>

<APIReturns type="NodeEntry[]">
  Array of selected block entries.
</APIReturns>
</API>

### `api.blockSelection.has`

Checks if one or more blocks are selected.

<API name="has">
  <APIParameters>
    <APIItem name="id" type="string | string[]">
      The ID(s) of the block(s) to check.
    </APIItem>
  </APIParameters>
  <APIReturns>
    <APIItem type="boolean">Whether the block(s) are selected.</APIItem>
  </APIReturns>
</API>

### `api.blockSelection.isSelectable`

Checks if a block at a given path is selectable based on the `isSelectable` plugin option.

<API name="isSelectable">
  <APIParameters>
    <APIItem name="element" type="TElement">
      Block element to check.
    </APIItem>
    <APIItem name="path" type="Path">
      Path to the block element.
    </APIItem>
  </APIParameters>
  <APIReturns type="boolean">Whether the block is selectable.</APIReturns>
</API>

### `api.blockSelection.moveSelection`

Moves the selection up or down to the next selectable block.

When moving up:

- Gets the previous selectable block from the top-most selected block
- Sets it as the new anchor
- Clears previous selection and selects only this block
  When moving down:
- Gets the next selectable block from the bottom-most selected block
- Sets it as the new anchor
- Clears previous selection and selects only this block

<API name="moveSelection">
  <APIParameters>
    <APIItem name="direction" type="'up' | 'down'">
      Direction to move selection.
    </APIItem>
  </APIParameters>
</API>

### `api.blockSelection.selectAll`

Selects all selectable blocks in the editor.

### `api.blockSelection.set`

Sets the selection to one or more blocks, clearing any existing selection.

<API name="set">
  <APIParameters>
    <APIItem name="id" type="string | string[]">
      The ID(s) of the block(s) to be selected.
    </APIItem>
  </APIParameters>
</API>

### `api.blockSelection.shiftSelection`

Expands or shrinks the selection based on the anchor block.

For `Shift+ArrowDown`:

- If anchor is top-most: Expands down by adding block below bottom-most
- Otherwise: Shrinks from top-most (unless top-most is the anchor)
  For `Shift+ArrowUp`:
- If anchor is bottom-most: Expands up by adding block above top-most
- Otherwise: Shrinks from bottom-most (unless bottom-most is the anchor)
  The anchor block always remains selected. If no anchor is set, it defaults to:
- Bottom-most block for `Shift+ArrowUp`
- Top-most block for `Shift+ArrowDown`

<API name="shiftSelection">
  <APIParameters>
    <APIItem name="direction" type="'up' | 'down'">
      Direction to expand/shrink selection.
    </APIItem>
  </APIParameters>
</API>

## Transforms

### `tf.blockSelection.duplicate`

Duplicates the selected blocks.

### `tf.blockSelection.removeNodes`

Removes the selected nodes from the editor.

### `tf.blockSelection.select`

Selects the nodes returned by `getNodes()` in the editor and resets selected IDs.

### `tf.blockSelection.setNodes`

Sets properties on the selected nodes.

<API name="setNodes">
  <APIParameters>
    <APIItem name="props" type="Partial<NodeProps<TElement>>">
      Properties to set on selected nodes.
    </APIItem>
    <APIItem name="options" type="SetNodesOptions" optional>
      Options for setting nodes.
    </APIItem>
  </APIParameters>
</API>

### `tf.blockSelection.setTexts`

Sets text properties on the selected nodes.

<API name="setTexts">
  <APIParameters>
    <APIItem name="props" type="Partial<NodeProps<TText>>">
      Text properties to set on selected nodes.
    </APIItem>
    <APIItem name="options" type="Omit<SetNodesOptions, 'at'>" optional>
      Options for setting text nodes, excluding the 'at' property.
    </APIItem>
  </APIParameters>
</API>

## Hooks

### `useBlockSelectable`

A hook that provides props for making a block element selectable, including context menu behavior.

<API name="useBlockSelectable">
  <APIReturns type="object">
    <APIItem name="props" type="object">
      Props to be spread on the block element.
      <APISubList>
        <APISubListItem parent="props" name="className" type="string">
          Required class for selection functionality. - **Default:**
          `'slate-selectable'`
        </APISubListItem>
        <APISubListItem
          parent="props"
          name="onContextMenu"
          type="(event: React.MouseEvent) => void"
        >
          Handles right-click context menu behavior: - Opens context menu for
          selected blocks - Opens for void elements - Opens for elements with
          `data-plate-open-context-menu="true"` - Adds block to selection with
          Shift key for multi-select
        </APISubListItem>
      </APISubList>
    </APIItem>
  </APIReturns>
</API>

### `useBlockSelected`

<API name="useBlockSelected">
  <APIReturns type="boolean">Whether the context block is selected.</APIReturns>
</API>

### `useBlockSelectionNodes`

<API name="useBlockSelectionNodes">
  <APIReturns type="NodeEntry[]">Array of selected block entries.</APIReturns>
</API>

### `useBlockSelectionFragment`

<API name="useBlockSelectionFragment">
  <APIReturns type="Node[]">Array of selected block nodes.</APIReturns>
</API>

### `useBlockSelectionFragmentProp`

<API name="useBlockSelectionFragmentProp">
  <APIReturns type="Node[]">Fragment prop for selected blocks.</APIReturns>
</API>

### `useSelectionArea`

Initialize and manage selection area functionality.


# Caption

Source: https://platejs.org/docs/caption

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Caption
description: Add captions to media elements like images, videos, and files.
docs:
  - route: /docs/components/caption
    title: Caption
---

[media-demo registry content](https://platejs.org/r/media-demo)

<PackageInfo>

## Features

- Add captions to images, videos, audio files, and other media elements.
- Arrow navigation selects caption within a block.
- Inline caption editing with textarea component.

</PackageInfo>

## Kit Usage

<Steps>

### Installation

The fastest way to add caption functionality is with the `MediaKit`, which includes the pre-configured `CaptionPlugin` along with media plugins and their [Plate UI](/docs/installation/plate-ui) components.

[media-kit registry content](https://platejs.org/r/media-kit)

- [`Caption`](/docs/components/caption): Renders caption components for media elements.

### Add Kit

```tsx
import { createPlateEditor } from 'platejs/react';
import { MediaKit } from '@/components/editor/plugins/media-kit';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    ...MediaKit,
  ],
});
```

</Steps>

## Manual Usage

<Steps>

### Installation

```bash
npm install @platejs/caption
```

### Add Plugin

```tsx
import { CaptionPlugin } from '@platejs/caption/react';
import { createPlateEditor } from 'platejs/react';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    CaptionPlugin,
  ],
});
```

### Configure Plugin

Configure which media plugins should support captions:

```tsx
import { KEYS } from 'platejs';
import { CaptionPlugin } from '@platejs/caption/react';
import {
  AudioPlugin,
  FilePlugin,
  ImagePlugin,
  MediaEmbedPlugin,
  VideoPlugin,
} from '@platejs/media/react';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    ImagePlugin,
    VideoPlugin,
    AudioPlugin,
    FilePlugin,
    MediaEmbedPlugin,
    CaptionPlugin.configure({
      options: {
        query: {
          allow: [KEYS.img, KEYS.video, KEYS.audio, KEYS.file, KEYS.mediaEmbed],
        },
      },
    }),
  ],
});
```

- `query.allow`: Array of plugin keys that support captions.

</Steps>

## Plugins

### `CaptionPlugin`

Plugin for adding caption functionality to media elements.

<API name="CaptionPlugin">
<APIOptions>
  <APIItem name="query" type="{ allow: string[] }" required>
    Configuration for which plugins support captions.
    <APISubList>
      <APISubListItem parent="query" name="allow" type="string[]">
        Plugin keys of the blocks that can have captions.
      </APISubListItem>
    </APISubList>
  </APIItem>
  <APIItem name="focusEndPath" type="Path" optional>
    Path to focus at the end of the caption.
    - **Default:** `null`
  </APIItem>
  <APIItem name="focusStartPath" type="Path" optional>
    Path to focus at the start of the caption.
    - **Default:** `null`
  </APIItem>
  <APIItem name="visibleId" type="string" optional>
    ID of the currently visible caption.
    - **Default:** `null`
  </APIItem>
</APIOptions>
</API>

## Types

### `TCaptionElement`

Extends `TElement`.

<API name="TCaptionElement">
<APIAttributes>
  <APIItem name="caption" type="Descendant[]" optional>
    Caption value as an array of descendant nodes.
  </APIItem>
</APIAttributes>
</API>

## Components

### `<Caption>`

<API name="Caption">
<APIProps>
  <APIItem name="options" type="object" optional>
    Options for the caption component.
  </APIItem>
  <APIItem name="state" type="object" optional>
    State for the caption component.
    <APISubList>
      <APISubListItem parent="state" name="captionString" type="string" optional>
        The string representing the caption.
      </APISubListItem>
      <APISubListItem parent="state" name="selected" type="boolean" optional>
        Whether the caption component is selected.
      </APISubListItem>
      <APISubListItem parent="state" name="readOnly" type="boolean" optional>
        Whether the caption component is in read-only mode.
      </APISubListItem>
    </APISubList>
  </APIItem>
  
  <APIOptions type="object">
  <APIItem name="readOnly" type="boolean" optional>
    Whether the caption component is in read-only mode.
  </APIItem>
</APIOptions>
</APIProps>
</API>

### `<CaptionTextarea>`

<API name="CaptionTextarea">
<APIProps>
  <APIItem name="state" type="object">
    State for the caption textarea.
    <APISubList>
      <APISubListItem parent="state" name="textareaRef" type="Ref">
        Reference to the textarea element.
      </APISubListItem>
      <APISubListItem parent="state" name="captionValue" type="TextareaAutosizeProps['value']">
        The value of the caption displayed in the textarea.
      </APISubListItem>
      <APISubListItem parent="state" name="setCaptionValue" type="(value: TextareaAutosizeProps['value']) => void">
        Function to update the caption value.
      </APISubListItem>
      <APISubListItem parent="state" name="readOnly" type="boolean">
        Whether the caption component is in read-only mode.
      </APISubListItem>
      <APISubListItem parent="state" name="element" type="TCaptionElement">
        The caption element.
      </APISubListItem>
    </APISubList>
  </APIItem>
</APIProps>
</API>


# Cursor Overlay

Source: https://platejs.org/docs/cursor-overlay

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Cursor Overlay
description: Visual feedback for selections and cursor positions when editor loses focus.
docs:
  - route: /docs/components/cursor-overlay
    title: Cursor Overlay
---

[cursor-overlay-demo registry content](https://platejs.org/r/cursor-overlay-demo)

<PackageInfo>

## Features

- Maintains selection highlight when another element is focused.
- Dynamic selection display (e.g., during AI streaming).
- Shows cursor position during drag operations.
- Customizable styling for cursors and selections.
- Essential for external UI interactions (e.g., link toolbar, AI combobox).

</PackageInfo>

## Kit Usage

<Steps>

### Installation

The fastest way to add cursor overlay functionality is with the `CursorOverlayKit`, which includes the pre-configured `CursorOverlayPlugin` and the [`CursorOverlay`](/docs/components/cursor-overlay) UI component.

[cursor-overlay-kit registry content](https://platejs.org/r/cursor-overlay-kit)

- [`CursorOverlay`](/docs/components/cursor-overlay): Renders cursor and selection overlays.

### Add Kit

```tsx
import { createPlateEditor } from 'platejs/react';
import { CursorOverlayKit } from '@/components/editor/plugins/cursor-overlay-kit';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    ...CursorOverlayKit,
  ],
});
```

</Steps>

## Manual Usage

<Steps>

### Installation

```bash
npm install @platejs/selection
```

### Add Plugin

```tsx
import { CursorOverlayPlugin } from '@platejs/selection/react';
import { createPlateEditor } from 'platejs/react';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    CursorOverlayPlugin,
  ],
});
```

### Configure Plugin

Configure the cursor overlay with a component to render overlays:

```tsx
import { CursorOverlayPlugin } from '@platejs/selection/react';
import { CursorOverlay } from '@/components/ui/cursor-overlay';

CursorOverlayPlugin.configure({
  render: {
    afterEditable: () => <CursorOverlay />,
  },
});
```

- `render.afterEditable`: Assigns [`CursorOverlay`](/docs/components/cursor-overlay) to render after the editable content.

### Editor Container Setup

The cursor overlay requires a container component to ensure correct positioning. If you're using the [Editor](/docs/components/editor) component, this is handled automatically through `EditorContainer`.

For custom setups, ensure your editor is wrapped with a container that has the editor's unique ID:

```tsx
import { PlateContainer } from 'platejs/react';

export function EditorContainer(props: React.HTMLAttributes<HTMLDivElement>) {
  return <PlateContainer {...props} />;
}
```

### Preserving Selection Focus

To maintain the editor's selection state when focusing UI elements, add the `data-plate-focus="true"` attribute to those elements:

```tsx
<ToolbarButton data-plate-focus="true">
  {/* toolbar content */}
</ToolbarButton>
```

This prevents the cursor overlay from disappearing when interacting with toolbar buttons or other UI elements.

</Steps>

## Plugins

### `CursorOverlayPlugin`

Plugin that manages cursor and selection overlays for visual feedback.

<API name="CursorOverlayPlugin">
<APIOptions>
  <APIItem name="cursors" type="Record<string, CursorState<CursorData>>">
    Object containing cursor states with their unique identifiers.
    - **Default:** `{}`
  </APIItem>
</APIOptions>
</API>

## API

### `api.cursorOverlay.addCursor`

Adds a cursor overlay with the specified key and state.

<API name="addCursor">
<APIParameters>
  <APIItem name="key" type="string">
    Unique identifier for the cursor (e.g., 'blur', 'drag', 'custom').
  </APIItem>
  <APIItem name="cursor" type="CursorState<CursorData>">
    The cursor state including selection and optional styling data.
  </APIItem>
</APIParameters>
</API>

### `api.cursorOverlay.removeCursor`

Removes a cursor overlay by its key.

<API name="removeCursor">
<APIParameters>
  <APIItem name="key" type="string">
    The key of the cursor to remove.
  </APIItem>
</APIParameters>
</API>

## Hooks

### `useCursorOverlay`

A hook that manages cursor and selection overlay states, providing real-time cursor positions and selection rectangles.

<API name="useCursorOverlay">
<APIOptions type="object">
  <APIItem name="minSelectionWidth" type="number" optional>
    Minimum width in pixels for a selection rectangle. Useful for making cursor carets more visible.
    - **Default:** `1`
  </APIItem>
  <APIItem name="refreshOnResize" type="boolean" optional>
    Whether to recalculate cursor positions when the container is resized.
    - **Default:** `true`
  </APIItem>
</APIOptions>

<APIReturns type="object">
  <APIItem name="cursors" type="CursorOverlayState<TCursorData>[]">
    Array of cursor states with their corresponding selection rectangles and styling data.
  </APIItem>
  <APIItem name="refresh" type="() => void">
    Function to manually trigger a recalculation of cursor positions.
  </APIItem>
</APIReturns>
</API>


# Drag & Drop

Source: https://platejs.org/docs/dnd

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Drag & Drop
description: Drag and drop blocks to reorganize content within the editor.
docs:
  - route: https://pro.platejs.org/docs/examples/dnd
    title: Plus
  - route: /docs/components/block-draggable
    title: Block Draggable
---

[dnd-demo registry content](https://platejs.org/r/dnd-demo)

<PackageInfo>

## Features

- Drag and drop blocks for content movement and insertion within the editor.
- Automatic scrolling when dragging blocks near viewport edges.
- File drop support for inserting media blocks.
- Visual drop indicators and drag handles.

</PackageInfo>

## Kit Usage

<Steps>

### Installation

The fastest way to add drag and drop functionality is with the `DndKit`, which includes the pre-configured `DndPlugin` along with React DnD setup and the [`BlockDraggable`](/docs/components/block-draggable) UI component.

[dnd-kit registry content](https://platejs.org/r/dnd-kit)

- [`BlockDraggable`](/docs/components/block-draggable): Renders drag handles and drop indicators for blocks.

### Add Kit

```tsx
import { createPlateEditor } from 'platejs/react';
import { DndKit } from '@/components/editor/plugins/dnd-kit';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    ...DndKit,
  ],
});
```

</Steps>

## Manual Usage

<Steps>

### Installation

```bash
npm install @platejs/dnd react-dnd react-dnd-html5-backend
```

### Add Plugin

```tsx
import { DndPlugin } from '@platejs/dnd';
import { createPlateEditor } from 'platejs/react';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    DndPlugin,
  ],
});
```

### Configure Plugin

Configure drag and drop with a draggable component and DnD provider:

```tsx
import { DndProvider } from 'react-dnd';
import { HTML5Backend } from 'react-dnd-html5-backend';
import { DndPlugin } from '@platejs/dnd';

DndPlugin.configure({
  render: {
    aboveSlate: ({ children }) => (
      <DndProvider backend={HTML5Backend}>{children}</DndProvider>
    ),
  },
});
```

- `render.aboveNodes`: Assigns [`BlockDraggable`](/docs/components/block-draggable) to render drag handles above blocks.
- `render.aboveSlate`: Wraps the editor with `DndProvider` and `HTML5Backend`. Remove this if you already have `DndProvider` in your React tree.

### Advanced Configuration

Add automatic scrolling and file drop handling:

```tsx
import { DndPlugin } from '@platejs/dnd';
import { PlaceholderPlugin } from '@platejs/media/react';

DndPlugin.configure({
  options: {
    enableScroller: true,
    onDropFiles: ({ dragItem, editor, target }) => {
      editor
        .getTransforms(PlaceholderPlugin)
        .insert.media(dragItem.files, { at: target, nextBlock: false });
    },
  },
  render: {
    aboveNodes: BlockDraggable,
    aboveSlate: ({ children }) => (
      <DndProvider backend={HTML5Backend}>{children}</DndProvider>
    ),
  },
});
```

- `enableScroller`: Enables automatic scrolling when dragging blocks near the viewport edges.
- `onDropFiles`: Handles file drops by inserting them as media blocks at the target location.

</Steps>

## Plugins

### `DndPlugin`

Plugin for drag and drop functionality within the editor.

<API name="DndPlugin">
<APIOptions>
  <APIItem name="enableScroller" type="boolean" optional>
    Enables automatic scrolling when dragging blocks near viewport edges.
    - **Default:** `false`
  </APIItem>
  <APIItem name="scrollerProps" type="Partial<ScrollerProps>" optional>
    Props for the `Scroller` component when `enableScroller` is true.
  </APIItem>
  <APIItem name="onDropFiles" type="function" optional>
    Handler for file drop events.
    <APISubList>
      <APISubListItem parent="onDropFiles" name="id" type="string">
        ID of the target element.
      </APISubListItem>
      <APISubListItem parent="onDropFiles" name="dragItem" type="FileDragItemNode">
        Object containing the dropped files.
      </APISubListItem>
      <APISubListItem parent="onDropFiles" name="editor" type="PlateEditor">
        The editor instance.
      </APISubListItem>
      <APISubListItem parent="onDropFiles" name="target" type="Path">
        Path where files should be inserted.
      </APISubListItem>
    </APISubList>
  </APIItem>
  <APIItem name="dropTarget" type="{ id: string | null; line: DropLineDirection }" optional>
    The current drop target state containing both the target element id and drop line direction.
  </APIItem>
</APIOptions>
</API>

## API

### `focusBlockStartById`

Selects the start of a block by ID and focuses the editor.

<API name="focusBlockStartById">
<APIParameters>
  <APIItem name="id" type="string">
    The ID of the block to be focused.
  </APIItem>
</APIParameters>
</API>

### `getBlocksWithId`

Returns an array of blocks that have an ID.

<API name="getBlocksWithId">
<APIOptions type="EditorNodesOptions">
  The options for getting node entries.
</APIOptions>

<APIReturns type="NodeEntry[]">
  Array of blocks that have an ID.
</APIReturns>
</API>

### `selectBlockById`

Selects a block by its ID.

<API name="selectBlockById">
<APIParameters>
  <APIItem name="id" type="string">
    The ID of the block to select.
  </APIItem>
</APIParameters>
</API>

## Hooks

### `useDndNode`

A custom hook that combines the `useDragNode` and `useDropNode` hooks to enable dragging and dropping of a node from the editor. It provides a default preview for the dragged node, which can be customized or disabled.

<API name="useDndNode">
<APIOptions type="UseDndNodeOptions">
  <APIItem name="element" type="TElement">
    The node to be dragged.
  </APIItem>
  <APIItem name="type" type="string" optional>
    The type of drag item.
    - **Default:** `'block'`
  </APIItem>
  <APIItem name="nodeRef" type="any">
    The ref of the node to be dragged.
  </APIItem>
  <APIItem name="orientation" type="'horizontal' | 'vertical'" optional>
    The orientation of drag and drop.
    - **Default:** `'vertical'`
  </APIItem>
  <APIItem name="canDropNode" type="(args: { dragEntry: NodeEntry; dragItem: DragItemNode; dropEntry: NodeEntry; editor: PlateEditor }) => boolean" optional>
    Callback to determine if a node can be dropped at the current location.
  </APIItem>
  <APIItem name="preview" type="previewOptions" optional>
    The preview options for the dragged node.
  </APIItem>
  <APIItem name="drag" type="dragOptions" optional>
    The drag options for the dragged node.
  </APIItem>
  <APIItem name="drop" type="dropOptions" optional>
    The drop options for the dragged node.
  </APIItem>
  <APIItem name="onDropHandler" type="string" optional>
    Handler called when the node is dropped.
  </APIItem>
</APIOptions>

<APIReturns type="object">
  <APIItem name="isDragging" type="boolean">
    Whether the node is currently being dragged.
  </APIItem>
  <APIItem name="isOver" type="boolean">
    Whether the dragged node is over a drop target.
  </APIItem>
  <APIItem name="dragRef" type="ConnectDragSource">
    Drag reference for the draggable element.
  </APIItem>
</APIReturns>
</API>

### `useDragNode`

A custom hook that enables dragging of a node from the editor using the `useDrag` hook from `react-dnd`.

<API name="useDragNode">
<APIOptions type="UseDragNodeOptions">
  <APIItem name="element" type="TElement">
    The node to be dragged.
  </APIItem>
  <APIItem name="item" type="DragObject | DragObjectFactory<DragObject>" optional>
    Drag object or factory function that returns it.
  </APIItem>
</APIOptions>
</API>

### `useDraggable`

A custom hook that enables draggable behavior for a given element. It provides a preview for the element, which can be customized or disabled.

<API name="useDraggable">
<APIOptions type="object">
  <APIItem name="element" type="TElement">
    The element to make draggable.
  </APIItem>
  <APIItem name="orientation" type="'horizontal' | 'vertical'" optional>
    Orientation of drag and drop.
    - **Default:** `'vertical'`
  </APIItem>
  <APIItem name="type" type="string" optional>
    Type of drag item.
    - **Default:** `'block'`
  </APIItem>
  <APIItem name="onDropHandler" type="function" optional>
    Handler called when element is dropped.
  </APIItem>
</APIOptions>

<APIReturns type="object">
  <APIItem name="handleRef" type="(element: Element | React.ReactElement | React.RefObject<any> | null) => void">
    Drag source connector function.
  </APIItem>
  <APIItem name="isDragging" type="boolean">
    Whether element is being dragged.
  </APIItem>
  <APIItem name="previewRef" type="React.RefObject<HTMLDivElement>">
    Reference to draggable element.
  </APIItem>
</APIReturns>
</API>

### `useDropNode`

A custom hook that enables dropping a node on the editor. It uses the `useDrop` hook from `react-dnd` to handle the drop behavior.

<API name="useDropNode">
<APIOptions type="UseDropNodeOptions">
  <APIItem name="nodeRef" type="any">
    Reference to the node being dragged.
  </APIItem>
  <APIItem name="element" type="TElement">
    The node to which the drop line is attached.
  </APIItem>
  <APIItem name="dropLine" type="string">
    Current value of the drop line.
  </APIItem>
  <APIItem name="onChangeDropLine" type="function">
    Callback when drop line changes.
  </APIItem>
  <APIItem name="onDropHandler" type="object">
    Callback that intercepts drop handling.
    - Returns `true` to prevent default behavior
    - Returns `false` to run default behavior after
  </APIItem>
</APIOptions>
</API>

### `useDropLine`

Returns the current drop line state for an element.

<API name="useDropLine">
<APIOptions type="object">
  <APIItem name="id" type="string" optional>
    Element ID to show drop line for.
    - **Default:** Current element ID
  </APIItem>
  <APIItem name="orientation" type="'horizontal' | 'vertical'" optional>
    Filter drop lines by orientation.
    - **Default:** `'vertical'`
  </APIItem>
</APIOptions>

<APIReturns type="object">
  <APIItem name="dropLine" type="'top' | 'bottom' | 'left' | 'right' | ''">
    Current drop line direction.
  </APIItem>
</APIReturns>
</API>


# Find

Source: https://platejs.org/docs/find-replace

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Find
description: Highlight search matches in editable text.
docs:
  - route: /docs/components/search-highlight-node
    title: Search Highlight Leaf
  - route: /docs/examples/find-replace
    title: Find Replace Demo
---

Find highlights matching text in editor blocks. `FindReplacePlugin` owns the search option and decorations; your UI owns the search input and any replace command.

[find-replace-demo registry content](https://platejs.org/r/find-replace-demo)

<PackageInfo>

## Features

- Case-insensitive search highlighting.
- Multiple matches inside the same block.
- Matches split across adjacent text leaves.
- App-controlled search state through plugin options.
- Registry highlight leaf for visible matches.

</PackageInfo>

## Fast Path

<Steps>

### Add The Plugin

Configure `FindReplacePlugin` with a leaf renderer for highlighted ranges.

```tsx
import { FindReplacePlugin } from '@platejs/find-replace';
import { createPlateEditor } from 'platejs/react';

import { SearchHighlightLeaf } from '@/components/ui/search-highlight-node';

export const editor = createPlateEditor({
  plugins: [
    FindReplacePlugin.configure({
      render: { node: SearchHighlightLeaf },
    }),
  ],
});
```

### Control The Search

Update the `search` option from your toolbar and ask Plate to redecorate the editor.

```tsx title="components/find-toolbar.tsx" showLineNumbers
import { FindReplacePlugin } from '@platejs/find-replace';
import { useEditorPlugin, usePluginOption } from 'platejs/react';

export function FindToolbar() {
  const { editor, setOption } = useEditorPlugin(FindReplacePlugin);
  const search = usePluginOption(FindReplacePlugin, 'search');

  return (
    <input
      type="search"
      value={search}
      onChange={(event) => {
        setOption('search', event.target.value);
        editor.api.redecorate();
      }}
    />
  );
}
```

### Use The Registry Example

The demo combines `FindReplacePlugin`, `FixedToolbar`, `Input`, and `SearchHighlightLeaf`.

[find-replace-demo registry content](https://platejs.org/r/find-replace-demo)

</Steps>

## Ownership

| Surface | Owner | What It Does |
|---------|-------|--------------|
| `FindReplacePlugin` | `@platejs/find-replace` | Stores `options.search`, registers a leaf node, and wires `decorateFindReplace`. |
| `decorateFindReplace` | `@platejs/find-replace` | Finds matches in one element's text children and returns Slate ranges. |
| `SearchHighlightLeaf` | Registry UI | Renders decorated ranges with a yellow background. |
| `FindToolbar` | App or registry example | Updates `options.search` and calls `editor.api.redecorate()`. |
| Replace actions | App code | Perform text replacement with editor transforms. The package does not replace content for you. |

The package is headless. The registry gives you a visible highlight leaf and a demo toolbar.

## Search Behavior

| Behavior | Source |
|----------|--------|
| Empty `search` | Returns no ranges. |
| Case handling | Text and query are lowercased before matching. |
| Match scope | Only element nodes whose direct children are all text nodes are decorated. |
| Multiple matches | Each match becomes one or more ranges. |
| Split text leaves | A match crossing adjacent leaves is split into per-leaf ranges. |
| Range payload | Each range includes `[FindReplacePlugin.key]: true` and the matched `search` slice. |

`decorateFindReplace` searches the concatenated text for one element, then maps each match back to the original child text paths.

## Search Highlight Leaf

Install the registry leaf when you want the default yellow highlight.

```bash
npx shadcn@latest add @plate/search-highlight-node
```

The copied component is intentionally small:

```tsx title="components/ui/search-highlight-node.tsx"
import { type PlateLeafProps, PlateLeaf } from 'platejs/react';

export function SearchHighlightLeaf(props: PlateLeafProps) {
  return <PlateLeaf {...props} className="bg-yellow-100" />;
}
```

Change the class name when your design system needs a different search color.

## API Reference

| API | Package | Use |
|-----|---------|-----|
| `FindReplacePlugin` | `@platejs/find-replace` | Main plugin for search highlighting. |
| `options.search` | `string` | Query text to highlight. Defaults to `''`. |
| `decorateFindReplace` | `@platejs/find-replace` | Decoration function used by the plugin. |
| `SearchRange.search` | `string` | The query slice represented by that range. |



# Multi Select

Source: https://platejs.org/docs/multi-select

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Multi Select
docs:
  - route: /docs/components/tag-node
  - route: /docs/components/select-editor
---

[select-editor-demo registry content](https://platejs.org/r/select-editor-demo)

<PackageInfo>

## Features

Unlike traditional input-based multi-selects, this component is built on top of Plate editor, providing:

- Full history support (undo/redo)
- Native cursor navigation between and within tags
- Select one to many tags
- Copy/paste tags
- Drag and drop to reorder tags
- Read-only mode
- Duplicate tags prevention
- Create new tags with case insensitive matching
- Search text cleanup and whitespace trimming
- Fuzzy search powered by [cmdk](https://github.com/pacocoursey/cmdk)

</PackageInfo>

## Manual Usage

<Steps>

### Installation

```bash
npm install @platejs/tag
```

### Add Plugins

```tsx
import { MultiSelectPlugin } from '@platejs/tag/react';
import { createPlateEditor } from 'platejs/react';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    MultiSelectPlugin, // Multi-select editor with tag functionality
  ],
});
```

### Configure Plugins

```tsx
import { MultiSelectPlugin } from '@platejs/tag/react';
import { createPlateEditor } from 'platejs/react';
import { TagElement } from '@/components/ui/tag-node';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    MultiSelectPlugin.withComponent(TagElement),
  ],
});
```

- `MultiSelectPlugin`: Extends TagPlugin and constrains the editor to only contain tag elements
- `withComponent`: Assigns [`TagElement`](/docs/components/tag-node) to render tag components

### Add SelectEditor

<ComponentInstallation name="select-editor" inline />

### Basic Example

```tsx
import { MultiSelectPlugin } from '@platejs/tag/react';
import { TagElement } from '@/components/ui/tag-node';
import {
  SelectEditor,
  SelectEditorContent,
  SelectEditorInput,
  SelectEditorCombobox,
  type SelectItem,
} from '@/components/ui/select-editor';

// Define your items
const ITEMS: SelectItem[] = [
  { value: 'React' },
  { value: 'TypeScript' },
  { value: 'JavaScript' },
];

export default function MySelectEditor() {
  const [value, setValue] = React.useState<SelectItem[]>([ITEMS[0]]);

  return (
    <SelectEditor
      value={value}
      onValueChange={setValue}
      items={ITEMS}
    >
      <SelectEditorContent>
        <SelectEditorInput placeholder="Select items..." />
        <SelectEditorCombobox />
      </SelectEditorContent>
    </SelectEditor>
  );
}
```

### Form Example

[select-editor-demo registry content](https://platejs.org/r/select-editor-demo)

</Steps>

## Plugins

### TagPlugin

Inline void element plugin for individual tag functionality.

### MultiSelectPlugin

Extension of `TagPlugin` that constrains the editor to only contain tag elements, enabling multi-select behavior with automatic text cleanup and duplicate prevention.

## API

### tf.insert.tag

Inserts new multi-select element at current selection.

<API name="tf.insert.tag">
<APIParameters>
  <APIItem name="props" type="TTagProps">
    Properties for multi-select element.
  </APIItem>
</APIParameters>

<APIOptions type="TTagProps">
  <APIItem name="value" type="string">
    Unique value of multi-select element.
  </APIItem>
</APIOptions>
</API>

### getSelectedItems

Gets all tag items in the editor.

<API name="getSelectedItems">
<APIReturns type="TTagProps[]">
  Array of tag items in editor.
</APIReturns>
</API>

### isEqualTags

Utility function to compare two sets of tags for equality, ignoring order.

<API name="isEqualTags">
<APIParameters>
  <APIItem name="newTags" type="TTagProps[]" optional>
    New tags to compare against current editor tags.
  </APIItem>
</APIParameters>

<APIReturns type="boolean">
  Whether both sets contain same values.
</APIReturns>
</API>

## Hooks

### useSelectedItems

Hook to get the currently selected tag items in the editor.

<API name="useSelectedItems">
<APIReturns type="TTagProps[]">
  Array of selected tag items with values and properties.
</APIReturns>
</API>

### useSelectableItems

Hook to get the available items that can be selected, filtered by search and excluding already selected items.

<API name="useSelectableItems">
<APIOptions type="options">
  <APIItem name="allowNew" type="boolean" optional>
    Whether to allow creating new items.
    - **Default:** `true`
  </APIItem>
  <APIItem name="filter" type="(value: string, search: string) => boolean" optional>
    Custom filter function for items.
  </APIItem>
  <APIItem name="items" type="T[]" optional>
    Array of available items.
  </APIItem>
  <APIItem name="newItemFilter" type="(search: string) => boolean" optional>
    Filter function for new items.
  </APIItem>
  <APIItem name="newItemPosition" type="'end' | 'start'" optional>
    Position of new items in list.
    - **Default:** `'end'`
  </APIItem>
</APIOptions>

<APIReturns type="T[]">
  Filtered array of selectable items.
</APIReturns>
</API>

### useSelectEditorCombobox

Hook to handle combobox behavior in the editor, including text cleanup and item selection.

<API name="useSelectEditorCombobox">
<APIOptions type="options">
  <APIItem name="open" type="boolean">
    Whether combobox is open.
  </APIItem>
  <APIItem name="selectFirstItem" type="() => void">
    Function to select first combobox item.
  </APIItem>
  <APIItem name="onValueChange" type="(items: TTagProps[]) => void" optional>
    Callback when selected items change.
  </APIItem>
</APIOptions>
</API>

## Types

### TTagElement

```ts
type TTagElement = TElement & {
  value: string;
  [key: string]: unknown;
};
```

### TTagProps

```ts
type TTagProps = {
  value: string;
  [key: string]: unknown;
};
```

# Navigation Feedback

Source: https://platejs.org/docs/navigation-feedback

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Navigation Feedback
description: Flash a landed target after TOC, footnote, search, or custom navigation jumps.
---

[toc-demo registry content](https://platejs.org/r/toc-demo)

<PackageInfo>

## Features

- Briefly highlight the landed node after a navigation jump.
- Replace any previous flash deterministically — no stacked timers, no doubled animations.
- Expose transforms for flash-only and full select-focus-scroll-flash flows.
- Inject `data-nav-*` attributes so any render can style the active target.

</PackageInfo>

Navigation Feedback is a small core plugin for "you landed here" UX. It doesn't own navigation itself — it flashes the landed node so the reader can see where the editor just moved. Reach for it in TOC jumps, footnote navigation, search results, and custom outline surfaces.

## Usage

<Steps>

### Core Plugin

`NavigationFeedbackPlugin` is part of Plate core and is included by `createPlateEditor` automatically. You don't need to add it to the `plugins` array for the defaults to work.

### Configure Duration

The default flash lasts 1.6 seconds. If you want it tighter or longer, use the top-level `navigationFeedback` editor option:

```tsx
import { createPlateEditor } from 'platejs/react';

const editor = createPlateEditor({
  navigationFeedback: {
    duration: 1200,
  },
});
```

- `navigationFeedback.duration`: Default flash duration in milliseconds. **Default:** `1600`.

Disable the plugin entirely if you don't want any landed-target flash:

```tsx
const editor = createPlateEditor({
  navigationFeedback: false,
});
```

### Flash a Target

When another action already handled scroll, focus, and selection, and you only want the visual confirmation, call `editor.tf.navigation.flashTarget`:

```tsx
editor.tf.navigation.flashTarget({
  target: {
    path: [12],
    type: 'node',
  },
});
```

The call returns `false` when the path doesn't resolve to a node, so you can branch on stale targets without throwing.

Override the duration or variant per call when this jump deserves its own look:

```tsx
editor.tf.navigation.flashTarget({
  duration: 1500,
  target: {
    path: [12],
    type: 'node',
  },
  variant: 'mention',
});
```

The `variant` string is written straight to `data-nav-highlight`, so you can key distinct CSS animations off it — `'navigated'`, `'mention'`, `'found'`, whatever you need.

### Navigate and Flash

Most navigation actions should do four things at once: move the selection, focus the editor, scroll the target into view, and flash the landed node. `editor.tf.navigation.navigate` does all four, and each step is independent — skip any of them with the flags below.

Here's how the footnote plugin jumps from a reference to its definition:

```tsx
editor.tf.navigation.navigate({
  focus: true,
  scroll: true,
  scrollTarget: point,
  select: {
    anchor: { offset: 0, path: firstTextPath },
    focus: { offset: 0, path: firstTextPath },
  },
  target: {
    path: definition[1],
    type: 'node',
  },
});
```

Skip the flash when the jump should be silent:

```tsx
editor.tf.navigation.navigate({
  flash: false,
  select: point,
  target: { path: [12], type: 'node' },
});
```

Or tune the flash per call:

```tsx
editor.tf.navigation.navigate({
  flash: { duration: 1200, variant: 'mention' },
  select: point,
  target: { path: [12], type: 'node' },
});
```

If you don't pass `scrollTarget`, Plate picks a scroll point in this order: `select.focus`, `select.anchor`, `select` (when it's a `Point`), then `editor.api.start(target.path)`.

### Style the Landed Target

Whenever a target is active, the plugin injects transient attributes onto that node's DOM and a CSS variable with the current duration:

| Attribute | Value |
| --- | --- |
| `data-nav-target` | `"true"` on the active node. |
| `data-nav-highlight` | Current `variant` (e.g. `"navigated"`). |
| `data-nav-cycle` | `"0"` or `"1"` — alternates per flash so CSS animations restart cleanly. |
| `data-nav-pulse` | Monotonic pulse counter. Useful for debugging repeat triggers. |
| `--plate-nav-feedback-duration` | Inline CSS variable set to `${duration}ms`. |

Style them anywhere your editor styles live:

```css
.slate-editor [data-nav-highlight] {
  border-radius: 0.375rem;
}

.slate-editor [data-nav-highlight][data-nav-cycle='0'] {
  animation: plate-nav-highlight-a var(--plate-nav-feedback-duration, 900ms)
    ease-out;
}

.slate-editor [data-nav-highlight][data-nav-cycle='1'] {
  animation: plate-nav-highlight-b var(--plate-nav-feedback-duration, 900ms)
    ease-out;
}
```

<Callout type="info">
  **Why two animations?** Flashing the same node twice in a row on the same keyframe name wouldn't restart the animation. The plugin alternates `data-nav-cycle` between `0` and `1` so adjacent flashes run different animation names and the browser replays cleanly.
</Callout>

### Highlight Custom Renders

Attribute injection fires through the plugin's `nodeProps` inject, so any standard `PlateElement` render that spreads its `attributes` onto the root DOM node picks up `data-nav-*` for free.

For atoms, inline voids, or components that need the highlight state inside JSX (e.g. on a nested button), read it with `useNavigationHighlight`:

```tsx
import { useNavigationHighlight, usePath } from 'platejs/react';

export function FootnoteReferenceElement(props) {
  const path = usePath();
  const highlight = useNavigationHighlight(path);

  return (
    <PlateElement
      {...props}
      attributes={{
        ...props.attributes,
        'data-nav-cycle': highlight ? String(highlight.cycle) : undefined,
        'data-nav-highlight': highlight?.variant,
        'data-nav-pulse': highlight ? String(highlight.pulse) : undefined,
        'data-nav-target': highlight ? 'true' : undefined,
        style: {
          ...props.attributes.style,
          '--plate-nav-feedback-duration': highlight
            ? `${highlight.duration}ms`
            : undefined,
        },
      }}
    >
      {props.children}
    </PlateElement>
  );
}
```

The hook returns `null` when this node isn't the active target and the full target (`{ cycle, duration, path, pulse, type, variant }`) when it is. Pass a `Path`, a `TElement`, or a `TText` — paths go through, nodes get resolved via `editor.api.findPath`.

Done. You now have a deterministic flash on every jump and the wiring to style or extend it.

</Steps>

## Plugins

### `NavigationFeedbackPlugin`

Core plugin for transient "landed target" feedback after successful navigation.

<API name="NavigationFeedbackPlugin">
<APIOptions>
  <APIItem name="duration" type="number">
    Default flash duration in milliseconds.
    - **Default:** `1600`
  </APIItem>
</APIOptions>
</API>

## API

### `api.navigation.activeTarget`

Get the current flashed target, or `null` when none is active. The returned target carries a resolved `path`, so later edits that shift the target keep the highlight on the right node.

<API name="activeTarget">
<APIReturns>
  <APIItem name="return" type="NavigationFeedbackActiveTarget | null">
    Active target `{ cycle, duration, path, pulse, type, variant }`, or `null`.
  </APIItem>
</APIReturns>
</API>

### `api.navigation.clear`

Clear the current feedback target immediately. Safe to call when nothing is active.

<API name="clear" />

### `api.navigation.isTarget`

Check whether a given path is the current flashed target.

<API name="isTarget">
<APIParameters>
  <APIItem name="path" type="Path">
    Path to compare against the active target.
  </APIItem>
</APIParameters>
<APIReturns>
  <APIItem name="return" type="boolean">
    `true` when there is an active target and its path equals `path`.
  </APIItem>
</APIReturns>
</API>

## Transforms

### `tf.navigation.flashTarget`

Flash a target node without changing selection, focus, or scroll. Replaces any active flash on the same editor.

<API name="flashTarget">
<APIParameters>
  <APIItem name="target" type="{ path: Path; type: 'node' }">
    Node target to flash.
  </APIItem>
  <APIItem name="duration" type="number" optional>
    Override the default duration for this call.
  </APIItem>
  <APIItem name="variant" type="string" optional>
    Highlight variant stored in `data-nav-highlight`.
    - **Default:** `navigated`
  </APIItem>
</APIParameters>
<APIReturns>
  <APIItem name="return" type="boolean">
    `false` when the path doesn't resolve to a node, `true` otherwise.
  </APIItem>
</APIReturns>
</API>

### `tf.navigation.navigate`

Select, focus, scroll, and flash a target in one call. Each step is independent — skip any of them with the flags below.

<API name="navigate">
<APIParameters>
  <APIItem name="target" type="{ path: Path; type: 'node' }">
    Node target to navigate to.
  </APIItem>
  <APIItem name="select" type="Point | TRange" optional>
    Point (collapsed) or range to apply before scrolling and flashing.
  </APIItem>
  <APIItem name="focus" type="boolean" optional>
    Focus the editor after selection.
    - **Default:** `true`
  </APIItem>
  <APIItem name="scroll" type="boolean" optional>
    Scroll the resolved point into view.
    - **Default:** `true`
  </APIItem>
  <APIItem name="scrollTarget" type="Point" optional>
    Explicit point to scroll into view. Falls back to `select.focus`, `select.anchor`, `select`, then `editor.api.start(target.path)`.
  </APIItem>
  <APIItem name="flash" type="false | { duration?: number; variant?: string }" optional>
    Per-call flash config. Pass `false` to navigate without flashing.
  </APIItem>
</APIParameters>
<APIReturns>
  <APIItem name="return" type="boolean">
    `false` when the path doesn't resolve to a node, `true` otherwise.
  </APIItem>
</APIReturns>
</API>

### `tf.navigation.clear`

Clear the current flashed target immediately. Same effect as `api.navigation.clear`.

<API name="clear" />

## Hooks

### `useNavigationHighlight`

Subscribe a custom render to the active navigation target. Returns the target metadata when the given path/node matches, `null` otherwise.

<API name="useNavigationHighlight">
<APIParameters>
  <APIItem name="target" type="Path | TElement | TText | null | undefined">
    Path to compare, or a node the hook resolves via `editor.api.findPath`.
  </APIItem>
</APIParameters>
<APIReturns>
  <APIItem name="return" type="NavigationFeedbackActiveTarget | null">
    Active target metadata when this node is the current flashed target, `null` otherwise.
  </APIItem>
</APIReturns>
</API>

## Related Docs

- [Table of Contents](/docs/toc)
- [Footnote](/docs/footnote)
- [Editor Methods](/docs/editor-methods)
- [Plugin Configuration](/docs/plugin)


# Tabbable

Source: https://platejs.org/docs/tabbable

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Tabbable
---

[tabbable-demo registry content](https://platejs.org/r/tabbable-demo)

<PackageInfo>

## Features

- Ensures consistent tab order between tabbable elements in the editor
- Manages focus transitions between void elements and external DOM elements

</PackageInfo>

## Kit Usage

<Steps>

### Installation

The fastest way to add the tabbable plugin is with the `TabbableKit`, which includes pre-configured `TabbablePlugin` with smart query logic to avoid conflicts with other plugins.

[tabbable-kit registry content](https://platejs.org/r/tabbable-kit)

### Add Kit

```tsx
import { createPlateEditor } from 'platejs/react';
import { TabbableKit } from '@/components/editor/plugins/tabbable-kit';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    ...TabbableKit,
  ],
});
```

</Steps>

## Manual Usage

<Steps>

### Installation

```bash
npm install @platejs/tabbable
```

### Add Plugin

```tsx
import { TabbablePlugin } from '@platejs/tabbable/react';
import { createPlateEditor } from 'platejs/react';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    TabbablePlugin,
  ],
});
```

### Configure Plugin

```tsx
import { TabbablePlugin } from '@platejs/tabbable/react';
import { createPlateEditor } from 'platejs/react';
import { KEYS } from 'platejs';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    TabbablePlugin.configure({
      options: {
        query: (event) => {
          // Disable when in lists or code blocks
          const inList = editor.api.some({ match: { type: KEYS.li } });
          const inCodeBlock = editor.api.some({ match: { type: KEYS.codeBlock } });
          return !inList && !inCodeBlock;
        },
        globalEventListener: true,
        isTabbable: (tabbableEntry) => 
          editor.api.isVoid(tabbableEntry.slateNode),
      },
    }),
  ],
});
```

- `options.query`: Function to dynamically enable/disable the plugin based on editor state.
- `options.globalEventListener`: When `true`, adds event listener to document instead of editor.
- `options.isTabbable`: Function to determine which elements should be included in tab order.

</Steps>

## Advanced Usage

### Conflicts with Other Plugins

The Tabbable plugin may cause issues with other plugins that handle the `Tab` key, such as:

- Lists
- Code blocks
- Indent plugin

Use the `query` option to disable the Tabbable plugin when the `Tab` key should be handled by another plugin:

```tsx
query: (event) => {
  const inList = editor.api.some({ match: { type: KEYS.li } });
  const inCodeBlock = editor.api.some({ match: { type: KEYS.codeBlock } });
  return !inList && !inCodeBlock;
},
```

Alternatively, if you're using the Indent plugin, you can enable the Tabbable plugin only when a specific type of node is selected, such as voids:

```tsx
query: (event) => !!editor.api.some({
  match: (node) => editor.api.isVoid(node),
}),
```

### Non-void Slate Nodes

One `TabbableEntry` will be created for each tabbable DOM element in the editor, as determined using the [tabbable](https://www.npmjs.com/package/tabbable) NPM package. The list of tabbables is then filtered using `isTabbable`.

By default, `isTabbable` only returns true for entries inside void Slate nodes. You can override `isTabbable` to add support for DOM elements contained in other types of Slate node:

```tsx
// Enable tabbable DOM elements inside CUSTOM_ELEMENT
isTabbable: (tabbableEntry) => (
  tabbableEntry.slateNode.type === CUSTOM_ELEMENT ||
  editor.api.isVoid(tabbableEntry.slateNode)
),
```

### DOM Elements Outside the Editor

In some circumstances, you may want to allow users to tab from the editor to a DOM element rendered outside the editor, such as an interactive popover.

To do this, override `insertTabbableEntries` to return an array of `TabbableEntry` objects, one for each DOM element outside the editor that you want to include in the tabbable list. The `slateNode` and `path` of the `TabbableEntry` should refer to the Slate node the user's cursor will be inside when the DOM element should be tabbable to.

Set the `globalEventListener` option to `true` to make sure the Tabbable plugin is able to return the user's focus to the editor.

For example, if the DOM element appears when a link is selected, the `slateNode` and `path` should be that of the link.

```tsx
// Add buttons inside .my-popover to the list of tabbables
globalEventListener: true,
insertTabbableEntries: (event) => {
  const [selectedNode, selectedNodePath] = editor.api.node(editor.selection);

  return [
    ...document.querySelectorAll('.my-popover > button'),
  ].map((domNode) => ({
    domNode,
    slateNode: selectedNode,
    path: selectedNodePath,
  }));
},
```

## Plugins

### TabbablePlugin

Plugin for managing tab order between tabbable elements.

<API name="TabbablePlugin">
<APIOptions>
  <APIItem name="query" type="(event: KeyboardEvent) => boolean" optional>
    Enable/disable plugin dynamically.
    - **Default:** `() => true`
  </APIItem>
  <APIItem name="globalEventListener" type="boolean" optional>
    Add event listener to document instead of editor.
    - **Default:** `false`
  </APIItem>
  <APIItem name="insertTabbableEntries" type="(event: KeyboardEvent) => TabbableEntry[]" optional>
    Add additional tabbable entries outside editor.
    - **Default:** `() => []`
  </APIItem>
  <APIItem name="isTabbable" type="(tabbableEntry: TabbableEntry) => boolean" optional>
    Determine if element should be tabbable.
    - **Default:** `(tabbableEntry) => editor.api.isVoid(tabbableEntry.slateNode)`
  </APIItem>
</APIOptions>
</API>

## Types

### TabbableEntry

Defines the properties of a tabbable entry.

<API name="TabbableEntry">
<APIAttributes>
  <APIItem name="domNode" type="HTMLElement">
    HTML element representing tabbable entry.
  </APIItem>
  <APIItem name="slateNode" type="TNode">
    Corresponding Slate node.
  </APIItem>
  <APIItem name="path" type="Path">
    Path to Slate node in document.
  </APIItem>
</APIAttributes>
</API>

# Toolbar

Source: https://platejs.org/docs/toolbar

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Toolbar
description: Fixed and floating toolbars for your editor.
docs:
  - route: https://pro.platejs.org/docs/examples/floating-toolbar
    title: Plus
  - route: /docs/components/fixed-toolbar
    title: Fixed Toolbar
  - route: /docs/components/floating-toolbar
    title: Floating Toolbar
---

[basic-nodes-demo registry content](https://platejs.org/r/basic-nodes-demo)

<PackageInfo>

## Features

- **Fixed Toolbar**: Persistent toolbar that sticks to the top of the editor
- **Floating Toolbar**: Contextual toolbar that appears on text selection
- **Customizable Buttons**: Easily add, remove, and reorder toolbar buttons
- **Responsive Design**: Adapts to different screen sizes and content
- **Plugin Integration**: Seamless integration with Plate plugins and UI components

</PackageInfo>

## Kit Usage

<Steps>

### Installation

The fastest way to add toolbar functionality is with the `FixedToolbarKit` and `FloatingToolbarKit`, which include pre-configured toolbar plugins along with their [Plate UI](/docs/installation/plate-ui) components.

[fixed-toolbar-kit registry content](https://platejs.org/r/fixed-toolbar-kit)
[floating-toolbar-kit registry content](https://platejs.org/r/floating-toolbar-kit)

- [`FixedToolbar`](/docs/components/fixed-toolbar): Renders a persistent toolbar above the editor
- [`FixedToolbarButtons`](/docs/components/fixed-toolbar-buttons): Pre-configured button set for the fixed toolbar
- [`FloatingToolbar`](/docs/components/floating-toolbar): Renders a contextual toolbar on text selection
- [`FloatingToolbarButtons`](/docs/components/floating-toolbar-buttons): Pre-configured button set for the floating toolbar

### Add Kit

```tsx
import { createPlateEditor } from 'platejs/react';
import { FixedToolbarKit } from '@/components/editor/plugins/fixed-toolbar-kit';
import { FloatingToolbarKit } from '@/components/editor/plugins/floating-toolbar-kit';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    ...FixedToolbarKit,
    ...FloatingToolbarKit,
  ],
});
```

</Steps>

## Manual Usage

<Steps>

### Create Plugins

```tsx
import { createPlatePlugin } from 'platejs/react';
import { FixedToolbar } from '@/components/ui/fixed-toolbar';
import { FixedToolbarButtons } from '@/components/ui/fixed-toolbar-buttons';
import { FloatingToolbar } from '@/components/ui/floating-toolbar';
import { FloatingToolbarButtons } from '@/components/ui/floating-toolbar-buttons';

const fixedToolbarPlugin = createPlatePlugin({
  key: 'fixed-toolbar',
  render: {
    beforeEditable: () => (
      <FixedToolbar>
        <FixedToolbarButtons />
      </FixedToolbar>
    ),
  },
});

const floatingToolbarPlugin = createPlatePlugin({
  key: 'floating-toolbar',
  render: {
    afterEditable: () => (
      <FloatingToolbar>
        <FloatingToolbarButtons />
      </FloatingToolbar>
    ),
  },
});

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    fixedToolbarPlugin,
    floatingToolbarPlugin,
  ],
});
```

- `render.beforeEditable`: Renders [`FixedToolbar`](/docs/components/fixed-toolbar) above the editor content
- `render.afterEditable`: Renders [`FloatingToolbar`](/docs/components/floating-toolbar) as an overlay after the editor

### Customizing Fixed Toolbar Buttons

The `FixedToolbarButtons` component contains the default set of buttons for the fixed toolbar.

[fixed-toolbar-buttons registry content](https://platejs.org/r/fixed-toolbar-buttons)

To customize it, you can edit `components/ui/fixed-toolbar-buttons.tsx`.

### Customizing Floating Toolbar Buttons

Similarly, you can customize the floating toolbar by editing `components/ui/floating-toolbar-buttons.tsx`.

[floating-toolbar-buttons registry content](https://platejs.org/r/floating-toolbar-buttons)


### Creating Custom Button

This example shows a button that inserts custom text into the editor.

```tsx
import { useEditorRef } from 'platejs/react';
import { CustomIcon } from 'lucide-react';
import { ToolbarButton } from '@/components/ui/toolbar';

export function CustomToolbarButton() {
  const editor = useEditorRef();

  return (
    <ToolbarButton
      onClick={() => {
        // Custom action
        editor.tf.insertText('Custom text');
      }}
      tooltip="Custom Action"
    >
      <CustomIcon />
    </ToolbarButton>
  );
}
```

### Creating Mark Button

For toggling marks like bold or italic, you can use the [`MarkToolbarButton`](/docs/components/mark-toolbar-button) component. It simplifies the process by handling the toggle state and action automatically.

This example creates a "Bold" button.

```tsx
import { BoldIcon } from 'lucide-react';

import { MarkToolbarButton } from '@/components/ui/mark-toolbar-button';

export function BoldToolbarButton() {
  return (
    <MarkToolbarButton nodeType="bold" tooltip="Bold (⌘+B)">
      <BoldIcon />
    </MarkToolbarButton>
  );
}
```

- `nodeType`: Specifies the mark to toggle (e.g., `bold`, `italic`).
- `tooltip`: Provides a helpful tooltip for the button.
- The `MarkToolbarButton` uses `useMarkToolbarButtonState` to get the toggle state and `useMarkToolbarButton` to get the `onClick` handler and other props.

### Turn Into Toolbar Button

The [`TurnIntoToolbarButton`](/docs/components/turn-into-toolbar-button) provides a dropdown menu to convert the current block into different types (headings, lists, quotes, etc.).

[turn-into-toolbar-button registry content](https://platejs.org/r/turn-into-toolbar-button)

To add a new block type to the turn-into options, edit the `turnIntoItems` array:

```tsx
const turnIntoItems = [
  // ... existing items
  {
    icon: <CustomIcon />,
    keywords: ['custom', 'special'],
    label: 'Custom Block',
    value: 'custom-block',
  },
];
```

### Insert Toolbar Button

The [`InsertToolbarButton`](/docs/components/insert-toolbar-button) provides a dropdown menu to insert various elements (blocks, lists, media, inline elements).

[insert-toolbar-button registry content](https://platejs.org/r/insert-toolbar-button)

To add a new insertable item, add it to the appropriate group in the `groups` array:

```tsx
{
  group: 'Basic blocks',
  items: [
    // ... existing items
    {
      icon: <CustomIcon />,
      label: 'Custom Block',
      value: 'custom-block',
    },
  ].map((item) => ({
    ...item,
    onSelect: (editor, value) => {
      insertBlock(editor, value);
    },
  })),
}
```

</Steps>

## Plate Plus

[floating-toolbar-pro registry content](https://platejs.org/r/floating-toolbar-pro)

## Plugins

### `FixedToolbarKit`

Plugin that renders a fixed toolbar above the editor content.

<API name="FixedToolbarKit">
<APIOptions>
  <APIItem name="render.beforeEditable" type="() => ReactNode">
    Renders the fixed toolbar before the editor content. Contains FixedToolbarButtons by default.
  </APIItem>
</APIOptions>
</API>

### `FloatingToolbarKit`

Plugin that renders a floating toolbar that appears on text selection.

<API name="FloatingToolbarKit">
<APIOptions>
  <APIItem name="render.afterEditable" type="() => ReactNode">
    Renders the floating toolbar as an overlay after the editor. Contains FloatingToolbarButtons by default.
  </APIItem>
</APIOptions>
</API> 

# Basic Marks

Source: https://platejs.org/docs/basic-marks

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Basic Marks
description: Common inline text formatting marks.
docs:
  - route: /docs/components/mark-toolbar-button
    title: Mark Toolbar Button
  - route: /docs/toolbar
    title: Toolbar
---

Basic Marks covers the common inline formatting marks: bold, italic, underline, strikethrough, code, subscript, superscript, highlight, and kbd. The package owns mark plugins and transforms; the registry kit adds leaf components, toolbar wiring, and Markdown-style input rules.

<Cards>

<Card icon="bold" title="Bold" href="/docs/bold">
Use `bold` for strong emphasis.
</Card>

<Card icon="italic" title="Italic" href="/docs/italic">
Use `italic` for emphasis or stylistic text.
</Card>

<Card icon="underline" title="Underline" href="/docs/underline">
Use `underline` for underlined text.
</Card>

<Card icon="strikethrough" title="Strikethrough" href="/docs/strikethrough">
Use `strikethrough` for deleted or replaced text.
</Card>

<Card icon="code" title="Code" href="/docs/code">
Use `code` for inline code and technical terms.
</Card>

<Card icon="subscript" title="Subscript" href="/docs/subscript">
Use `sub` for subscript text.
</Card>

<Card icon="superscript" title="Superscript" href="/docs/superscript">
Use `sup` for superscript text.
</Card>

<Card icon="kbd" title="Kbd" href="/docs/kbd">
Use `kbd` for keyboard shortcuts.
</Card>

<Card icon="highlight" title="Highlight" href="/docs/highlight">
Use `highlight` for marked text.
</Card>

</Cards>

[basic-marks-demo registry content](https://platejs.org/r/basic-marks-demo)

<PackageInfo>

## Features

- Leaf plugins for common mark keys.
- Toggle transforms through each mark plugin.
- HTML deserialization for semantic tags and styles.
- Markdown-style input rules in the registry kit.
- Registry leaves for code, highlight, and keyboard text.
- Toolbar support through `MarkToolbarButton`.

</PackageInfo>

## Kit Usage

<Steps>

### Add The Kit

`BasicMarksKit` is the full client-side registry kit. It includes mark plugins, input rules, `CodeLeaf`, `HighlightLeaf`, and `KbdLeaf`.

[basic-marks-kit registry content](https://platejs.org/r/basic-marks-kit)

```tsx
import { createPlateEditor } from 'platejs/react';

import { BasicMarksKit } from '@/components/editor/plugins/basic-marks-kit';

export const editor = createPlateEditor({
  plugins: [...BasicMarksKit],
});
```

### Add Toolbar Buttons

Use `MarkToolbarButton` for direct mark toggles.

```tsx
import { BoldIcon } from 'lucide-react';
import { KEYS } from 'platejs';

import { MarkToolbarButton } from '@/components/ui/mark-toolbar-button';

export function BoldToolbarButton() {
  return (
    <MarkToolbarButton nodeType={KEYS.bold} tooltip="Bold (⌘+B)">
      <BoldIcon />
    </MarkToolbarButton>
  );
}
```

</Steps>

## Ownership

| Surface | Owner | What It Does |
|---------|-------|--------------|
| `BasicMarksPlugin` | `@platejs/basic-nodes/react` | Groups bold, code, italic, strikethrough, subscript, superscript, and underline. |
| `BaseBasicMarksPlugin` | `@platejs/basic-nodes` | Headless grouping plugin for the same seven marks. |
| `BasicMarksKit` | Registry | Adds the full mark set, input rules, and client leaf components. |
| `BaseBasicMarksKit` | Registry | Adds static/base mark plugins with static code, highlight, and kbd leaves. |
| Individual mark plugins | `@platejs/basic-nodes` | Own mark keys, HTML parsing, render tags, and `toggle` transforms. |
| `MarkToolbarButton` | Registry UI | Reads mark state and calls the mark toolbar hook. |

`BasicMarksPlugin` is smaller than `BasicMarksKit`: highlight and kbd are separate plugins that the registry kit includes.

## Mark Set

| Mark | Plugin | Key | Render | Notes |
|------|--------|-----|--------|-------|
| Bold | `BoldPlugin` | `KEYS.bold` | `strong` | Deserializes `strong`, `b`, and bold font weight. |
| Italic | `ItalicPlugin` | `KEYS.italic` | `em` | Deserializes `em`, `i`, and italic font style. |
| Underline | `UnderlinePlugin` | `KEYS.underline` | `u` | Deserializes `u` and underline text decoration. |
| Strikethrough | `StrikethroughPlugin` | `KEYS.strikethrough` | `s` | Uses directional selection affinity. |
| Code | `CodePlugin` | `KEYS.code` | `code` | Uses hard selection affinity and skips `pre` HTML parents. |
| Subscript | `SubscriptPlugin` | `KEYS.sub` | `sub` | Toggle removes superscript. |
| Superscript | `SuperscriptPlugin` | `KEYS.sup` | `sup` | Toggle removes subscript. |
| Highlight | `HighlightPlugin` | `KEYS.highlight` | `mark` | Uses directional selection affinity. |
| Kbd | `KbdPlugin` | `KEYS.kbd` | `kbd` | Uses hard selection affinity. |

Each base mark plugin extends `editor.tf.<mark>.toggle()` by calling `editor.tf.toggleMark(type)`.

## Input Rules

`BasicMarksKit` registers input rules explicitly. The package plugins do not enable them by default.

| Rule Family | Kit Registration |
|-------------|------------------|
| `BoldRules.markdown` | `variant: '*'` and `variant: '_'` |
| `ItalicRules.markdown` | `variant: '*'` and `variant: '_'` |
| `UnderlineRules.markdown` | Default underline rule |
| `CodeRules.markdown` | Default inline code rule |
| `StrikethroughRules.markdown` | Default strikethrough rule |
| `SubscriptRules.markdown` | Default subscript rule |
| `SuperscriptRules.markdown` | Default superscript rule |
| `HighlightRules.markdown` | `variant: '=='` and `variant: '≡'` |
| `MarkComboRules.markdown` | Bold/italic/underline combinations |

See [Plugin Input Rules](/docs/plugin-input-rules) for the runtime model.

## Manual Usage

Install the package when you want to compose marks yourself.

```bash
npm install @platejs/basic-nodes
```

Add only the marks you need.

```tsx title="components/editor/mark-plugins.tsx"
import {
  BoldPlugin,
  CodePlugin,
  ItalicPlugin,
  UnderlinePlugin,
} from '@platejs/basic-nodes/react';

export const markPlugins = [
  BoldPlugin,
  ItalicPlugin,
  UnderlinePlugin,
  CodePlugin,
];
```

Use the individual pages for mark-specific setup and component details.

## API Reference

| API | Package | Use |
|-----|---------|-----|
| `BasicMarksPlugin` | `@platejs/basic-nodes/react` | React grouping plugin for seven common marks. |
| `BaseBasicMarksPlugin` | `@platejs/basic-nodes` | Headless grouping plugin for seven common marks. |
| `BasicMarksKit` | Registry | Full client kit with highlight, kbd, input rules, and leaves. |
| `BaseBasicMarksKit` | Registry | Static/base kit for server or static rendering. |
| `MarkToolbarButton` | Registry UI | Toolbar control for one mark key. |



# Bold

Source: https://platejs.org/docs/bold

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Bold
description: Add strong inline text formatting.
docs:
  - route: /docs/basic-marks
    title: Basic Marks
  - route: /docs/components/mark-toolbar-button
    title: Mark Toolbar Button
  - route: /docs/plugin-shortcuts
    title: Plugin Shortcuts
---

Bold applies the `bold` leaf mark to selected text. `BoldPlugin` owns the mark key, shortcut, HTML parsing, render tag, and toggle transform.

[basic-marks-demo registry content](https://platejs.org/r/basic-marks-demo)

<PackageInfo>

## Features

- `KEYS.bold` leaf mark.
- Default `⌘B` / `Ctrl+B` shortcut.
- HTML deserialization from `strong`, `b`, and bold font weight.
- `<strong>` rendering by default.
- Optional Markdown-style input rules through `BoldRules`.
- Toolbar support through `MarkToolbarButton`.

</PackageInfo>

## Kit Usage

<Steps>

### Add Basic Marks

`BasicMarksKit` includes `BoldPlugin`, bold input rules, and the standard toolbar buttons that use `KEYS.bold`.

[basic-marks-kit registry content](https://platejs.org/r/basic-marks-kit)

```tsx
import { createPlateEditor } from 'platejs/react';

import { BasicMarksKit } from '@/components/editor/plugins/basic-marks-kit';

export const editor = createPlateEditor({
  plugins: [...BasicMarksKit],
});
```

### Add A Toolbar Button

Use `MarkToolbarButton` with `KEYS.bold`.

```tsx
import { BoldIcon } from 'lucide-react';
import { KEYS } from 'platejs';

import { MarkToolbarButton } from '@/components/ui/mark-toolbar-button';

export function BoldToolbarButton() {
  return (
    <MarkToolbarButton nodeType={KEYS.bold} tooltip="Bold (⌘+B)">
      <BoldIcon />
    </MarkToolbarButton>
  );
}
```

</Steps>

## Manual Usage

Install the mark package.

```bash
npm install @platejs/basic-nodes
```

Add `BoldPlugin` directly when you do not want the whole kit.

```tsx
import { BoldPlugin } from '@platejs/basic-nodes/react';
import { createPlateEditor } from 'platejs/react';

export const editor = createPlateEditor({
  plugins: [BoldPlugin],
});
```

Register Markdown-style input rules when users should type bold delimiters.

```tsx
import { BoldRules } from '@platejs/basic-nodes';
import { BoldPlugin } from '@platejs/basic-nodes/react';

export const boldPlugin = BoldPlugin.configure({
  inputRules: [
    BoldRules.markdown({ variant: '*' }),
    BoldRules.markdown({ variant: '_' }),
  ],
});
```

## Ownership

| Surface | Owner | What It Does |
|---------|-------|--------------|
| `BaseBoldPlugin` | `@platejs/basic-nodes` | Headless bold mark, HTML parser, render tag, and `toggle` transform. |
| `BoldPlugin` | `@platejs/basic-nodes/react` | React wrapper with default `mod+b` shortcut. |
| `BoldRules.markdown` | `@platejs/basic-nodes` | Optional mark input rule factory. |
| `BasicMarksKit` | Registry | Adds `BoldPlugin` with `*` and `_` Markdown-style input rules. |
| `MarkToolbarButton` | Registry UI | Reads active mark state and calls the mark toggle hook. |

The package owns the mark. The registry owns toolbar placement and icon choice.

## Behavior

| Behavior | Source |
|----------|--------|
| Mark key | `KEYS.bold` |
| Leaf behavior | `node.isLeaf: true` |
| Toggle transform | `editor.tf.bold.toggle()` calls `editor.tf.toggleMark(type)`. |
| Shortcut | `BoldPlugin` registers `mod+b`. |
| HTML tags | `strong`, `b` |
| HTML styles | `font-weight: 600`, `700`, or `bold` |
| HTML guard | Ignores descendants where `fontWeight` is `normal`. |
| Render output | `strong` |

## API Reference

| API | Package | Use |
|-----|---------|-----|
| `BaseBoldPlugin` | `@platejs/basic-nodes` | Headless bold plugin. |
| `BoldPlugin` | `@platejs/basic-nodes/react` | React bold plugin with shortcut defaults. |
| `BoldRules.markdown(options)` | `@platejs/basic-nodes` | Creates a bold mark input rule. |
| `tf.bold.toggle()` | `@platejs/basic-nodes` | Toggles the bold mark at the selection. |



# Code

Source: https://platejs.org/docs/code

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Code
description: Add inline code formatting.
docs:
  - route: /docs/basic-marks
    title: Basic Marks
  - route: /docs/components/code-node
    title: Code Leaf
  - route: /docs/components/mark-toolbar-button
    title: Mark Toolbar Button
  - route: /docs/code-block
    title: Code Block
---

Code applies the `code` leaf mark to inline text. Use [Code Block](/docs/code-block) for fenced or multiline code; this page is only for inline code spans.

[basic-marks-demo registry content](https://platejs.org/r/basic-marks-demo)

<PackageInfo>

## Features

- `KEYS.code` leaf mark.
- Hard selection affinity.
- HTML deserialization from `code` tags and Consolas font styles.
- `<code>` rendering by default.
- Registry `CodeLeaf` for styled inline code.
- Optional Markdown-style input rule through `CodeRules`.

</PackageInfo>

## Kit Usage

<Steps>

### Add Basic Marks

`BasicMarksKit` includes `CodePlugin`, `CodeLeaf`, the backtick input rule, and a `mod+e` shortcut.

[basic-marks-kit registry content](https://platejs.org/r/basic-marks-kit)

```tsx
import { createPlateEditor } from 'platejs/react';

import { BasicMarksKit } from '@/components/editor/plugins/basic-marks-kit';

export const editor = createPlateEditor({
  plugins: [...BasicMarksKit],
});
```

### Add A Toolbar Button

Use `MarkToolbarButton` with `KEYS.code`.

```tsx
import { Code2Icon } from 'lucide-react';
import { KEYS } from 'platejs';

import { MarkToolbarButton } from '@/components/ui/mark-toolbar-button';

export function CodeToolbarButton() {
  return (
    <MarkToolbarButton nodeType={KEYS.code} tooltip="Code (⌘+E)">
      <Code2Icon />
    </MarkToolbarButton>
  );
}
```

</Steps>

## Manual Usage

Install the mark package.

```bash
npm install @platejs/basic-nodes
```

Add `CodePlugin` directly when you want the default `<code>` render.

```tsx
import { CodePlugin } from '@platejs/basic-nodes/react';
import { createPlateEditor } from 'platejs/react';

export const editor = createPlateEditor({
  plugins: [CodePlugin],
});
```

Configure the registry leaf, input rule, and shortcut when you want the same behavior as the kit.

```tsx
import { CodeRules } from '@platejs/basic-nodes';
import { CodePlugin } from '@platejs/basic-nodes/react';

import { CodeLeaf } from '@/components/ui/code-node';

export const codePlugin = CodePlugin.configure({
  inputRules: [CodeRules.markdown()],
  node: { component: CodeLeaf },
  shortcuts: { toggle: { keys: 'mod+e' } },
});
```

## Ownership

| Surface | Owner | What It Does |
|---------|-------|--------------|
| `BaseCodePlugin` | `@platejs/basic-nodes` | Headless inline code mark, HTML parser, render tag, selection rule, and `toggle` transform. |
| `CodePlugin` | `@platejs/basic-nodes/react` | React wrapper for the headless code mark. |
| `CodeRules.markdown` | `@platejs/basic-nodes` | Optional backtick input rule. |
| `CodeLeaf` | Registry UI | Styled inline code leaf using `PlateLeaf`. |
| `CodeLeafStatic` | Registry UI | Static rendering version using `SlateLeaf`. |
| `BasicMarksKit` | Registry | Adds `CodePlugin`, `CodeLeaf`, `CodeRules.markdown()`, and `mod+e`. |
| `MarkToolbarButton` | Registry UI | Reads active mark state and calls the mark toggle hook. |

The package owns inline code semantics. The registry owns visual styling and toolbar placement.

## Behavior

| Behavior | Source |
|----------|--------|
| Mark key | `KEYS.code` |
| Leaf behavior | `node.isLeaf: true` |
| Toggle transform | `editor.tf.code.toggle()` calls `editor.tf.toggleMark(type)`. |
| Selection affinity | `hard` |
| HTML tags | `code` |
| HTML styles | `font-family: Consolas` |
| HTML guard | Skips code inside `pre` and paragraph-level Consolas blocks. |
| Render output | `code` |
| Kit shortcut | `mod+e` |

## API Reference

| API | Package | Use |
|-----|---------|-----|
| `BaseCodePlugin` | `@platejs/basic-nodes` | Headless inline code plugin. |
| `CodePlugin` | `@platejs/basic-nodes/react` | React inline code plugin. |
| `CodeRules.markdown()` | `@platejs/basic-nodes` | Creates the backtick mark input rule. |
| `tf.code.toggle()` | `@platejs/basic-nodes` | Toggles the inline code mark at the selection. |
| `CodeLeaf` | Registry UI | Styled client inline code leaf. |
| `CodeLeafStatic` | Registry UI | Styled static inline code leaf. |



# Highlight

Source: https://platejs.org/docs/highlight

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Highlight
description: Add marked inline text.
docs:
  - route: /docs/basic-marks
    title: Basic Marks
  - route: /docs/components/highlight-node
    title: Highlight Leaf
  - route: /docs/components/mark-toolbar-button
    title: Mark Toolbar Button
  - route: /docs/examples/find-replace
    title: Find Replace Demo
---

Highlight applies the `highlight` leaf mark to selected text. It is the authoring mark; [Find Replace](/docs/examples/find-replace) uses a separate search highlight leaf for transient search results.

[basic-marks-demo registry content](https://platejs.org/r/basic-marks-demo)

<PackageInfo>

## Features

- `KEYS.highlight` leaf mark.
- Directional selection affinity.
- HTML deserialization from `mark`.
- `<mark>` rendering by default.
- Registry `HighlightLeaf` for styled marked text.
- Optional input rules through `HighlightRules`.

</PackageInfo>

## Kit Usage

<Steps>

### Add Basic Marks

`BasicMarksKit` includes `HighlightPlugin`, `HighlightLeaf`, `==` and `≡` input rules, and a `mod+shift+h` shortcut.

[basic-marks-kit registry content](https://platejs.org/r/basic-marks-kit)

```tsx
import { createPlateEditor } from 'platejs/react';

import { BasicMarksKit } from '@/components/editor/plugins/basic-marks-kit';

export const editor = createPlateEditor({
  plugins: [...BasicMarksKit],
});
```

### Add A Toolbar Button

Use `MarkToolbarButton` with `KEYS.highlight`.

```tsx
import { HighlighterIcon } from 'lucide-react';
import { KEYS } from 'platejs';

import { MarkToolbarButton } from '@/components/ui/mark-toolbar-button';

export function HighlightToolbarButton() {
  return (
    <MarkToolbarButton nodeType={KEYS.highlight} tooltip="Highlight">
      <HighlighterIcon />
    </MarkToolbarButton>
  );
}
```

</Steps>

## Manual Usage

Install the mark package.

```bash
npm install @platejs/basic-nodes
```

Add `HighlightPlugin` directly when you want the default `<mark>` render.

```tsx
import { HighlightPlugin } from '@platejs/basic-nodes/react';
import { createPlateEditor } from 'platejs/react';

export const editor = createPlateEditor({
  plugins: [HighlightPlugin],
});
```

Configure the registry leaf, input rules, and shortcut when you want the same behavior as the kit.

```tsx
import { HighlightRules } from '@platejs/basic-nodes';
import { HighlightPlugin } from '@platejs/basic-nodes/react';

import { HighlightLeaf } from '@/components/ui/highlight-node';

export const highlightPlugin = HighlightPlugin.configure({
  inputRules: [
    HighlightRules.markdown({ variant: '==' }),
    HighlightRules.markdown({ variant: '≡' }),
  ],
  node: { component: HighlightLeaf },
  shortcuts: { toggle: { keys: 'mod+shift+h' } },
});
```

## Ownership

| Surface | Owner | What It Does |
|---------|-------|--------------|
| `BaseHighlightPlugin` | `@platejs/basic-nodes` | Headless highlight mark, HTML parser, render tag, selection rule, and `toggle` transform. |
| `HighlightPlugin` | `@platejs/basic-nodes/react` | React wrapper for the headless highlight mark. |
| `HighlightRules.markdown` | `@platejs/basic-nodes` | Optional mark input rule factory. |
| `HighlightLeaf` | Registry UI | Styled client highlight leaf using `PlateLeaf`. |
| `HighlightLeafStatic` | Registry UI | Static rendering version using `SlateLeaf`. |
| `BasicMarksKit` | Registry | Adds `HighlightPlugin`, `HighlightLeaf`, two input-rule variants, and `mod+shift+h`. |
| `MarkToolbarButton` | Registry UI | Reads active mark state and calls the mark toggle hook. |

The package owns the mark. The registry owns highlight color and toolbar placement.

## Behavior

| Behavior | Source |
|----------|--------|
| Mark key | `KEYS.highlight` |
| Leaf behavior | `node.isLeaf: true` |
| Toggle transform | `editor.tf.highlight.toggle()` calls `editor.tf.toggleMark(type)`. |
| Selection affinity | `directional` |
| HTML tags | `mark` |
| Render output | `mark` |
| Kit input rules | `==` and `≡` variants |
| Kit shortcut | `mod+shift+h` |

## API Reference

| API | Package | Use |
|-----|---------|-----|
| `BaseHighlightPlugin` | `@platejs/basic-nodes` | Headless highlight plugin. |
| `HighlightPlugin` | `@platejs/basic-nodes/react` | React highlight plugin. |
| `HighlightRules.markdown(options)` | `@platejs/basic-nodes` | Creates a highlight mark input rule. |
| `tf.highlight.toggle()` | `@platejs/basic-nodes` | Toggles the highlight mark at the selection. |
| `HighlightLeaf` | Registry UI | Styled client highlight leaf. |
| `HighlightLeafStatic` | Registry UI | Styled static highlight leaf. |


# Italic

Source: https://platejs.org/docs/italic

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Italic
description: Add emphasized inline text.
docs:
  - route: /docs/basic-marks
    title: Basic Marks
  - route: /docs/components/mark-toolbar-button
    title: Mark Toolbar Button
  - route: /docs/plugin-shortcuts
    title: Plugin Shortcuts
---

Italic applies the `italic` leaf mark to selected text. `ItalicPlugin` owns the mark key, shortcut, HTML parsing, render tag, and toggle transform.

[basic-marks-demo registry content](https://platejs.org/r/basic-marks-demo)

<PackageInfo>

## Features

- `KEYS.italic` leaf mark.
- Default `⌘I` / `Ctrl+I` shortcut.
- HTML deserialization from `em`, `i`, and italic font style.
- `<em>` rendering by default.
- Optional Markdown-style input rules through `ItalicRules`.
- Toolbar support through `MarkToolbarButton`.

</PackageInfo>

## Kit Usage

<Steps>

### Add Basic Marks

`BasicMarksKit` includes `ItalicPlugin`, `*` and `_` Markdown-style input rules, and the standard toolbar buttons that use `KEYS.italic`.

[basic-marks-kit registry content](https://platejs.org/r/basic-marks-kit)

```tsx
import { createPlateEditor } from 'platejs/react';

import { BasicMarksKit } from '@/components/editor/plugins/basic-marks-kit';

export const editor = createPlateEditor({
  plugins: [...BasicMarksKit],
});
```

### Add A Toolbar Button

Use `MarkToolbarButton` with `KEYS.italic`.

```tsx
import { ItalicIcon } from 'lucide-react';
import { KEYS } from 'platejs';

import { MarkToolbarButton } from '@/components/ui/mark-toolbar-button';

export function ItalicToolbarButton() {
  return (
    <MarkToolbarButton nodeType={KEYS.italic} tooltip="Italic (⌘+I)">
      <ItalicIcon />
    </MarkToolbarButton>
  );
}
```

</Steps>

## Manual Usage

Install the mark package.

```bash
npm install @platejs/basic-nodes
```

Add `ItalicPlugin` directly when you do not want the whole kit.

```tsx
import { ItalicPlugin } from '@platejs/basic-nodes/react';
import { createPlateEditor } from 'platejs/react';

export const editor = createPlateEditor({
  plugins: [ItalicPlugin],
});
```

Register Markdown-style input rules when users should type italic delimiters.

```tsx
import { ItalicRules } from '@platejs/basic-nodes';
import { ItalicPlugin } from '@platejs/basic-nodes/react';

export const italicPlugin = ItalicPlugin.configure({
  inputRules: [
    ItalicRules.markdown({ variant: '*' }),
    ItalicRules.markdown({ variant: '_' }),
  ],
});
```

## Ownership

| Surface | Owner | What It Does |
|---------|-------|--------------|
| `BaseItalicPlugin` | `@platejs/basic-nodes` | Headless italic mark, HTML parser, render tag, and `toggle` transform. |
| `ItalicPlugin` | `@platejs/basic-nodes/react` | React wrapper with default `mod+i` shortcut. |
| `ItalicRules.markdown` | `@platejs/basic-nodes` | Optional mark input rule factory. |
| `BasicMarksKit` | Registry | Adds `ItalicPlugin` with `*` and `_` Markdown-style input rules. |
| `MarkToolbarButton` | Registry UI | Reads active mark state and calls the mark toggle hook. |

The package owns the mark. The registry owns toolbar placement and icon choice.

## Behavior

| Behavior | Source |
|----------|--------|
| Mark key | `KEYS.italic` |
| Leaf behavior | `node.isLeaf: true` |
| Toggle transform | `editor.tf.italic.toggle()` calls `editor.tf.toggleMark(type)`. |
| Shortcut | `ItalicPlugin` registers `mod+i`. |
| HTML tags | `em`, `i` |
| HTML styles | `font-style: italic` |
| HTML guard | Ignores descendants where `fontStyle` is `normal`. |
| Render output | `em` |

## API Reference

| API | Package | Use |
|-----|---------|-----|
| `BaseItalicPlugin` | `@platejs/basic-nodes` | Headless italic plugin. |
| `ItalicPlugin` | `@platejs/basic-nodes/react` | React italic plugin with shortcut defaults. |
| `ItalicRules.markdown(options)` | `@platejs/basic-nodes` | Creates an italic mark input rule. |
| `tf.italic.toggle()` | `@platejs/basic-nodes` | Toggles the italic mark at the selection. |


# Keyboard Input

Source: https://platejs.org/docs/kbd

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Keyboard Input
description: Style keyboard shortcuts and key names.
docs:
  - route: /docs/basic-marks
    title: Basic Marks
  - route: /docs/components/kbd-node
    title: Keyboard Input Leaf
  - route: /docs/components/more-toolbar-button
    title: More Toolbar Button
---

Keyboard Input applies the `kbd` leaf mark to selected text. Use it for shortcuts, key names, and command hints that should render as `<kbd>`.

[basic-marks-demo registry content](https://platejs.org/r/basic-marks-demo)

<PackageInfo>

## Features

- `KEYS.kbd` leaf mark.
- Hard selection affinity.
- HTML deserialization from `kbd`.
- `<kbd>` rendering by default.
- Registry `KbdLeaf` for styled keyboard input.
- Static rendering support through `KbdLeafStatic`.

</PackageInfo>

## Kit Usage

<Steps>

### Add Basic Marks

`BasicMarksKit` includes `KbdPlugin.withComponent(KbdLeaf)`. It does not add a shortcut or input rule for keyboard input.

[basic-marks-kit registry content](https://platejs.org/r/basic-marks-kit)

```tsx
import { createPlateEditor } from 'platejs/react';

import { BasicMarksKit } from '@/components/editor/plugins/basic-marks-kit';

export const editor = createPlateEditor({
  plugins: [...BasicMarksKit],
});
```

### Add the Leaf

`KbdLeaf` provides the registry styling for the `<kbd>` element.

[kbd-node registry content](https://platejs.org/r/kbd-node)

### Add a Toolbar Control

The registry `MoreToolbarButton` toggles keyboard input from the More menu.

```tsx
import { MoreToolbarButton } from '@/components/ui/more-toolbar-button';

export function FormattingMoreMenu() {
  return <MoreToolbarButton />;
}
```

</Steps>

## Manual Usage

Install the mark package.

```bash
npm install @platejs/basic-nodes
```

Add `KbdPlugin` directly when you want the default `<kbd>` render.

```tsx
import { KbdPlugin } from '@platejs/basic-nodes/react';
import { createPlateEditor } from 'platejs/react';

export const editor = createPlateEditor({
  plugins: [KbdPlugin],
});
```

Attach the registry leaf when you want the same visual treatment as the kit.

```tsx
import { KbdPlugin } from '@platejs/basic-nodes/react';

import { KbdLeaf } from '@/components/ui/kbd-node';

export const kbdPlugin = KbdPlugin.withComponent(KbdLeaf);
```

## Ownership

| Surface | Owner | What It Does |
|---------|-------|--------------|
| `BaseKbdPlugin` | `@platejs/basic-nodes` | Headless keyboard-input mark, HTML parser, render tag, selection rule, and `toggle` transform. |
| `KbdPlugin` | `@platejs/basic-nodes/react` | React wrapper for the headless keyboard-input mark. |
| `KbdLeaf` | Registry UI | Styled client `<kbd>` leaf using `PlateLeaf`. |
| `KbdLeafStatic` | Registry UI | Static rendering version using `SlateLeaf`. |
| `BasicMarksKit` | Registry | Adds `KbdPlugin.withComponent(KbdLeaf)`. |
| `MoreToolbarButton` | Registry UI | Calls `editor.tf.toggleMark(KEYS.kbd)` from the More menu. |

The package owns the mark. The registry owns keycap styling and toolbar placement.

## Behavior

| Behavior | Source |
|----------|--------|
| Mark key | `KEYS.kbd` |
| Leaf behavior | `node.isLeaf: true` |
| Toggle transform | `editor.tf.kbd.toggle()` calls `editor.tf.toggleMark(type)`. |
| Selection affinity | `hard` |
| HTML tags | `kbd` |
| Render output | `kbd` |
| Kit component | `KbdLeaf` |
| Registry toolbar | `MoreToolbarButton` toggles `KEYS.kbd`. |

## API Reference

| API | Package | Use |
|-----|---------|-----|
| `BaseKbdPlugin` | `@platejs/basic-nodes` | Headless keyboard-input plugin. |
| `KbdPlugin` | `@platejs/basic-nodes/react` | React keyboard-input plugin. |
| `tf.kbd.toggle()` | `@platejs/basic-nodes` | Toggles the keyboard-input mark at the selection. |
| `KbdLeaf` | Registry UI | Styled client keyboard-input leaf. |
| `KbdLeafStatic` | Registry UI | Styled static keyboard-input leaf. |


# Strikethrough

Source: https://platejs.org/docs/strikethrough

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Strikethrough
description: Strike through inline text.
docs:
  - route: /docs/basic-marks
    title: Basic Marks
  - route: /docs/components/mark-toolbar-button
    title: Mark Toolbar Button
  - route: /docs/plugin-shortcuts
    title: Plugin Shortcuts
---

Strikethrough applies the `strikethrough` leaf mark to selected text. The package owns the mark semantics; `BasicMarksKit` adds the Markdown-style input rule and shortcut.

[basic-marks-demo registry content](https://platejs.org/r/basic-marks-demo)

<PackageInfo>

## Features

- `KEYS.strikethrough` leaf mark.
- Directional selection affinity.
- HTML deserialization from `s`, `del`, `strike`, and line-through text decoration.
- `<s>` rendering by default.
- Optional Markdown-style input rule through `StrikethroughRules`.
- Toolbar support through `MarkToolbarButton`.

</PackageInfo>

## Kit Usage

<Steps>

### Add Basic Marks

`BasicMarksKit` includes `StrikethroughPlugin`, `~~` input rules, and a `mod+shift+x` shortcut.

[basic-marks-kit registry content](https://platejs.org/r/basic-marks-kit)

```tsx
import { createPlateEditor } from 'platejs/react';

import { BasicMarksKit } from '@/components/editor/plugins/basic-marks-kit';

export const editor = createPlateEditor({
  plugins: [...BasicMarksKit],
});
```

### Add A Toolbar Button

Use `MarkToolbarButton` with `KEYS.strikethrough`.

```tsx
import { StrikethroughIcon } from 'lucide-react';
import { KEYS } from 'platejs';

import { MarkToolbarButton } from '@/components/ui/mark-toolbar-button';

export function StrikethroughToolbarButton() {
  return (
    <MarkToolbarButton
      nodeType={KEYS.strikethrough}
      tooltip="Strikethrough"
    >
      <StrikethroughIcon />
    </MarkToolbarButton>
  );
}
```

</Steps>

## Manual Usage

Install the mark package.

```bash
npm install @platejs/basic-nodes
```

Add `StrikethroughPlugin` directly when you want the default `<s>` render.

```tsx
import { StrikethroughPlugin } from '@platejs/basic-nodes/react';
import { createPlateEditor } from 'platejs/react';

export const editor = createPlateEditor({
  plugins: [StrikethroughPlugin],
});
```

Configure the input rule and shortcut when you want the same behavior as the kit.

```tsx
import { StrikethroughRules } from '@platejs/basic-nodes';
import { StrikethroughPlugin } from '@platejs/basic-nodes/react';

export const strikethroughPlugin = StrikethroughPlugin.configure({
  inputRules: [StrikethroughRules.markdown()],
  shortcuts: { toggle: { keys: 'mod+shift+x' } },
});
```

## Ownership

| Surface | Owner | What It Does |
|---------|-------|--------------|
| `BaseStrikethroughPlugin` | `@platejs/basic-nodes` | Headless strikethrough mark, HTML parser, render tag, selection rule, and `toggle` transform. |
| `StrikethroughPlugin` | `@platejs/basic-nodes/react` | React wrapper for the headless strikethrough mark. |
| `StrikethroughRules.markdown` | `@platejs/basic-nodes` | Optional `~~` mark input rule factory. |
| `BasicMarksKit` | Registry | Adds `StrikethroughPlugin`, the input rule, and `mod+shift+x`. |
| `MarkToolbarButton` | Registry UI | Reads active mark state and calls the mark toggle hook. |

The package owns the mark. The registry owns shortcut configuration and toolbar placement.

## Behavior

| Behavior | Source |
|----------|--------|
| Mark key | `KEYS.strikethrough` |
| Leaf behavior | `node.isLeaf: true` |
| Toggle transform | `editor.tf.strikethrough.toggle()` calls `editor.tf.toggleMark(type)`. |
| Selection affinity | `directional` |
| HTML tags | `s`, `del`, `strike` |
| HTML styles | `text-decoration: line-through` |
| HTML guard | Ignores descendants where `textDecoration` is `none`. |
| Render output | `s` |
| Kit input rule | `StrikethroughRules.markdown()` |
| Kit shortcut | `mod+shift+x` |

## API Reference

| API | Package | Use |
|-----|---------|-----|
| `BaseStrikethroughPlugin` | `@platejs/basic-nodes` | Headless strikethrough plugin. |
| `StrikethroughPlugin` | `@platejs/basic-nodes/react` | React strikethrough plugin. |
| `StrikethroughRules.markdown()` | `@platejs/basic-nodes` | Creates the `~~` mark input rule. |
| `tf.strikethrough.toggle()` | `@platejs/basic-nodes` | Toggles the strikethrough mark at the selection. |


# Subscript

Source: https://platejs.org/docs/subscript

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Subscript
description: Format inline text below the baseline.
docs:
  - route: /docs/basic-marks
    title: Basic Marks
  - route: /docs/superscript
    title: Superscript
  - route: /docs/components/more-toolbar-button
    title: More Toolbar Button
  - route: /docs/plugin-shortcuts
    title: Plugin Shortcuts
---

Subscript applies the `subscript` leaf mark to selected text. Its toggle transform removes `superscript`, so the same text cannot keep both vertical-position marks through the plugin API.

[basic-marks-demo registry content](https://platejs.org/r/basic-marks-demo)

<PackageInfo>

## Features

- `KEYS.sub` leaf mark.
- Directional selection affinity.
- HTML deserialization from `sub` and `vertical-align: sub`.
- `<sub>` rendering by default.
- Optional Markdown-style input rule through `SubscriptRules`.
- Mutual exclusion with `KEYS.sup`.

</PackageInfo>

## Kit Usage

<Steps>

### Add Basic Marks

`BasicMarksKit` includes `SubscriptPlugin`, the `~` input rule, and a `mod+comma` shortcut.

[basic-marks-kit registry content](https://platejs.org/r/basic-marks-kit)

```tsx
import { createPlateEditor } from 'platejs/react';

import { BasicMarksKit } from '@/components/editor/plugins/basic-marks-kit';

export const editor = createPlateEditor({
  plugins: [...BasicMarksKit],
});
```

### Add a Toolbar Control

The registry `MoreToolbarButton` toggles subscript from the More menu and removes superscript.

```tsx
import { MoreToolbarButton } from '@/components/ui/more-toolbar-button';

export function FormattingMoreMenu() {
  return <MoreToolbarButton />;
}
```

</Steps>

## Manual Usage

Install the mark package.

```bash
npm install @platejs/basic-nodes
```

Add `SubscriptPlugin` directly when you want the default `<sub>` render.

```tsx
import { SubscriptPlugin } from '@platejs/basic-nodes/react';
import { createPlateEditor } from 'platejs/react';

export const editor = createPlateEditor({
  plugins: [SubscriptPlugin],
});
```

Configure the input rule and shortcut when you want the same behavior as the kit.

```tsx
import { SubscriptRules } from '@platejs/basic-nodes';
import { SubscriptPlugin } from '@platejs/basic-nodes/react';

export const subscriptPlugin = SubscriptPlugin.configure({
  inputRules: [SubscriptRules.markdown()],
  shortcuts: { toggle: { keys: 'mod+comma' } },
});
```

## Ownership

| Surface | Owner | What It Does |
|---------|-------|--------------|
| `BaseSubscriptPlugin` | `@platejs/basic-nodes` | Headless subscript mark, HTML parser, render tag, selection rule, and `toggle` transform. |
| `SubscriptPlugin` | `@platejs/basic-nodes/react` | React wrapper for the headless subscript mark. |
| `SubscriptRules.markdown` | `@platejs/basic-nodes` | Optional `~` mark input rule factory. |
| `BasicMarksKit` | Registry | Adds `SubscriptPlugin`, the input rule, and `mod+comma`. |
| `MoreToolbarButton` | Registry UI | Calls `editor.tf.toggleMark(KEYS.sub, { remove: KEYS.sup })`. |

The package owns subscript semantics. The registry owns shortcut configuration and toolbar placement.

## Behavior

| Behavior | Source |
|----------|--------|
| Mark key | `KEYS.sub` (`subscript`) |
| Leaf behavior | `node.isLeaf: true` |
| Toggle transform | `editor.tf.subscript.toggle()` calls `editor.tf.toggleMark(type, { remove: editor.getType(KEYS.sup) })`. |
| Selection affinity | `directional` |
| HTML tags | `sub` |
| HTML styles | `vertical-align: sub` |
| Render output | `sub` |
| Kit input rule | `SubscriptRules.markdown()` |
| Kit shortcut | `mod+comma` |

## API Reference

| API | Package | Use |
|-----|---------|-----|
| `BaseSubscriptPlugin` | `@platejs/basic-nodes` | Headless subscript plugin. |
| `SubscriptPlugin` | `@platejs/basic-nodes/react` | React subscript plugin. |
| `SubscriptRules.markdown()` | `@platejs/basic-nodes` | Creates the `~` mark input rule. |
| `tf.subscript.toggle()` | `@platejs/basic-nodes` | Toggles subscript and removes superscript. |


# Superscript

Source: https://platejs.org/docs/superscript

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Superscript
description: Format inline text above the baseline.
docs:
  - route: /docs/basic-marks
    title: Basic Marks
  - route: /docs/subscript
    title: Subscript
  - route: /docs/components/more-toolbar-button
    title: More Toolbar Button
  - route: /docs/plugin-shortcuts
    title: Plugin Shortcuts
---

Superscript applies the `superscript` leaf mark to selected text. Its toggle transform removes `subscript`, so the same text cannot keep both vertical-position marks through the plugin API.

[basic-marks-demo registry content](https://platejs.org/r/basic-marks-demo)

<PackageInfo>

## Features

- `KEYS.sup` leaf mark.
- Directional selection affinity.
- HTML deserialization from `sup` and `vertical-align: super`.
- `<sup>` rendering by default.
- Optional Markdown-style input rule through `SuperscriptRules`.
- Mutual exclusion with `KEYS.sub`.

</PackageInfo>

## Kit Usage

<Steps>

### Add Basic Marks

`BasicMarksKit` includes `SuperscriptPlugin`, the `^` input rule, and a `mod+period` shortcut.

[basic-marks-kit registry content](https://platejs.org/r/basic-marks-kit)

```tsx
import { createPlateEditor } from 'platejs/react';

import { BasicMarksKit } from '@/components/editor/plugins/basic-marks-kit';

export const editor = createPlateEditor({
  plugins: [...BasicMarksKit],
});
```

### Add a Toolbar Control

The registry `MoreToolbarButton` toggles superscript from the More menu and removes subscript.

```tsx
import { MoreToolbarButton } from '@/components/ui/more-toolbar-button';

export function FormattingMoreMenu() {
  return <MoreToolbarButton />;
}
```

</Steps>

## Manual Usage

Install the mark package.

```bash
npm install @platejs/basic-nodes
```

Add `SuperscriptPlugin` directly when you want the default `<sup>` render.

```tsx
import { SuperscriptPlugin } from '@platejs/basic-nodes/react';
import { createPlateEditor } from 'platejs/react';

export const editor = createPlateEditor({
  plugins: [SuperscriptPlugin],
});
```

Configure the input rule and shortcut when you want the same behavior as the kit.

```tsx
import { SuperscriptRules } from '@platejs/basic-nodes';
import { SuperscriptPlugin } from '@platejs/basic-nodes/react';

export const superscriptPlugin = SuperscriptPlugin.configure({
  inputRules: [SuperscriptRules.markdown()],
  shortcuts: { toggle: { keys: 'mod+period' } },
});
```

## Ownership

| Surface | Owner | What It Does |
|---------|-------|--------------|
| `BaseSuperscriptPlugin` | `@platejs/basic-nodes` | Headless superscript mark, HTML parser, render tag, selection rule, and `toggle` transform. |
| `SuperscriptPlugin` | `@platejs/basic-nodes/react` | React wrapper for the headless superscript mark. |
| `SuperscriptRules.markdown` | `@platejs/basic-nodes` | Optional `^` mark input rule factory. |
| `BasicMarksKit` | Registry | Adds `SuperscriptPlugin`, the input rule, and `mod+period`. |
| `MoreToolbarButton` | Registry UI | Calls `editor.tf.toggleMark(KEYS.sup, { remove: KEYS.sub })`. |

The package owns superscript semantics. The registry owns shortcut configuration and toolbar placement.

## Behavior

| Behavior | Source |
|----------|--------|
| Mark key | `KEYS.sup` (`superscript`) |
| Leaf behavior | `node.isLeaf: true` |
| Toggle transform | `editor.tf.superscript.toggle()` calls `editor.tf.toggleMark(type, { remove: editor.getType(KEYS.sub) })`. |
| Selection affinity | `directional` |
| HTML tags | `sup` |
| HTML styles | `vertical-align: super` |
| Render output | `sup` |
| Kit input rule | `SuperscriptRules.markdown()` |
| Kit shortcut | `mod+period` |

## API Reference

| API | Package | Use |
|-----|---------|-----|
| `BaseSuperscriptPlugin` | `@platejs/basic-nodes` | Headless superscript plugin. |
| `SuperscriptPlugin` | `@platejs/basic-nodes/react` | React superscript plugin. |
| `SuperscriptRules.markdown()` | `@platejs/basic-nodes` | Creates the `^` mark input rule. |
| `tf.superscript.toggle()` | `@platejs/basic-nodes` | Toggles superscript and removes subscript. |


# Underline

Source: https://platejs.org/docs/underline

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Underline
description: Add underlined inline text.
docs:
  - route: /docs/basic-marks
    title: Basic Marks
  - route: /docs/components/mark-toolbar-button
    title: Mark Toolbar Button
  - route: /docs/plugin-shortcuts
    title: Plugin Shortcuts
---

Underline applies the `underline` leaf mark to selected text. `UnderlinePlugin` owns the mark key, shortcut, HTML parsing, render tag, and toggle transform.

[basic-marks-demo registry content](https://platejs.org/r/basic-marks-demo)

<PackageInfo>

## Features

- `KEYS.underline` leaf mark.
- Default `⌘U` / `Ctrl+U` shortcut.
- HTML deserialization from `u` and underline text decoration.
- `<u>` rendering by default.
- Optional Markdown-style input rule through `UnderlineRules`.
- Toolbar support through `MarkToolbarButton`.

</PackageInfo>

## Kit Usage

<Steps>

### Add Basic Marks

`BasicMarksKit` includes `UnderlinePlugin`, the underscore input rule, and the standard toolbar buttons that use `KEYS.underline`.

[basic-marks-kit registry content](https://platejs.org/r/basic-marks-kit)

```tsx
import { createPlateEditor } from 'platejs/react';

import { BasicMarksKit } from '@/components/editor/plugins/basic-marks-kit';

export const editor = createPlateEditor({
  plugins: [...BasicMarksKit],
});
```

### Add A Toolbar Button

Use `MarkToolbarButton` with `KEYS.underline`.

```tsx
import { UnderlineIcon } from 'lucide-react';
import { KEYS } from 'platejs';

import { MarkToolbarButton } from '@/components/ui/mark-toolbar-button';

export function UnderlineToolbarButton() {
  return (
    <MarkToolbarButton nodeType={KEYS.underline} tooltip="Underline (⌘+U)">
      <UnderlineIcon />
    </MarkToolbarButton>
  );
}
```

</Steps>

## Manual Usage

Install the mark package.

```bash
npm install @platejs/basic-nodes
```

Add `UnderlinePlugin` directly when you do not want the whole kit.

```tsx
import { UnderlinePlugin } from '@platejs/basic-nodes/react';
import { createPlateEditor } from 'platejs/react';

export const editor = createPlateEditor({
  plugins: [UnderlinePlugin],
});
```

Register the Markdown-style input rule when users should type underline delimiters.

```tsx
import { UnderlineRules } from '@platejs/basic-nodes';
import { UnderlinePlugin } from '@platejs/basic-nodes/react';

export const underlinePlugin = UnderlinePlugin.configure({
  inputRules: [UnderlineRules.markdown()],
});
```

## Ownership

| Surface | Owner | What It Does |
|---------|-------|--------------|
| `BaseUnderlinePlugin` | `@platejs/basic-nodes` | Headless underline mark, HTML parser, render tag, and `toggle` transform. |
| `UnderlinePlugin` | `@platejs/basic-nodes/react` | React wrapper with default `mod+u` shortcut. |
| `UnderlineRules.markdown` | `@platejs/basic-nodes` | Optional mark input rule factory. |
| `BasicMarksKit` | Registry | Adds `UnderlinePlugin` with the underscore input rule. |
| `MarkToolbarButton` | Registry UI | Reads active mark state and calls the mark toggle hook. |

The package owns the mark. The registry owns toolbar placement and icon choice.

## Behavior

| Behavior | Source |
|----------|--------|
| Mark key | `KEYS.underline` |
| Leaf behavior | `node.isLeaf: true` |
| Toggle transform | `editor.tf.underline.toggle()` calls `editor.tf.toggleMark(type)`. |
| Shortcut | `UnderlinePlugin` registers `mod+u`. |
| HTML tags | `u` |
| HTML styles | `text-decoration: underline` |
| HTML guard | Ignores descendants where `textDecoration` is `none`. |
| Render output | `u` |

## API Reference

| API | Package | Use |
|-----|---------|-----|
| `BaseUnderlinePlugin` | `@platejs/basic-nodes` | Headless underline plugin. |
| `UnderlinePlugin` | `@platejs/basic-nodes/react` | React underline plugin with shortcut defaults. |
| `UnderlineRules.markdown()` | `@platejs/basic-nodes` | Creates the underline mark input rule. |
| `tf.underline.toggle()` | `@platejs/basic-nodes` | Toggles the underline mark at the selection. |


# Serializing CSV

Source: https://platejs.org/docs/csv

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Serializing CSV
---

[csv-demo registry content](https://platejs.org/r/csv-demo)

<PackageInfo>

## Features

- Convert CSV content to Plate table format
- Configurable error tolerance for parsing malformed CSV data

<Callout className="my-4" type="note">
  Converting a Plate value to CSV is not yet supported.
</Callout>

</PackageInfo>

## Manual Usage

<Steps>

### Installation

```bash
npm install @platejs/csv
```

### Add Plugin

```tsx
import { CsvPlugin } from '@platejs/csv';
import { createPlateEditor } from 'platejs/react';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    CsvPlugin,
  ],
});
```

### Configure Plugin

```tsx
import { CsvPlugin } from '@platejs/csv';
import { createPlateEditor } from 'platejs/react';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    CsvPlugin.configure({
      options: {
        errorTolerance: 0.1,
        parseOptions: {
          header: true,
          skipEmptyLines: true,
          delimiter: ',',
        },
      },
    }),
  ],
});
```

- `options.errorTolerance`: Percentage of rows that can contain errors (default: `0.25` for 25%)
- `options.parseOptions`: Configuration passed to PapaParse library for CSV parsing
- `options.parseOptions.header`: Treat first row as headers (default: `true`)

</Steps>

## Usage

### CSV to Plate

Use the API method to deserialize CSV data:

```tsx
// Deserialize CSV string to Plate format
const csvData = `Name,Age,City
John,30,New York
Jane,25,Boston`;

const nodes = editor.api.csv.deserialize({ data: csvData });
```

## Plugins

### CsvPlugin

Plugin for CSV deserialization functionality.

<API name="CsvPlugin">
<APIOptions>
  <APIItem name="errorTolerance" type="number" optional>
    The tolerance for errors in the CSV data, represented as a percentage in decimal form. This value is calculated as the ratio of errors to the total number of rows.

    - **Default:** `0.25` (This indicates that up to 25% of the rows can contain errors.)
  </APIItem>
  <APIItem name="parseOptions" type="ParseConfig" optional>
    Options to be passed to the PapaParse library for parsing CSV data.

    - **Default:** `{ header: true }` (Indicating that the first row of the CSV data should be treated as a header.)
    - See [PapaParse documentation](https://www.papaparse.com/docs#config) for more details about these options.
  </APIItem>
</APIOptions>
</API>

## API

### api.csv.deserialize

Takes a CSV (Comma Separated Values) string and converts it into a Plate compatible format. This function uses the `papaparse` library to parse the CSV data.

<API name="deserialize">
<APIParameters>
  <APIItem name="data" type="string">
    The CSV data string to be deserialized.
  </APIItem>
  <APIItem name="errorTolerance" type="number" optional>
    Percentage in decimal form, from 0 to ∞, 0 for no errors allowed. Percentage is based on number of errors compared to number of rows.
    - **Default:** `0.25`
  </APIItem>
  <APIItem name="parseOptions" type="ParseConfig">
    Options to be passed to the PapaParse library for parsing CSV data.
    - **Default:** `{ header: true }`
    - See [PapaParse documentation](https://www.papaparse.com/docs#config)
  </APIItem>
</APIParameters>

<APIReturns type="Descendant[]">
  Array of `Descendant` nodes representing the CSV data in Plate format. Returns `undefined` if parsing fails.
</APIReturns>
</API>

Creates a table representation of the CSV data:
- Headers (if present) become the first row
- Each CSV row becomes a table row
- Uses plugins: `TablePlugin`, `TableCellHeaderPlugin`, `TableRowPlugin`, and `TableCellPlugin`


# DOCX Import/Export

Source: https://platejs.org/docs/docx-io

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: DOCX Import/Export
description: Import DOCX files and export Plate content to Word documents.
---

<PackageInfo>

## Features

- **Import DOCX files** to Plate format with full content and comment extraction
- **Export to DOCX** with support for all common formatting, tables, lists, and images
- Support for headers, footers, page orientation, and margins
- Configurable CSS styles and fonts for export

</PackageInfo>

<Callout type="info">
  Looking for paste from Word support? See [DOCX Paste](/docs/docx).
</Callout>

## Installation

```bash
npm install @platejs/docx-io
```

## Import DOCX

<Steps>

### Import DOCX File

Use `importDocx` to convert a DOCX file to Plate nodes:

```tsx
import { importDocx } from '@platejs/docx-io';

const handleFileUpload = async (file: File) => {
  const arrayBuffer = await file.arrayBuffer();
  const result = await importDocx(editor, arrayBuffer);

  // Insert nodes into editor
  editor.tf.insertNodes(result.nodes);

  // Handle comments if needed
  for (const comment of result.comments) {
    console.log(`Comment ${comment.id}: ${comment.text}`);
  }

  // Check for conversion warnings
  if (result.warnings.length > 0) {
    console.warn('Conversion warnings:', result.warnings);
  }
};
```

</Steps>

## Export DOCX

<Steps>

### Basic Export

Use `exportToDocx` to convert Plate content to a DOCX file:

```tsx
import { exportToDocx, downloadDocx } from '@platejs/docx-io';

const handleExport = async () => {
  const blob = await exportToDocx(editor.children, {
    orientation: 'portrait',
    margins: { top: 1440, bottom: 1440, left: 1440, right: 1440 },
    fontFamily: 'Calibri',
  });

  downloadDocx(blob, 'document.docx');
};
```

Or use the combined function:

```tsx
import { exportEditorToDocx } from '@platejs/docx-io';

await exportEditorToDocx(editor.children, 'document', {
  orientation: 'portrait',
});
```

### With Editor Plugins

For accurate serialization, provide your editor plugins:

```tsx
import { exportToDocx } from '@platejs/docx-io';
import { BaseEditorKit } from '@/components/editor/editor-base-kit';
import { DocxExportKit } from '@/components/editor/plugins/docx-export-kit';

const blob = await exportToDocx(editor.children, {
  editorPlugins: [...BaseEditorKit, ...DocxExportKit],
});
```

### Custom Styles

Customize the export styles:

```tsx
import { exportToDocx, DOCX_EXPORT_STYLES } from '@platejs/docx-io';

const blob = await exportToDocx(editor.children, {
  customStyles: `
    .custom-highlight { background-color: #ffeb3b; }
    h1 { color: #1a1a1a; }
  `,
  fontFamily: 'Times New Roman',
});
```

### Using DocxExportPlugin

For plugin-based API access:

```tsx
import { DocxExportPlugin } from '@platejs/docx-io';
import { createPlateEditor } from 'platejs/react';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    DocxExportPlugin.configure({
      options: {
        editorPlugins: myPlugins,
        editorStaticComponent: MyEditorStatic,
      },
    }),
  ],
});

// Export using plugin API
const blob = await editor.api.docxExport.exportToBlob({
  orientation: 'landscape',
});

editor.api.docxExport.download(blob, 'document');

// Or use transform for export + download
await editor.tf.docxExport.exportAndDownload('document', {
  orientation: 'portrait',
});
```

</Steps>

## DOCX Export Kit

The `DocxExportKit` provides DOCX-optimized static components for elements that require special handling:

[docx-export-kit registry content](https://platejs.org/r/docx-export-kit)

Components included:
- **Code blocks**: Inline syntax highlighting with line breaks
- **Columns**: Table layout instead of flexbox
- **Equations**: Inline font styling (KaTeX doesn't work in DOCX)
- **Callouts**: Table layout for icon + content
- **TOC**: Anchor links with proper paragraph breaks

## Plugins

### DocxExportPlugin

Plugin providing DOCX export functionality with typed API methods.

<API name="DocxExportPlugin">
<APIOptions>
<APIItem name="editorPlugins" type="SlatePlugin[]" optional>
Plugins to use for HTML serialization. If not provided, uses the editor's current plugins.
</APIItem>
<APIItem name="editorStaticComponent" type="React.ComponentType<PlateStaticProps>" optional>
React component to use for static rendering.
</APIItem>
</APIOptions>
</API>

## API

### `importDocx`

Import a DOCX file and convert it to Plate nodes.

<API name="importDocx">
<APIParameters>
<APIItem name="editor" type="SlateEditor">
The Plate editor instance.
</APIItem>
<APIItem name="arrayBuffer" type="ArrayBuffer">
The DOCX file as ArrayBuffer.
</APIItem>
<APIItem name="options" type="ImportDocxOptions" optional>
Import options.
</APIItem>
</APIParameters>

<APIOptions type="ImportDocxOptions">
<APIItem name="rtf" type="string" optional>
RTF data for image extraction.
</APIItem>
</APIOptions>

<APIReturns type="Promise<ImportDocxResult>">
<APIItem name="nodes" type="TNode[]">
Deserialized editor nodes.
</APIItem>
<APIItem name="comments" type="DocxComment[]">
Comments extracted from the DOCX file.
</APIItem>
<APIItem name="warnings" type="string[]">
Warnings from mammoth conversion.
</APIItem>
</APIReturns>
</API>

### `exportToDocx`

Convert Plate content to a DOCX blob.

<API name="exportToDocx">
<APIParameters>
<APIItem name="value" type="Value">
The Plate editor value (array of nodes).
</APIItem>
<APIItem name="options" type="DocxExportOptions" optional>
Export options.
</APIItem>
</APIParameters>

<APIOptions type="DocxExportOptions">
<APIItem name="orientation" type="'portrait' | 'landscape'" optional>
Page orientation.

- **Default:** `'portrait'`
</APIItem>
<APIItem name="margins" type="DocxExportMargins" optional>
Page margins in twentieths of a point (1 inch = 1440).

- **Default:** `{ top: 1440, bottom: 1440, left: 1440, right: 1440, header: 720, footer: 720, gutter: 0 }`
</APIItem>
<APIItem name="fontFamily" type="string" optional>
Font family for the document body. Overrides default Calibri font.
</APIItem>
<APIItem name="customStyles" type="string" optional>
Additional CSS styles to include. Appended after default DOCX_EXPORT_STYLES.
</APIItem>
<APIItem name="title" type="string" optional>
Document title for metadata.
</APIItem>
<APIItem name="editorPlugins" type="SlatePlugin[]" optional>
Plugins for HTML serialization.
</APIItem>
<APIItem name="editorStaticComponent" type="React.ComponentType" optional>
Component for static rendering.
</APIItem>
</APIOptions>

<APIReturns type="Promise<Blob>">
A Blob containing the DOCX file.
</APIReturns>
</API>

### `downloadDocx`

Download a DOCX blob as a file.

<API name="downloadDocx">
<APIParameters>
<APIItem name="blob" type="Blob">
The DOCX blob to download.
</APIItem>
<APIItem name="filename" type="string">
The filename (with or without .docx extension).
</APIItem>
</APIParameters>
</API>

### `exportEditorToDocx`

Export and download editor content as a DOCX file in one call.

<API name="exportEditorToDocx">
<APIParameters>
<APIItem name="value" type="Value">
The Plate editor value.
</APIItem>
<APIItem name="filename" type="string">
The filename for download.
</APIItem>
<APIItem name="options" type="DocxExportOptions" optional>
Export options (same as `exportToDocx`).
</APIItem>
</APIParameters>
</API>

### api.docxExport.exportToBlob

Convert editor content to a DOCX blob using the plugin API.

<API name="api.docxExport.exportToBlob">
<APIOptions type="DocxExportOperationOptions">
<APIItem name="orientation" type="'portrait' | 'landscape'" optional>
Page orientation.
</APIItem>
<APIItem name="margins" type="DocxExportMargins" optional>
Page margins.
</APIItem>
<APIItem name="fontFamily" type="string" optional>
Font family.
</APIItem>
<APIItem name="customStyles" type="string" optional>
Additional CSS styles.
</APIItem>
<APIItem name="title" type="string" optional>
Document title.
</APIItem>
</APIOptions>

<APIReturns type="Promise<Blob>">
A Blob containing the DOCX file.
</APIReturns>
</API>

### api.docxExport.download

Download a DOCX blob as a file.

<API name="api.docxExport.download">
<APIParameters>
<APIItem name="blob" type="Blob">
The DOCX blob.
</APIItem>
<APIItem name="filename" type="string">
The filename.
</APIItem>
</APIParameters>
</API>

## Transforms

### tf.docxExport.exportAndDownload

Export and download editor content as a DOCX file.

<API name="tf.docxExport.exportAndDownload">
<APIParameters>
<APIItem name="filename" type="string">
The filename for download.
</APIItem>
<APIItem name="options" type="DocxExportOperationOptions" optional>
Export options.
</APIItem>
</APIParameters>
</API>

## Types

### DocxComment

```ts
type DocxComment = {
  id: string;
  text: string;
};
```

### DocxExportMargins

```ts
type DocxExportMargins = {
  top?: number;
  bottom?: number;
  left?: number;
  right?: number;
  header?: number;
  footer?: number;
  gutter?: number;
};
```

## Constants

### DOCX_EXPORT_STYLES

Default CSS styles optimized for Microsoft Word HTML rendering:

- Calibri font (Microsoft Office default)
- 11pt font size with 1.5 line height
- Heading hierarchy (24pt to 10pt)
- Table styles with borders
- Code block styling with Courier New
- Blockquote styling with left border

## Known Limitations

- **Mobile browsers**: Export may not work reliably on mobile browsers due to limitations with blob handling and downloads.
- **Complex layouts**: Some complex CSS layouts (flexbox, grid) are converted to table-based layouts for Word compatibility.
- **Custom fonts**: Only system fonts available in Word will render correctly.


# DOCX Paste

Source: https://platejs.org/docs/docx

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: DOCX Paste
description: Paste content from Microsoft Word with automatic formatting.
---

[docx-demo registry content](https://platejs.org/r/docx-demo)

<PackageInfo>

## Features

- Convert pasted DOCX content to Plate format
- Clean and normalize DOCX HTML content for Plate compatibility
- Support for list styles and nested indentation from Word documents

</PackageInfo>

<Callout type="info">
  Looking for DOCX file import/export? See [DOCX Import/Export](/docs/docx-io).
</Callout>

## Kit Usage

<Steps>

### Installation

The fastest way to add DOCX import functionality is with the `DocxKit`, which includes pre-configured `DocxPlugin` and `JuicePlugin` for handling DOCX content and CSS processing.

[docx-kit registry content](https://platejs.org/r/docx-kit)

### Add Kit

```tsx
import { createPlateEditor } from 'platejs/react';
import { DocxKit } from '@/components/editor/plugins/docx-kit';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    ...DocxKit,
  ],
});
```

</Steps>

## Manual Usage

<Steps>

### Installation

```bash
npm install @platejs/docx @platejs/juice
```

### Add Plugins

```tsx
import { DocxPlugin } from '@platejs/docx';
import { JuicePlugin } from '@platejs/juice';
import { createPlateEditor } from 'platejs/react';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    DocxPlugin,
    JuicePlugin,
  ],
});
```

### Configure Plugins

```tsx
import { DocxPlugin } from '@platejs/docx';
import { JuicePlugin } from '@platejs/juice';
import { createPlateEditor } from 'platejs/react';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    DocxPlugin, // Handles DOCX content transformation
    JuicePlugin, // Inlines CSS properties into style attributes
  ],
});
```

- `DocxPlugin`: Processes pasted DOCX content and converts it to Plate format
- `JuicePlugin`: Inlines CSS properties into the `style` attribute for better compatibility

</Steps>

## Usage

### DOCX to Plate

When users paste content from Microsoft Word, the DOCX plugin automatically:

1. Detects DOCX content in the clipboard
2. Cleans and normalizes the HTML structure
3. Preserves indentation and list formatting
4. Converts DOCX-specific elements to Plate format

The plugin works seamlessly with the paste functionality - no additional code is needed once installed.

## Plugins

### DocxPlugin

Plugin for processing DOCX content during paste operations.

### JuicePlugin

Plugin for inlining CSS properties into HTML elements. Converts external CSS styles to inline `style` attributes. This is essential for DOCX processing as it ensures styling information is preserved when content is pasted from Word documents.


# HTML

Source: https://platejs.org/docs/html

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: HTML
description: Convert Plate content to HTML and vice-versa.
toc: true
---

This guide covers converting Plate editor content to HTML (`serializeHtml`) and parsing HTML back into Plate's format (`editor.api.html.deserialize`).

[html-demo registry content](https://platejs.org/r/html-demo)

## Kit Usage

<Steps>

### Installation

The fastest way to enable HTML serialization is with the `BaseEditorKit`, which includes pre-configured base plugins that support HTML conversion for most common elements and marks.

[editor-base-kit registry content](https://platejs.org/r/editor-base-kit)

### Add Kit

```tsx
import { createSlateEditor } from 'platejs';
import { serializeHtml } from 'platejs/static';
import { BaseEditorKit } from '@/components/editor/editor-base-kit';

const editor = createSlateEditor({
  plugins: BaseEditorKit,
  value: [
    { type: 'h1', children: [{ text: 'Hello World' }] },
    { type: 'p', children: [{ text: 'This content will be serialized to HTML.' }] },
  ],
});

// Serialize to HTML
const html = await serializeHtml(editor);
```

### Example

See a complete server-side HTML generation example:

[slate-to-html registry content](https://platejs.org/r/slate-to-html)

</Steps>

## Plate to HTML

Convert Plate editor content (Plate nodes) into an HTML string. This is often done server-side.

[View Server-Side Example](/docs/examples/slate-to-html)

<Callout type="warning" title="Key Server-Side Constraint">
  When using `serializeHtml` or other Plate utilities in a server environment (Node.js, RSC), you **must not** import from `/react` subpaths of any `platejs*` package. Always use the base imports (e.g., `@platejs/basic-nodes` instead of `@platejs/basic-nodes/react`).

  This means you should use `createSlateEditor` from `platejs` for server-side editor instances, not `usePlateEditor` or `createPlateEditor` from `platejs/react`.
</Callout>

<Steps>

### Basic Usage

Provide a server-side editor instance and configure your Plate components during editor creation.

```tsx title="lib/generate-html.ts"
import { createSlateEditor } from 'platejs';
import { serializeHtml } from 'platejs/static'; // Static import
// Import base plugins (NOT from /react paths)
import { BaseHeadingPlugin } from '@platejs/basic-nodes';
// Import your STATIC components for rendering
import { ParagraphElementStatic } from '@/components/ui/paragraph-node-static';
import { HeadingElementStatic } from '@/components/ui/heading-node-static';
// For a styled static output, you might use a wrapper like EditorStatic
import { EditorStatic } from '@/components/ui/editor-static';

// Map plugin keys to their STATIC rendering components
const components = {
  p: ParagraphElementStatic, // 'p' is the default key for paragraphs
  h1: HeadingElementStatic,
  // ... add mappings for all your elements and marks
};

// Create a server-side editor instance with components
const editor = createSlateEditor({
  plugins: [
    BaseHeadingPlugin,   // Base plugin for headings
    // ... add all other base plugins relevant to your content
  ],
  components,
});

async function getMyHtml() {
  // Example: set some content on the server-side editor
  editor.children = [
    { type: 'h1', children: [{text: 'My Title'}] },
    { type: 'p', children: [{text: 'My content.'}] }
  ];

  const html = await serializeHtml(editor, {
    // Optional: Use a custom wrapper like EditorStatic for styling
    // editorComponent: EditorStatic,
    // props: { variant: 'none', className: 'p-4 m-4 border' },
  });

  return html;
}
```

### Styling Serialized HTML

`serializeHtml` returns only the HTML for the editor content itself. If you use styled components (like `EditorStatic` or custom static components with specific classes), you must ensure the necessary CSS is available in the final context where the HTML will be displayed.

This often means wrapping the serialized HTML in a full HTML document that includes your stylesheets:

```tsx title="lib/generate-full-html-document.ts"
// ... (previous setup from generate-html.ts)

async function getFullHtmlDocument() {
  const editorHtmlContent = await getMyHtml(); // From previous example

  const fullHtml = `<!DOCTYPE html>
  <html>
    <head>
      <meta charset="UTF-8">
      <meta name="viewport" content="width=device-width, initial-scale=1.0">
      <link rel="stylesheet" href="/path/to/your-global-styles.css" />
      <link rel="stylesheet" href="/path/to/tailwind-or-component-styles.css" />
      <title>Serialized Content</title>
    </head>
    <body>
      <div class="my-document-wrapper prose dark:prose-invert">
        ${editorHtmlContent}
      </div>
    </body>
  </html>`;
  return fullHtml;
}
```

<Callout type="info" title="Static Output Only">
  The serialization process converts Plate nodes to static HTML. Interactive features (React event handlers, client-side hooks) or components relying on browser APIs will not function in the serialized output.
</Callout>

### Using Static Components

For server-side serialization, you **must** use static versions of your components (no client-only code, no React hooks like `useEffect` or `useState`).

Refer to the [Static Rendering Guide](/docs/static) for detailed instructions on creating server-safe static components for your Plate elements and marks.

```tsx title="components/ui/paragraph-node-static.tsx"
import React from 'react';
import type { SlateElementProps } from 'platejs/static';

// Example static paragraph component
export function ParagraphElementStatic(props: SlateElementProps) {
  return (
    <SlateElement {...props} className={cn('m-0 px-0 py-1')}>
      {props.children}
    </SlateElement>
  );
}
```

</Steps>

---

## HTML to Plate

The HTML deserializer allows you to convert HTML content (strings or DOM elements) back into Plate format. This supports round-trip conversion, preserving structure, formatting, and attributes where corresponding plugin rules exist.

<Steps>

### Basic Usage

Use `editor.api.html.deserialize` within a client-side Plate editor context.

```tsx title="components/my-html-importer.tsx"
import { PlateEditor, usePlateEditor } from 'platejs/react'; // React-specific imports for client-side
// Import ALL Plate plugins needed to represent the HTML content
import { HeadingPlugin } from '@platejs/basic-nodes/react';
// ... and so on for bold, italic, tables, lists, etc.

function MyHtmlImporter({ htmlString }: { htmlString: string }) {
  const editor = usePlateEditor({
    plugins: [
      HeadingPlugin,     // For <h1>, <h2>, etc.
      // ... include all plugins corresponding to the HTML you expect to parse
    ],
  });

  const handleImport = () => {
    const slateValue = editor.api.html.deserialize({ element: htmlString });
    editor.tf.setValue(slateValue);
  };

  // ... render your editor and a button to trigger handleImport ...
  return <button onClick={handleImport}>Import HTML</button>;
}
```

<Callout type="warning" title="Client-Side Operation">
  HTML deserialization using `editor.api.html.deserialize` is typically a client-side operation as it interacts with a live Plate editor instance configured with React components and plugins.
</Callout>

### Plugin Deserialization Rules Overview

Each Plate plugin can define rules for how it interprets specific HTML tags, styles, and attributes during deserialization. Below is a summary of common HTML structures and the Plate plugins typically responsible for them.

| HTML Element / Style                                       | Plate Plugin (Typical)  | Notes                                                                    |
| :--------------------------------------------------------- | :---------------------- | :----------------------------------------------------------------------- |
| `<strong>`, `<b>`, `font-weight: 600,700,bold`          | [`BoldPlugin`](/docs/bold)            | Converts to `bold: true` mark.                                           |
| `<em>`, `<i>`, `font-style: italic`                      | [`ItalicPlugin`](/docs/italic)          | Converts to `italic: true` mark.                                         |
| `<u>`, `text-decoration: underline`                       | [`UnderlinePlugin`](/docs/underline)       | Converts to `underline: true` mark.                                      |
| `<s>`, `<del>`, `<strike>`, `text-decoration: line-through` | [`StrikethroughPlugin`](/docs/strikethrough)   | Converts to `strikethrough: true` mark.                                  |
| `<sub>`, `vertical-align: sub`                            | [`SubscriptPlugin`](/docs/subscript)       | Converts to `subscript: true` mark.                                      |
| `<sup>`, `vertical-align: super`                           | [`SuperscriptPlugin`](/docs/superscript)     | Converts to `superscript: true` mark.                                    |
| `<code>` (not in `<pre>`), `font-family: Consolas`         | [`CodePlugin`](/docs/code)            | Converts to `code: true` mark (inline code).                             |
| `<kbd>`                                                    | [`KbdPlugin`](/docs/kbd)             | Converts to `kbd: true` mark.                                            |
| `<p>`                                                      | [`ParagraphPlugin`](/docs/basic-blocks)       | Converts to paragraph element.                                           |
| `<h1>` - `<h6>`                                            | [`HeadingPlugin`](/docs/heading)         | Converts to corresponding heading elements (`h1` - `h6`).                |
| `<ul>`                                                     | [`ListPlugin` (classic)](/docs/list-classic)            | Converts to unordered list (`ul` type). Items become `li`.               |
| `<ol>`                                                     | [`ListPlugin` (classic)](/docs/list-classic)            | Converts to ordered list (`ol` type). Items become `li`.                 |
| `<li>` (within `<ul>` or `<ol>`)                           | [`ListPlugin` (classic)](/docs/list-classic)            | Converts to list item (`li` type), with `lic` (list item content) child. |
| `<li>` (with `aria-level` for indent)                      | [`ListPlugin`](/docs/list)      | Converts to paragraph with `indent` and `listStyleType` props.           |
| `<blockquote>`                                             | [`BlockquotePlugin`](/docs/blockquote)      | Converts to blockquote element.                                          |
| `<pre>` (often with `<code>` inside)                       | [`CodeBlockPlugin`](/docs/code-block)       | Converts to `code_block` element. Content split into `code_line`.        |
| `<hr>`                                                     | [`HorizontalRulePlugin`](/docs/horizontal-rule)  | Converts to horizontal rule element.                                     |
| `<a>`                                                      | [`LinkPlugin`](/docs/link)            | Converts to link element (`a` type) with `url` property.                 |
| `<img>`                                                    | [`ImagePlugin`](/docs/media)           | Converts to image element (`img` type) with `url` property.              |
| `<iframe>`                                                 | [`MediaEmbedPlugin`](/docs/media)      | Converts to media embed element, attempting to parse URL.                |
| `<table>`                                                  | [`TablePlugin`](/docs/table)           | Converts to `table` element.                                             |
| `<tr>`                                                     | [`TablePlugin`](/docs/table)           | Converts to `tr` (table row) element.                                    |
| `<td>`                                                     | [`TablePlugin`](/docs/table)           | Converts to `td` (table cell) element.                                   |
| `<th>`                                                     | [`TablePlugin`](/docs/table)           | Converts to `th` (table header cell) element.                            |
| `style="background-color: ..."`                          | [`FontColorPlugin`](/docs/font)    | Converts to `backgroundColor` mark. (Plugin name might seem inverse) |
| `style="color: ..."`                                     | [`FontColorPlugin`](/docs/font)       | Converts to `color` mark.                                                |
| `style="font-family: ..."`                               | [`FontFamilyPlugin`](/docs/font)      | Converts to `fontFamily` mark.                                           |
| `style="font-size: ..."`                                 | [`FontSizePlugin`](/docs/font)        | Converts to `fontSize` mark.                                             |
| `style="font-weight: ..."` (other than bold values)      | [`FontWeightPlugin`](/docs/font)      | Converts to `fontWeight` mark for non-standard bold values.              |
| `<mark>`                                                   | [`HighlightPlugin`](/docs/highlight)       | Converts to `highlight: true` mark.                                      |
| `style="text-align: ..."`                                | [`TextAlignPlugin`](/docs/text-align)           | Sets `align` property on block elements.                                 |
| `style="line-height: ..."`                               | [`LineHeightPlugin`](/docs/line-height)      | Sets `lineHeight` property on block elements.                            |

<Callout type="note" title="Plugin Configuration">
  The exact Plate type (e.g., `ParagraphPlugin.key` vs. `'p'`) depends on how plugins are configured. The table shows typical associations. Ensure the corresponding Plate plugins are included in your editor for these rules to apply.
</Callout>

### Deserialization Properties in Plugins

Plugins can define how they handle HTML deserialization using properties within their `parsers.html.deserializer` configuration:

-   **`parse`**: A function `({ editor, element, getOptions, ... }) => Partial<SlateNode>` that takes an HTML element and returns a partial Plate node. This is where the main conversion logic resides.
-   **`query`**: An optional function `({ element, getOptions }) => boolean` that determines if the deserializer rule should even be considered for the current HTML element.
-   **`rules`**: An array of rule objects, each defining conditions for matching an HTML element:
    -   `validNodeName`: String or array of strings for matching HTML tag names (e.g., `'P'`, `['STRONG', 'B']`).
    -   `validAttribute`: Object or array of objects specifying required attribute names and/or values (e.g., `{ align: ['left', 'center'] }`).
    -   `validClassName`: String or array of strings for matching CSS class names.
    -   `validStyle`: Object or array of objects specifying required CSS style properties and/or values (e.g., `{ fontWeight: ['600', '700', 'bold'] }`).
-   **`isElement`**: Boolean, `true` if the plugin deserializes an HTML element into a Plate Element node.
-   **`isLeaf`**: Boolean, `true` if the plugin deserializes an HTML element or style into a Plate Leaf (mark) on a Text node.
-   **`attributeNames`**: Array of HTML attribute names whose values should be preserved on the `node.attributes` property of the resulting Plate node.
-   **`withoutChildren`**: Boolean, if `true`, child nodes of the HTML element are not processed by `convertHtmlAttributes`.

### Customizing Deserialization Behavior

You can extend a plugin to modify its HTML parsing logic. This is useful for supporting non-standard HTML attributes or structures.

```tsx title="lib/custom-code-block-plugin.ts"
import { CodeBlockPlugin } from '@platejs/code-block/react';
import { CodeLinePlugin } from '@platejs/code-block'; // Base if needed

const MyCustomCodeBlockPlugin = CodeBlockPlugin.configure({
  parsers: {
    html: {
      deserializer: {
        // Inherit most rules and properties, then override or add
        ...CodeBlockPlugin.parsers.html.deserializer,
        parse: ({ element, editor }) => { // editor might be needed for getType
          const language = element.getAttribute('data-custom-lang') || element.className.match(/language-(?<lang>[^\s]+)/)?.groups?.lang;
          const textContent = element.textContent || '';
          const lines = textContent.split('\n');

          return {
            type: CodeBlockPlugin.key, // Or editor.getType(CodeBlockPlugin.key)
            lang: language,
            code: textContent, // Example: store full code string
            children: lines.map((line) => ({
              type: editor.getType(CodeLinePlugin.key),
              children: [{ text: line }],
            })),
          };
        },
        rules: [
          // Inherit existing rules if desired
          ...(CodeBlockPlugin.parsers.html.deserializer.rules || []),
          // Add a new rule to match based on a custom attribute
          { validAttribute: { 'data-custom-lang': true } },
        ],
      },
    },
  },
});

// Then use MyCustomCodeBlockPlugin in your editor configuration.
```
This example customizes `CodeBlockPlugin` to look for a `data-custom-lang` attribute or a `language-*` class for determining the code language.

### Advanced Deserialization Example (`ListPlugin`)

The `ListPlugin` demonstrates a more complex deserialization scenario where it transforms HTML list structures (`<li>` elements) into indented paragraphs within Plate, using `aria-level` to determine indentation.

Here's a conceptual look at its deserialization logic:

```ts
// Simplified concept from ListPlugin
export const ListPluginConfig = {
  // ... other configurations ...
  parsers: {
    html: {
      deserializer: {
        isElement: true,
        // query: ({ element }) => hasListAncestor(element), // Example condition
        parse: ({ editor, element }) => ({
          type: 'p', // Converts <li> to <p>
          indent: Number(element.getAttribute('aria-level') || '1'),
          listStyleType: element.style.listStyleType || undefined,
          // Children are processed by Plate's default deserializer after this node is created
        }),
        rules: [
          { validNodeName: 'LI' }, // Only applies to <li> elements
        ],
      },
    },
  },
};
```
This illustrates how a plugin can completely reinterpret HTML structures into a different Plate representation.

</Steps>

## API Reference

### `serializeHtml(editor, options)`

Converts Plate nodes from `editor.children` (or a provided `value`) into an HTML string. This function is typically used server-side.

<API name="serializeHtml">
<APIParameters>
  <APIItem name="editor" type="PlateEditor">
    A server-side Plate editor instance, created via `createSlateEditor` with components configured.
  </APIItem>
  <APIItem name="options" type="SerializeHtmlOptions">
    Options for serialization.
  </APIItem>
</APIParameters>
<APIOptions type="SerializeHtmlOptions<P = PlateStaticProps>">
  <APIItem name="editorComponent" type="React.ComponentType<P>" optional>
    A React component to wrap the entire editor content during static rendering. Defaults to `PlateStatic`.
    The component receives `editor`, `value`, and any `props` passed here.
  </APIItem>
  <APIItem name="props" type="Partial<P>" optional>
    Props to pass to the `editorComponent`. `P` defaults to `PlateStaticProps`.
  </APIItem>
  <APIItem name="value" type="Descendant[]" optional>
    Plate nodes to serialize. If not provided, `editor.children` will be used.
  </APIItem>
  <APIItem name="preserveClassNames" type="string[]" optional>
    Class name prefixes to preserve when `stripClassNames` is true. Default preserve list in the stripping helper: `['slate-']`.
  </APIItem>
  <APIItem name="stripClassNames" type="boolean" optional>
    If `true`, removes all class names from the output HTML except those whose prefixes are listed in `preserveClassNames`. Default: `false`.
  </APIItem>
  <APIItem name="stripDataAttributes" type="boolean" optional>
    If `true`, removes all `data-*` attributes from the output HTML. Default: `false`.
  </APIItem>
</APIOptions>
<APIReturns>
  <APIItem type="Promise<string>">
    A promise that resolves to the serialized HTML string.
  </APIItem>
</APIReturns>
</API>

---

### `api.html.deserialize(options)`

Parses an HTML string or `HTMLElement` into a Plate `Value` (an array of `Descendant` nodes). This is typically used on the client-side with a fully configured Plate editor.

<API name="deserializeHtml">
<APIParameters>
  <APIItem name="editor" type="PlateEditor">
    The client-side Plate editor instance.
  </APIItem>
  <APIItem name="options" type="DeserializeHtmlOptions">
    Options for deserialization.
  </APIItem>
</APIParameters>
<APIOptions type="DeserializeHtmlOptions">
  <APIItem name="element" type="HTMLElement | string">
    The HTML string or `HTMLElement` to deserialize.
  </APIItem>
  <APIItem name="collapseWhiteSpace" type="boolean" optional>
    If `true` (default), collapses whitespace from text nodes similarly to how browsers treat whitespace in HTML. Set to `false` to preserve all whitespace. Default: `true`.
  </APIItem>
  <APIItem name="stripWhitespace" type="boolean" optional>
    **Deprecated.** Use `collapseWhiteSpace`. If `true`, leading/trailing whitespace is trimmed and sequences of whitespace are collapsed. Default: `true`.
  </APIItem>
</APIOptions>
<APIReturns>
  <APIItem type="Descendant[]">
    The deserialized Plate `Value`.
  </APIItem>
</APIReturns>
</API>

## Next Steps

-   Explore the [Static Rendering guide](/docs/static) for creating server-safe components.
-   Review individual plugin documentation for specific HTML serialization/deserialization capabilities and default rules.
-   See the [Server-Side HTML Generation Example](/docs/examples/slate-to-html).


# Markdown

Source: https://platejs.org/docs/markdown

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Markdown
description: Convert Plate content to Markdown and vice-versa.
toc: true
---

The `@platejs/markdown` package provides robust, two-way conversion between Markdown and Plate's content structure.

[markdown-to-slate-demo registry content](https://platejs.org/r/markdown-to-slate-demo)

[markdown-demo registry content](https://platejs.org/r/markdown-demo)

<PackageInfo>

## Features

- **Markdown to Plate JSON:** Convert Markdown strings to Plate's editable format (`deserialize`).
- **Plate JSON to Markdown:** Convert Plate content back to Markdown strings (`serialize`).
- **Safe by Default:** Handles Markdown conversion without `dangerouslySetInnerHTML`.
- **Customizable Rules:** Define how specific Markdown syntax or custom Plate elements are converted using `rules`. Supports MDX.
- **Extensible:** Utilize [remark plugins](https://github.com/remarkjs/remark/blob/main/doc/plugins.md#list-of-plugins) via the `remarkPlugins` option.
- **Compliant:** Supports CommonMark, with GFM (GitHub Flavored Markdown) available via [`remark-gfm`](https://github.com/remarkjs/remark-gfm).
- **Round-Trip Serialization:** Preserves custom elements through MDX syntax during conversion cycles.

</PackageInfo>

## Why Use Plate Markdown?

While libraries like `react-markdown` render Markdown to React elements, `@platejs/markdown` offers deeper integration with the Plate ecosystem:

- **Rich Text Editing:** Enables advanced editing features by converting Markdown to Plate's structured format.
- **WYSIWYG Experience:** Edit content in a rich text view and serialize it back to Markdown.
- **Custom Elements & Data:** Handles complex custom Plate elements (mentions, embeds) by converting them to/from MDX.
- **Extensibility:** Leverages Plate's plugin system and the unified/remark ecosystem for powerful customization.

<Callout type="note">
  If you only need to display Markdown as HTML without editing or custom
  elements, `react-markdown` might be sufficient. For a rich text editor with
  Markdown import/export and custom content, `@platejs/markdown` is the
  integrated solution.
</Callout>

## Kit Usage

<Steps>

### Installation

The fastest way to add Markdown functionality is with the `MarkdownKit`, which includes pre-configured `MarkdownPlugin` with essential remark plugins for [Plate UI](/docs/installation/plate-ui) compatibility.

[markdown-kit registry content](https://platejs.org/r/markdown-kit)

### Add Kit

```tsx
import { createPlateEditor } from 'platejs/react';
import { MarkdownKit } from '@/components/editor/plugins/markdown-kit';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    ...MarkdownKit,
  ],
});
```

</Steps>

## Manual Usage

<Steps>

### Installation

```bash
npm install platejs @platejs/markdown
```

### Add Plugin

```tsx
import { MarkdownPlugin } from '@platejs/markdown';
import { createPlateEditor } from 'platejs/react';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    MarkdownPlugin,
  ],
});
```

### Configure Plugin

Configuring `MarkdownPlugin` is recommended to enable Markdown paste handling and set default conversion `rules`.

```tsx title="lib/plate-editor.ts"
import { createPlateEditor } from 'platejs/react';
import {
  MarkdownPlugin,
  remarkMention,
  remarkMdx,
} from '@platejs/markdown';
import remarkEmoji from 'remark-emoji';
import remarkGfm from 'remark-gfm';
import remarkMath from 'remark-math';

const editor = createPlateEditor({
  plugins: [
    // ...other Plate plugins
    MarkdownPlugin.configure({
      options: {
        // Add remark plugins for syntax extensions (GFM, emoji shortcodes, Math, MDX)
        remarkPlugins: [remarkMath, remarkGfm, remarkEmoji, remarkMdx, remarkMention],
        // Define custom rules if needed
        rules: {
          // date: { /* ... rule implementation ... */ },
        },
      },
    }),
  ],
});

// To disable Markdown paste handling:
const editorWithoutPaste = createPlateEditor({
  plugins: [
    // ...other Plate plugins
    MarkdownPlugin.configure(() => ({ parser: null })),
  ],
});
```

<Callout type="info">
  If you don't use `MarkdownPlugin` with `configure`, you can still use
  `editor.api.markdown.deserialize` and `editor.api.markdown.serialize`
  directly, but without plugin-configured default rules or paste handling.
</Callout>

### Markdown to Plate (Deserialization)

Use `editor.api.markdown.deserialize` to convert a Markdown string into a Plate `Value` (an array of nodes). This is often used for the editor's initial content.

```tsx title="components/my-editor.tsx"
import { createPlateEditor } from 'platejs/react';
import { MarkdownPlugin } from '@platejs/markdown';
// ... import other necessary Plate plugins for rendering elements

const markdownString = '# Hello, *Plate*!';

const editor = createPlateEditor({
  plugins: [
    // MarkdownPlugin must be included
    MarkdownPlugin,
    // ... other plugins needed to render the deserialized elements (e.g., HeadingPlugin, ItalicPlugin)
  ],
  // Use deserialize in the value factory for initial content
  value: (editor) =>
    editor.getApi(MarkdownPlugin).markdown.deserialize(markdownString),
});
```

<Callout type="warning" title="Plugin Requirements">
  Ensure all Plate plugins required to render the deserialized Markdown (e.g.,
  `HeadingPlugin` for `#`, `TablePlugin` for tables) are included in your
  editor's `plugins` array.
</Callout>

### Plate to Markdown (Serialization)

Use `editor.api.markdown.serialize` to convert the current editor content (or a specific array of nodes) into a Markdown string.

**Serializing Current Editor Content:**

```tsx
// Assuming `editor` is your Plate editor instance with content
const markdownOutput = editor.api.markdown.serialize();
console.info(markdownOutput);
```

**Serializing Specific Nodes:**

```tsx
const specificNodes = [
  { type: 'p', children: [{ text: 'Serialize just this paragraph.' }] },
  { type: 'h1', children: [{ text: 'And this heading.' }] },
];

// Assuming `editor` is your Plate editor instance
const partialMarkdownOutput = editor.api.markdown.serialize({
  value: specificNodes,
});
console.info(partialMarkdownOutput);
```

### Round-Trip Serialization with Custom Elements (MDX)

A key feature is handling custom Plate elements that lack standard Markdown representation (e.g., underline, mentions). `@platejs/markdown` converts these to [MDX][github-mdx] elements during serialization and parses them back during deserialization.

**Example:** Handling a custom `date` element.

**Plate Node Structure:**

```ts
{
  type: 'p',
  children: [
    { text: 'Today is ' },
    { type: 'date', date: '2025-03-31', children: [{ text: '' }] } // Leaf elements need a text child
  ],
}
```

**Plugin Configuration with `rules`:**

```tsx title="lib/plate-editor.ts"
import type { MdMdxJsxTextElement } from '@platejs/markdown';
import { MarkdownPlugin, remarkMdx } from '@platejs/markdown';
// ... other imports

MarkdownPlugin.configure({
  options: {
    rules: {
      // Key matches:
      // 1. Plate element's plugin 'key' or 'type'.
      // 2. mdast node type.
      // 3. MDX tag name.
      date: {
        // Markdown -> Plate
        deserialize(mdastNode: MdMdxJsxTextElement, deco, options) {
          const dateValue = (mdastNode.children?.[0] as any)?.value || '';
          return {
            type: 'date', // Your Plate element type
            date: dateValue,
            children: [{ text: '' }], // Valid Plate structure
          };
        },
        // Plate -> Markdown (MDX)
        serialize: (slateNode): MdMdxJsxTextElement => {
          return {
            type: 'mdxJsxTextElement',
            name: 'date', // MDX tag name
            attributes: [], // Optional: [{ type: 'mdxJsxAttribute', name: 'date', value: slateNode.date }]
            children: [{ type: 'text', value: slateNode.date || '1999-01-01' }],
          };
        },
      },
      // ... rules for other custom elements
    },
    remarkPlugins: [remarkMdx /*, ... other remark plugins like remarkGfm */],
  },
});
```

**Conversion Process:**

1.  **Serialization (Plate → Markdown):** The Plate `date` node writes as `<date value="2025-03-31" />`.
2.  **Deserialization (Markdown → Plate):** Both `<date value="2025-03-31" />` and `<date>2025-03-31</date>` convert back to the Plate `date` node.

</Steps>

## API Reference

### `MarkdownPlugin`

The core plugin configuration object. Use `MarkdownPlugin.configure({ options: {} })` to set global options for Markdown processing.

<API name="MarkdownPlugin">
  <APIOptions>
    <APIItem name="allowedNodes" type="PlateType | null">
      Whitelist specific node types (Plate types and Markdown AST types like
      `strong`). Cannot be used with `disallowedNodes`. If set, only listed
      types are processed. Default: `null` (all allowed).
    </APIItem>
    <APIItem name="disallowedNodes" type="PlateType | null">
      Blacklist specific node types. Cannot be used with `allowedNodes`. Listed
      types are filtered out. Default: `null`.
    </APIItem>
    <APIItem name="allowNode" type="AllowNodeConfig">
      Fine-grained node filtering with custom functions, applied *after*
      `allowedNodes`/`disallowedNodes`. - `deserialize?: (mdastNode: any) =>
      boolean`: Filter for Markdown → Plate. Return `true` to keep. -
      `serialize?: (slateNode: any) => boolean`: Filter for Plate → Markdown.
      Return `true` to keep. Default: `null`.
    </APIItem>
    <APIItem name="rules" type="MdRules | null">
      Custom conversion rules between Markdown AST and Plate elements. See
      [Round-Trip
      Serialization](#round-trip-serialization-with-custom-elements-mdx) and
      [Customizing Conversion Rules](#appendix-b-customizing-conversion-rules).
      For marks/leaves, ensure the rule object has `mark: true`. Default: `null`
      (uses internal `defaultRules`).
    </APIItem>
    <APIItem name="remarkPlugins" type="Plugin[]">
      Array of [remark
      plugins](https://github.com/remarkjs/remark/blob/main/doc/plugins.md#list-of-plugins)
      (e.g., `remark-gfm`, `remark-math`, `remark-mdx`). Operates on Markdown
      AST (`mdast`). Default: `[]`.
    </APIItem>
  </APIOptions>
  <APIAttributes>
    <APIItem name="parser" type="Parser | null">
      Configuration for pasted content. Set to `null` to disable Markdown paste
      handling. Default enables pasting `text/plain` as Markdown. See
      [PlatePlugin API > parser](/docs/api/core/plate-plugin#parser).
    </APIItem>
  </APIAttributes>
</API>

---

### `api.markdown.deserialize`

Converts a Markdown string into a Plate `Value` (`Descendant[]`).

<API name="deserialize">
  <APIParameters>
    <APIItem name="markdown" type="string">
      The Markdown string to deserialize.
    </APIItem>
    <APIItem name="options" type="DeserializeMdOptions" optional>
      Options for this call, overriding plugin defaults.
    </APIItem>
  </APIParameters>
  <APIOptions type="DeserializeMdOptions">
    <APIItem name="allowedNodes" type="PlateType" optional>
      Override plugin `allowedNodes`.
    </APIItem>
    <APIItem name="disallowedNodes" type="PlateType" optional>
      Override plugin `disallowedNodes`.
    </APIItem>
    <APIItem name="allowNode" type="AllowNodeConfig" optional>
      Override plugin `allowNode`.
    </APIItem>
    <APIItem name="memoize" type="boolean" optional>
      Adds `_memo` property with raw Markdown to top-level blocks for
      memoization (e.g., with `PlateStatic`). Default: `false`.
    </APIItem>
    <APIItem name="rules" type="MdRules | null" optional>
      Override plugin `rules`.
    </APIItem>
    <APIItem name="parser" type="ParseMarkdownBlocksOptions" optional>
      Options for the underlying Markdown block parser (`parseMarkdownBlocks`).
      See below.
    </APIItem>
    <APIItem name="remarkPlugins" type="Plugin[]" optional>
      Override plugin `remarkPlugins`.
    </APIItem>
    <APIItem name="splitLineBreaks" type="boolean" optional>
      If `true`, single line breaks (`\\n`) in paragraphs become paragraph
      breaks. Default: `false`.
    </APIItem>
    <APIItem name="withoutMdx" type="boolean" optional>
      If `true`, skips the MDX preprocessing pass and filters `remarkMdx` out
      of the plugin list. Default: `false`.
    </APIItem>
    <APIItem name="preserveEmptyParagraphs" type="boolean" optional>
      Preserves empty paragraph nodes during deserialization.
    </APIItem>
    <APIItem name="onError" type="(error: Error) => void" optional>
      Receives parser errors before the safe fallback path runs.
    </APIItem>
  </APIOptions>
  <APIReturns type="Descendant[]">An array of Plate nodes.</APIReturns>
</API>

---

### `api.markdown.deserializeInline`

Converts inline Markdown text into Slate children.

<API name="deserializeInline">
  <APIParameters>
    <APIItem name="markdown" type="string">
      Inline Markdown text to deserialize.
    </APIItem>
    <APIItem name="options" type="DeserializeMdOptions" optional>
      Options for this call, overriding plugin defaults.
    </APIItem>
  </APIParameters>
  <APIReturns type="Descendant[]">Slate children for inline content.</APIReturns>
</API>

---

### `api.markdown.serialize`

Converts a Plate `Value` (`Descendant[]`) into a Markdown string.

<API name="serialize">
  <APIParameters>
    <APIItem name="options" type="SerializeMdOptions" optional>
      Options for this call, overriding plugin defaults.
    </APIItem>
  </APIParameters>
  <APIOptions type="SerializeMdOptions">
    <APIItem name="value" type="Descendant[]" optional>
      Plate nodes to serialize. Defaults to `editor.children`.
    </APIItem>
    <APIItem name="allowedNodes" type="PlateType" optional>
      Override plugin `allowedNodes`.
    </APIItem>
    <APIItem name="disallowedNodes" type="PlateType" optional>
      Override plugin `disallowedNodes`.
    </APIItem>
    <APIItem name="allowNode" type="AllowNodeConfig" optional>
      Override plugin `allowNode`.
    </APIItem>
    <APIItem name="rules" type="MdRules | null" optional>
      Override plugin `rules`.
    </APIItem>
    <APIItem name="remarkPlugins" type="Plugin[]" optional>
      Override plugin `remarkPlugins` (affects stringification).
    </APIItem>
    <APIItem name="remarkStringifyOptions" type="RemarkStringifyOptions | null" optional>
      Options passed to `remark-stringify`. Defaults to plugin options, with
      Plate setting emphasis to `_` and resource links to `false`.
    </APIItem>
    <APIItem name="plainMarks" type="PlateType[] | null" optional>
      Marks to serialize as plain text instead of Markdown formatting.
    </APIItem>
    <APIItem name="spread" type="boolean" optional>
      Controls spread formatting for list output. Default: `false`.
    </APIItem>
    <APIItem name="preserveEmptyParagraphs" type="boolean" optional>
      Preserves empty paragraph nodes during serialization.
    </APIItem>
    <APIItem name="withBlockId" type="boolean" optional>
      When true, preserves block IDs in markdown serialization to enable AI
      comment tracking. Wraps blocks with `<block id="...">content</block>`
      syntax. - **Default:** `false`
    </APIItem>
  </APIOptions>
  <APIReturns type="string">A Markdown string.</APIReturns>
</API>

---

### `parseMarkdownBlocks`

Utility to parse a Markdown string into block-level tokens (used by `deserialize`, useful with `memoize`).

<API name="parseMarkdownBlocks">
  <APIParameters>
    <APIItem name="markdown" type="string">
      The Markdown string.
    </APIItem>
    <APIItem name="options" type="ParseMarkdownBlocksOptions" optional>
      Parsing options.
    </APIItem>
  </APIParameters>
  <APIOptions type="ParseMarkdownBlocksOptions">
    <APIItem name="exclude" type="string[]" optional>
      Marked token types (e.g., `'space'`) to exclude. Default: `['space']`.
    </APIItem>
    <APIItem name="trim" type="boolean" optional>
      Trim trailing whitespace from input. Default: `true`.
    </APIItem>
  </APIOptions>
  <APIReturns type="Token[]">
    Array of marked `Token` objects with raw Markdown.
  </APIReturns>
</API>

## Examples

<Steps>

### Using a Remark Plugin (GFM)

Add support for GitHub Flavored Markdown (tables, strikethrough, task lists, autolinks).

**Plugin Configuration:**

```tsx title="lib/plate-editor.ts"
import { createPlateEditor } from 'platejs/react';
import { MarkdownPlugin } from '@platejs/markdown';
import remarkGfm from 'remark-gfm';
// Import Plate plugins for GFM elements
import { TablePlugin } from '@platejs/table/react';
import { TodoListPlugin } from '@platejs/list-classic/react'; // Ensure this is the correct List plugin for tasks
import { StrikethroughPlugin } from '@platejs/basic-nodes/react';
import { LinkPlugin } from '@platejs/link/react';

const editor = createPlateEditor({
  plugins: [
    // ...other plugins
    TablePlugin,
    TodoListPlugin, // Or your specific task list plugin
    StrikethroughPlugin,
    LinkPlugin,
    MarkdownPlugin.configure({
      options: {
        remarkPlugins: [remarkGfm],
      },
    }),
  ],
});
```

**Usage:**

```tsx
const markdown = `
A table:

| a | b |
| - | - |

~~Strikethrough~~

- [x] Task list item

Visit https://platejs.org
`;

// Assuming `editor` is your configured Plate editor instance
const slateValue = editor.api.markdown.deserialize(markdown);
// editor.tf.setValue(slateValue); // To set editor content

const markdownOutput = editor.api.markdown.serialize();
// markdownOutput will contain GFM syntax
```

### Customizing Rendering (Syntax Highlighting)

This example shows two approaches: customizing the rendering component (common for UI changes) and customizing the conversion rule (advanced, for changing Plate structure).

**Background:**

- `@platejs/markdown` converts Markdown fenced code blocks (e.g., \`\`\`js ... \`\`\`) to Plate `code_block` elements with `code_line` children.
- The Plate `CodeBlockElement` (often from `@platejs/code-block/react`) renders this structure.
- Syntax highlighting typically occurs within `CodeBlockElement` using a library like `lowlight` (via `CodeBlockPlugin`). See [Code Block Plugin](/docs/code-block) for details.

**Approach 1: Customizing Rendering Component (Recommended for UI)**

To change how code blocks appear, customize the component for the `code_block` plugin key.

```tsx title="components/my-editor.tsx"
import { createPlateEditor } from 'platejs/react';
import {
  CodeBlockPlugin,
  CodeLinePlugin,
  CodeSyntaxPlugin,
} from '@platejs/code-block/react';
import { MarkdownPlugin } from '@platejs/markdown';
import { MyCustomCodeBlockElement } from './my-custom-code-block'; // Your custom component

const editor = createPlateEditor({
  plugins: [
    CodeBlockPlugin.withComponent(MyCustomCodeBlockElement), // Base plugin for structure/logic
    CodeLinePlugin.withComponent(MyCustomCodeLineElement),
    CodeSyntaxPlugin.withComponent(MyCustomCodeSyntaxElement),
    MarkdownPlugin, // For Markdown conversion
    // ... other plugins
  ],
});

// MyCustomCodeBlockElement.tsx would then implement the desired rendering
// (e.g., using react-syntax-highlighter), consuming props from PlateElement.
```

Refer to the [Code Block Plugin documentation](/docs/code-block) for complete examples.

**Approach 2: Customizing Conversion Rule (Advanced - Changing Plate Structure)**

To fundamentally alter the Plate JSON for code blocks (e.g., storing code as a single string prop), override the `deserialize` rule.

```tsx title="lib/plate-editor.ts"
import { MarkdownPlugin } from '@platejs/markdown';
import { CodeBlockPlugin } from '@platejs/code-block/react';

MarkdownPlugin.configure({
  options: {
    rules: {
      // Override deserialization for mdast 'code' type
      code: {
        deserialize: (mdastNode, deco, options) => {
          return {
            type: KEYS.codeBlock, // Use Plate's type
            lang: mdastNode.lang ?? undefined,
            rawCode: mdastNode.value || '', // Store raw code directly
            children: [{ text: '' }], // Plate Element needs a dummy text child
          };
        },
      },
      // A custom `serialize` rule for `code_block` would also be needed
      // to convert `rawCode` back to an mdast 'code' node.
      [KEYS.codeBlock]: {
        serialize: (slateNode, options) => {
          return {
            // mdast 'code' node
            type: 'code',
            lang: slateNode.lang,
            value: slateNode.rawCode,
          };
        },
      },
    },
    // remarkPlugins: [...]
  },
});

// Your custom rendering component (MyCustomCodeBlockElement) would then
// need to read the code from the `rawCode` property.
```

Choose based on whether you're changing UI (Approach 1) or data structure (Approach 2).

### Using Remark Plugins for Math (`remark-math`)

Enable TeX math syntax (`$inline$`, `$$block$$`).

**Plugin Configuration:**

```tsx title="lib/plate-editor.ts"
import { createPlateEditor } from 'platejs/react';
import { MarkdownPlugin } from '@platejs/markdown';
import remarkMath from 'remark-math';
// Import Plate math plugins for rendering
import { MathPlugin } from '@platejs/math/react'; // Main Math plugin

const editor = createPlateEditor({
  plugins: [
    // ...other plugins
    MathPlugin, // Renders block and inline equations
    MarkdownPlugin.configure({
      options: {
        remarkPlugins: [remarkMath],
        // Default rules handle 'math' and 'inlineMath' mdast types from remark-math,
        // converting them to Plate's 'equation' and 'inline_equation' types.
      },
    }),
  ],
});
```

**Usage:**

```tsx
const markdown = `
Inline math: $E=mc^2$

Block math:
$$
\\int_a^b f(x) dx = F(b) - F(a)
$$
`;

// Assuming `editor` is your configured Plate editor instance
const slateValue = editor.api.markdown.deserialize(markdown);
// slateValue will contain 'inline_equation' and 'equation' nodes.

const markdownOutput = editor.api.markdown.serialize({ value: slateValue });
// markdownOutput will contain $...$ and $$...$$ syntax.
```

### Using Mentions (`remarkMention`)

Enable mention syntax using the link format for consistency and special character support.

**Plugin Configuration:**

```tsx title="lib/plate-editor.ts"
import { createPlateEditor } from 'platejs/react';
import { MarkdownPlugin, remarkMention } from '@platejs/markdown';
import { MentionPlugin } from '@platejs/mention/react';

const editor = createPlateEditor({
  plugins: [
    // ...other plugins
    MentionPlugin,
    MarkdownPlugin.configure({
      options: {
        remarkPlugins: [remarkMention],
      },
    }),
  ],
});
```

**Supported Format:**

```tsx
const markdown = `
Mention: [Alice](mention:alice)
Mention with spaces: [John Doe](mention:john_doe)
Full name with ID: [Jane Smith](mention:user_123)
`;

// Assuming `editor` is your configured Plate editor instance
const slateValue = editor.api.markdown.deserialize(markdown);
// Creates mention nodes with appropriate values and display text

const markdownOutput = editor.api.markdown.serialize({ value: slateValue });
// All mentions use the link format: [Alice](mention:alice), [John Doe](mention:john_doe), etc.
```

The `remarkMention` plugin uses the **[display text](mention:id)** format - a Markdown link-style format that supports spaces and custom display text.

When serializing, all mentions use the link format to ensure consistency and support for special characters.

### Using Columns

Enable column layouts with MDX support for multi-column documents.

**Plugin Configuration:**

```tsx title="lib/plate-editor.ts"
import { createPlateEditor } from 'platejs/react';
import { MarkdownPlugin, remarkMdx } from '@platejs/markdown';
import { ColumnPlugin, ColumnItemPlugin } from '@platejs/layout/react';

const editor = createPlateEditor({
  plugins: [
    // ...other plugins
    ColumnPlugin,
    ColumnItemPlugin,
    MarkdownPlugin.configure({
      options: {
        remarkPlugins: [remarkMdx], // Required for column MDX syntax
      },
    }),
  ],
});
```

**Supported Format:**

```tsx
const markdown = `
<column_group>
  <column width="50%">
    Left column content with 50% width
  </column>
  <column width="50%">
    Right column content with 50% width
  </column>
</column_group>

<column_group>
  <column width="33%">First</column>
  <column width="33%">Second</column>
  <column width="34%">Third</column>
</column_group>
`;

// Assuming `editor` is your configured Plate editor instance
const slateValue = editor.api.markdown.deserialize(markdown);
// Creates column_group with nested column elements

const markdownOutput = editor.api.markdown.serialize({ value: slateValue });
// Preserves column structure with width attributes
```

**Column Features:**

- Supports arbitrary number of columns
- Width attributes are optional (defaults to equal distribution)
- Nested content fully supported within columns
- Width normalization ensures columns always sum to 100%

</Steps>

## Remark Plugins

`@platejs/markdown` leverages the [unified][github-unified] / [remark][github-remark] ecosystem. Extend its capabilities by adding remark plugins via the `remarkPlugins` option in `MarkdownPlugin.configure`. These plugins operate on the [mdast (Markdown Abstract Syntax Tree)][github-mdast].

**Finding Plugins:**

- [List of remark plugins][github-remark-plugins] (Official)
- [`remark-plugin` topic on GitHub][github-topic-remark-plugin]
- [Awesome Remark][github-awesome-remark]

**Common Uses:**

- **Syntax Extensions:** `remark-gfm` (tables, etc.), `remark-math` (TeX), `remark-frontmatter`, `remark-mdx`.
- **Linting/Formatting:** `remark-lint` (often separate tooling).
- **Custom Transformations:** Custom plugins to modify mdast.

<Callout type="info" title="Remark vs. Rehype">
  Plate components (e.g., `TableElement`, `CodeBlockElement`) render Plate JSON.
  `remarkPlugins` modify the Markdown AST. Unlike some renderers,
  `rehypePlugins` (for HTML AST) are not part of `MarkdownPlugin`'s conversion
  pipeline. Run HTML transforms before Plate, or model controlled HTML-like
  content as MDX plus explicit `rules`.
</Callout>

## Syntax Support

`@platejs/markdown` uses [`remark-parse`][github-remark-parse], adhering to [CommonMark][commonmark-spec]. Enable GFM or other syntaxes via `remarkPlugins`.

- **Learn Markdown:** [CommonMark Help][commonmark-help]
- **GFM Spec:** [GitHub Flavored Markdown Spec][gfm-spec]

## Architecture Overview

`@platejs/markdown` bridges Markdown strings and Plate's editor format using the unified/remark ecosystem.

```
                                             @platejs/markdown
          +--------------------------------------------------------------------------------------------+
          |                                                                                            |
          |  +-----------+        +----------------+        +---------------+      +-----------+       |
          |  |           |        |                |        |               |      |           |       |
 markdown-+->+ remark    +-mdast->+ remark plugins +-mdast->+ mdast-to-slate+----->+   nodes   +-plate-+->react elements
          |  |           |        |                |        |               |      |           |       |
          |  +-----------+        +----------------+        +---------------+      +-----------+       |
          |       ^                                                                      |             |
          |       |                                                                      v             |
          |  +-----------+        +----------------+        +---------------+      +-----------+       |
          |  |           |        |                |        |               |      |           |       |
          |  | stringify |<-mdast-+ remark plugins |<-mdast-+ slate-to-mdast+<-----+ serialize |       |
          |  |           |        |                |        |               |      |           |       |
          |  +-----------+        +----------------+        +---------------+      +-----------+       |
          |                                                                                            |
          +--------------------------------------------------------------------------------------------+
```

**Key Steps:**

1.  **Parse (Deserialization):**
    - Markdown string → `remark-parse` → mdast.
    - `remarkPlugins` transform mdast (e.g., `remark-gfm`).
    - `mdast-to-slate` converts mdast to Plate nodes using `rules`.
    - Plate renders nodes via its component system.
2.  **Stringify (Serialization):**
    - Plate nodes → `slate-to-mdast` (using `rules`) → mdast.
    - `remarkPlugins` transform mdast.
    - `remark-stringify` converts mdast to Markdown string.

<Callout type="note" title="Comparison with react-markdown">
  - **Direct Node Rendering:** Plate directly renders its nodes via components,
  unlike `react-markdown` which often uses rehype to convert Markdown to HTML,
  then to React elements. - **Bidirectional:** Plate's Markdown processor is
  fully bidirectional. - **Rich Text Integration:** Nodes are integrated with
  Plate's editing capabilities. - **Plugin System:** Components are managed via
  Plate's plugin system.
</Callout>

## Migrating from `react-markdown`

Migrating involves mapping `react-markdown` concepts to Plate's architecture.

**Key Differences:**

1.  **Rendering Pipeline:** `react-markdown` (MD → mdast → hast → React) vs. `@platejs/markdown` (MD ↔ mdast ↔ Plate JSON; Plate components render Plate JSON).
2.  **Component Customization:**
    - `react-markdown`: `components` prop replaces HTML tag renderers.
    - Plate:
      - `MarkdownPlugin` `rules`: Customize mdast ↔ Plate JSON conversion.
      - `createPlateEditor` `components`: Customize React components for Plate node types. See [Appendix C](#appendix-c-components).
3.  **Plugin Ecosystem:** `@platejs/markdown` primarily uses `remarkPlugins`. `rehypePlugins` are less common.

**Mapping Options:**

| `react-markdown` Prop           | `@platejs/markdown` Equivalent/Concept                                                                           | Notes                                                                                  |
| :------------------------------ | :--------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------- |
| `children` (string)             | Pass to `editor.api.markdown.deserialize(string)`                                                                | Input for deserialization; often in `createPlateEditor` `value` option.                |
| `remarkPlugins`                 | `MarkdownPlugin.configure({ options: { remarkPlugins: [...] }})`                                                 | Direct mapping; operates on mdast.                                                     |
| `rehypePlugins`                 | Not part of `MarkdownPlugin`'s conversion pipeline.                                                              | Run any HTML pipeline before passing Markdown or Plate nodes to Plate.                 |
| `components={{ h1: MyH1 }}`     | `createPlateEditor({ components: { h1: MyH1 } })`                                                                | Configures Plate rendering component. Key depends on `HeadingPlugin` config.           |
| `components={{ code: MyCode }}` | 1. **Conversion**: `MarkdownPlugin > rules > code`. 2. **Rendering**: `components: { [KEYS.codeBlock]: MyCode }` | `rules` for mdast (`code`) to Plate (`code_block`). `components` for Plate rendering.  |
| `allowedElements`               | `MarkdownPlugin.configure({ options: { allowedNodes: [...] }})`                                                  | Filters nodes during conversion (mdast/Plate types).                                   |
| `disallowedElements`            | `MarkdownPlugin.configure({ options: { disallowedNodes: [...] }})`                                               | Filters nodes during conversion.                                                       |
| `unwrapDisallowed`              | No direct equivalent. Filtering removes nodes.                                                                   | Custom `rules` could implement unwrapping.                                             |
| `skipHtml`                      | Default behavior strips most HTML.                                                                               | Sanitize or convert raw HTML before calling `editor.api.markdown.deserialize`.          |
| `urlTransform`                  | Customize via `rules` for `link` (deserialize) or plugin type (serialize).                                       | Handle URL transformations in conversion rules.                                        |
| `allowElement`                  | `MarkdownPlugin.configure({ options: { allowNode: { ... } } })`                                                  | Function-based filtering during conversion.                                            |

## Appendix A: HTML in Markdown

By default, `@platejs/markdown` does **not** process raw HTML tags. Standard Markdown syntax still becomes Plate nodes, but literal HTML like `<div>` is ignored unless you handle it outside Plate or model it as MDX/custom nodes.

`MarkdownPlugin` runs `remark-parse`, configured `remarkPlugins`, and Plate conversion rules. It does not run a rehype HTML stage, so `rehype-raw` and `rehype-sanitize` are not `MarkdownPlugin` options.

For raw HTML from a trusted source, convert it in your own content pipeline before calling Plate. For untrusted input, sanitize with a strict element and attribute whitelist before deserializing.

```tsx
const safeMarkdown = await sanitizeMarkdownBeforePlate(untrustedMarkdown);

const value = editor.api.markdown.deserialize(safeMarkdown);
```

For HTML-like custom nodes that you control, prefer MDX syntax with `remarkMdx` and explicit `rules`. That keeps the conversion in Plate's supported Markdown pipeline.

<Callout type="destructive" title="Security Warning">
  Raw HTML can carry XSS payloads. Treat untrusted Markdown as unsafe until your
  own pipeline sanitizes it with a strict element and attribute whitelist.
</Callout>

## Appendix B: Customizing Conversion Rules (`rules`)

The `rules` option in `MarkdownPlugin.configure` offers fine-grained control over mdast ↔ Plate JSON conversion. Keys in the `rules` object match node types.

- **Deserialization (Markdown → Plate):** Keys are `mdast` node types (e.g., `paragraph`, `heading`, `strong`, `link`, MDX types like `mdxJsxTextElement`). The `deserialize` function takes `(mdastNode, deco, options)` and returns a Plate `Descendant` or `Descendant[]`.
- **Serialization (Plate → Markdown):** Keys are Plate element/text types (e.g., `p`, `h1`, `a`, `code_block`, `bold`). The `serialize` function takes `(slateNode, options)` and returns an `mdast` node.

**Example: Overriding Link Deserialization**

```tsx title="lib/plate-editor.ts"
MarkdownPlugin.configure({
  options: {
    rules: {
      // Rule for mdast 'link' type
      link: {
        deserialize: (mdastNode, deco, options) => {
          // Default creates { type: 'a', url: ..., children: [...] }
          // Add a custom property:
          return {
            type: 'a', // Plate link element type
            url: mdastNode.url,
            title: mdastNode.title,
            customProp: 'added-during-deserialize',
            children: convertChildrenDeserialize(
              mdastNode.children,
              deco,
              options
            ),
          };
        },
      },
      // Rule for Plate 'a' type (if serialization needs override for customProp)
      a: {
        // Assuming 'a' is the Plate type for links
        serialize: (slateNode, options) => {
          // Default creates mdast 'link'
          // Handle customProp if needed in MDX attributes or similar
          return {
            type: 'link', // mdast type
            url: slateNode.url,
            title: slateNode.title,
            // customProp: slateNode.customProp, // MDX attribute?
            children: convertNodesSerialize(slateNode.children, options),
          };
        },
      },
    },
    // ... remarkPlugins ...
  },
});
```

**Default Rules Summary:**
Refer to [`defaultRules.ts`](https://github.com/udecode/plate/blob/main/packages/markdown/src/lib/rules/defaultRules.ts) for the complete list. Key conversions include:

| Markdown (mdast)    | Plate Type             | Notes                                          |
| :------------------ | :--------------------- | :--------------------------------------------- |
| `paragraph`         | `p`                    |                                                |
| `heading` (depth)   | `h1` - `h6`            | Based on depth.                                |
| `blockquote`        | `blockquote`           |                                                |
| `list` (ordered)    | `ol` / `p`\*           | `ol`/`li`/`lic` or `p` with list indent props. |
| `list` (unordered)  | `ul` / `p`\*           | `ul`/`li`/`lic` or `p` with list indent props. |
| `code` (fenced)     | `code_block`           | Contains `code_line` children.                 |
| `inlineCode`        | `code` (mark)          | Applied to text.                               |
| `strong`            | `bold` (mark)          | Applied to text.                               |
| `emphasis`          | `italic` (mark)        | Applied to text.                               |
| `delete`            | `strikethrough` (mark) | Applied to text.                               |
| `link`              | `a`                    |                                                |
| `image`             | `img`                  | Wraps in paragraph during serialization.       |
| `thematicBreak`     | `hr`                   |                                                |
| `table`             | `table`                | Contains `tr`.                                 |
| `math` (block)      | `equation`             | Requires `remark-math`.                        |
| `inlineMath`        | `inline_equation`      | Requires `remark-math`.                        |
| `mdxJsxFlowElement` | _Custom_               | Requires `remark-mdx` and custom `rules`.      |
| `mdxJsxTextElement` | _Custom_               | Requires `remark-mdx` and custom `rules`.      |

\* List conversion depends on `ListPlugin` detection.

**Emoji shortcodes:** Add [`remark-emoji`](https://github.com/rhysd/remark-emoji) to `remarkPlugins` to turn `:fire:` into unicode `🔥` on deserialization and back to unicode on serialization.

**GFM footnotes:** With `remark-gfm` enabled, footnotes deserialize into `footnoteReference` and `footnoteDefinition` nodes. Add the matching [Footnote plugins](/docs/footnote) to render them as real editor nodes instead of falling back to unknown types.

---

**Default MDX Conversions (with `remark-mdx`):**

| MDX (mdast)                            | Plate Type               | Notes                                       |
| :------------------------------------- | :----------------------- | :------------------------------------------ |
| `<del>...</del>`                       | `strikethrough` (mark)   | Alt for `~~strikethrough~~`                 |
| `<sub>...</sub>`                       | `subscript` (mark)       | H<sub>2</sub>O                              |
| `<sup>...</sup>`                       | `superscript` (mark)     | E=mc<sup>2</sup>                            |
| `<u>...</u>`                           | `underline` (mark)       | <u>Underlined</u>                           |
| `<mark>...</mark>`                     | `highlight` (mark)       | <mark>Highlighted</mark>                    |
| `<span style="font-family: ...">`      | `fontFamily` (mark)      |                                             |
| `<span style="font-size: ...">`        | `fontSize` (mark)        |                                             |
| `<span style="font-weight: ...">`      | `fontWeight` (mark)      |                                             |
| `<span style="color: ...">`            | `color` (mark)           |                                             |
| `<span style="background-color: ...">` | `backgroundColor` (mark) |                                             |
| `<date>...</date>`                     | `date`                   | Custom Date element                         |
| `[text](mention:id)`                   | `mention`                | Custom Mention element                      |
| `<file name="..." />`                  | `file`                   | Custom File element                         |
| `<audio src="..." />`                  | `audio`                  | Custom Audio element                        |
| `<video src="..." />`                  | `video`                  | Custom Video element                        |
| `<toc />`                              | `toc`                    | Table of Contents                           |
| `<callout>...</callout>`               | `callout`                | Callout block                               |
| `<column_group>...</column_group>`     | `column_group`           | Multi-column layout container               |
| `<column width="50%">...</column>`     | `column`                 | Single column with optional width attribute |

## Appendix C: Components for Rendering

While `rules` handle MD ↔ Plate conversion, Plate uses React components to _render_ Plate nodes. Configure these in `createPlateEditor` via the `components` option or plugin `withComponent` method.

**Example:**

```tsx title="components/my-editor.tsx"
import { createPlateEditor, ParagraphPlugin, PlateLeaf } from 'platejs/react';
import { BoldPlugin } from '@platejs/basic-nodes/react';
import { CodeBlockPlugin } from '@platejs/code-block/react';
import { ParagraphElement } from '@/components/ui/paragraph-node'; // Example UI component
import { CodeBlockElement } from '@/components/ui/code-block-node'; // Example UI component

const editor = createPlateEditor({
  plugins: [
    ParagraphPlugin.withComponent(ParagraphElement),
    CodeBlockPlugin.withComponent(CodeBlockElement),
    BoldPlugin,
    /* ... */
  ],
});
```

Refer to [Plugin Components](/docs/plugin-components) for more on creating/registering components.

## Appendix D: `PlateMarkdown` Component (Read-Only Display)

For a `react-markdown`-like component for read-only display:

```tsx title="components/plate-markdown.tsx"
import React, { useEffect } from 'react';
import { Plate, PlateContent, usePlateEditor } from 'platejs/react';
import { MarkdownPlugin } from '@platejs/markdown';
// Import necessary Plate plugins for common Markdown features
import { HeadingPlugin } from '@platejs/basic-nodes/react';
// ... include other plugins like BlockquotePlugin, CodeBlockPlugin, ListPlugin, etc.
// ... and mark plugins like BoldPlugin, ItalicPlugin, etc.

export interface PlateMarkdownProps {
  children: string; // Markdown content
  remarkPlugins?: any[];
  components?: Record<string, React.ComponentType<any>>; // Plate component overrides
  className?: string;
}

export function PlateMarkdown({
  children,
  remarkPlugins = [],
  components = {},
  className,
}: PlateMarkdownProps) {
  const editor = usePlateEditor({
    plugins: [
      // Include all plugins needed to render your Markdown
      HeadingPlugin /* ... other plugins ... */,
      MarkdownPlugin.configure({ options: { remarkPlugins } }),
    ],
    components, // Pass through component overrides
  });

  useEffect(() => {
    editor.tf.reset(); // Clear previous content
    editor.tf.setValue(
      editor.getApi(MarkdownPlugin).markdown.deserialize(children)
    );
  }, [children, editor, remarkPlugins]); // Re-deserialize if markdown or plugins change

  return (
    <Plate editor={editor}>
      <PlateContent readOnly className={className} />
    </Plate>
  );
}

// Usage Example:
// const markdownString = "# Hello\nThis is *Markdown*.";
// <PlateMarkdown className="prose dark:prose-invert">
//   {markdownString}
// </PlateMarkdown>
```

<Callout type="info" title="Initial Value">
  This `PlateMarkdown` component provides a **read-only** view. For full
  editing, see the [Installation guides](/docs/installation).
</Callout>

## Security Considerations

`@platejs/markdown` prioritizes safety by converting Markdown to a structured Plate format, avoiding direct HTML rendering. However, security depends on:

- **Custom `rules`:** Ensure `deserialize` rules don't introduce unsafe data.
- **`remarkPlugins`:** Vet third-party remark plugins for potential security risks.
- **Raw HTML Processing:** Sanitize or convert raw HTML before passing Markdown to Plate. Treat untrusted Markdown as unsafe until your own pipeline has applied a strict whitelist.
- **Plugin Responsibility:** URL validation in `LinkPlugin` ([`isUrl`](/docs/link#linkplugin)) or `MediaEmbedPlugin` ([`parseMediaUrl`](/docs/media#parsemediaurl)) is crucial.

**Recommendation:** Treat untrusted Markdown input cautiously. Sanitize if allowing complex features or raw HTML.

## Related Links

- **[remark][github-remark]:** Markdown processor.
- **[unified][github-unified]:** Core processing engine.
- **[MDX][github-mdx]:** JSX in Markdown.
- **[react-markdown][github-react-markdown]:** Alternative React Markdown component.
- **[remark-slate-transformer][github-remark-slate-transformer]:** Initial mdast ↔ Plate conversion work by [inokawa](https://github.com/inokawa).

[commonmark-help]: https://commonmark.org/help/
[commonmark-spec]: https://spec.commonmark.org/
[gfm-spec]: https://github.github.com/gfm/
[github-awesome-remark]: https://github.com/remarkjs/awesome-remark
[github-mdast]: https://github.com/syntax-tree/mdast
[github-mdx]: https://mdxjs.com/
[github-react-markdown]: https://github.com/remarkjs/react-markdown
[github-remark-slate-transformer]: https://github.com/inokawa/remark-slate-transformer
[github-rehype-raw]: https://github.com/rehypejs/rehype-raw
[github-rehype-sanitize]: https://github.com/rehypejs/rehype-sanitize
[github-remark]: https://github.com/remarkjs/remark
[github-remark-gfm]: https://github.com/remarkjs/remark-gfm
[github-remark-parse]: https://github.com/remarkjs/remark/tree/main/packages/remark-parse
[github-remark-plugins]: https://github.com/remarkjs/remark/blob/main/doc/plugins.md#list-of-plugins
[github-remark-stringify]: https://github.com/remarkjs/remark/tree/main/packages/remark-stringify
[github-topic-remark-plugin]: https://github.com/topics/remark-plugin
[github-unified]: https://github.com/unifiedjs/unified


# Font

Source: https://platejs.org/docs/font

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Font
description: Provide extended formatting options for document content.
docs:
  - route: /docs/components/font-color-toolbar-button
    title: Font Color Toolbar Button
  - route: /docs/components/font-size-toolbar-button
    title: Font Size Toolbar Button
---

[font-demo registry content](https://platejs.org/r/font-demo)

<PackageInfo>

## Features

- Apply font styling to selected text including size, family, color, background color, and weight.
- Supports custom font families, sizes, colors, and weights.

## Plugins

- `FontBackgroundColorPlugin`: Control background color with `background-color` style
- `FontColorPlugin`: Control font color with `color` style
- `FontFamilyPlugin`: Change font family using inline elements with `font-family` style
- `FontSizePlugin`: Control font size with CSS class or `font-size` style
- `FontWeightPlugin`: Control font weight with `font-weight` style

</PackageInfo>

## Kit Usage

<Steps>

### Installation

The fastest way to add font styling functionality is with the `FontKit`, which includes pre-configured font plugins with their [Plate UI](/docs/installation/plate-ui) components.

[font-kit registry content](https://platejs.org/r/font-kit)

- Includes all font plugins (`FontColorPlugin`, `FontBackgroundColorPlugin`, `FontSizePlugin`, `FontFamilyPlugin`) with sensible defaults.

### Add Kit

Add the kit to your plugins:

```tsx
import { createPlateEditor } from 'platejs/react';
import { FontKit } from '@/components/editor/plugins/font-kit';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    ...FontKit,
  ],
});
```

</Steps>

## Manual Usage

<Steps>

### Installation

```bash
npm install @platejs/basic-styles
```

### Add Plugins

Include the font plugins in your Plate plugins array when creating the editor.

```tsx
import {
  FontBackgroundColorPlugin,
  FontColorPlugin,
  FontFamilyPlugin,
  FontSizePlugin,
} from '@platejs/basic-styles/react';
import { createPlateEditor } from 'platejs/react';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    FontColorPlugin,
    FontBackgroundColorPlugin,
    FontFamilyPlugin,
    FontSizePlugin,
  ],
});
```

### Configure Plugins

You can configure individual font plugins with custom options and target elements.

```tsx
import {
  FontColorPlugin,
  FontBackgroundColorPlugin,
  FontSizePlugin,
  FontFamilyPlugin,
} from '@platejs/basic-styles/react';
import { KEYS } from 'platejs';
import { createPlateEditor } from 'platejs/react';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    FontColorPlugin.configure({
      inject: {
        nodeProps: {
          defaultNodeValue: 'black',
        },
        targetPlugins: [KEYS.p],
      },
    }),
    FontSizePlugin.configure({
      inject: {
        targetPlugins: [KEYS.p],
      },
    }),
    FontBackgroundColorPlugin.configure({
      inject: {
        targetPlugins: [KEYS.p],
      },
    }),
    FontFamilyPlugin.configure({
      inject: {
        targetPlugins: [KEYS.p],
      },
    }),
  ],
});
```

- `inject.nodeProps.defaultNodeValue`: Sets the default font color value.
- `inject.targetPlugins`: Specifies which element types can receive font styling (affects HTML parsing).

### Add Toolbar Button

You can add [`FontColorToolbarButton`](/docs/components/font-color-toolbar-button) and [`FontSizeToolbarButton`](/docs/components/font-size-toolbar-button) to your [Toolbar](/docs/toolbar) to control font color and size.

</Steps>

## Plugins

### `FontBackgroundColorPlugin`

Plugin for font background color formatting. Applies `background-color` style to selected text.

### `FontColorPlugin`

Plugin for font color formatting. Applies `color` style to selected text.

### `FontFamilyPlugin`

Plugin for font family formatting. Applies `font-family` style to selected text.

### `FontSizePlugin`

Plugin for font size formatting. Applies `font-size` style to selected text.

### `FontWeightPlugin`

Plugin for font weight formatting. Applies `font-weight` style to selected text.

## Transforms

### `tf.backgroundColor.addMark`

Set the font background color mark on the selected text.

<API name="tf.backgroundColor.addMark">
<APIParameters>
  <APIItem name="value" type="string">
    The background color value to set (e.g., `'#ff0000'`, `'red'`).
  </APIItem>
</APIParameters>
</API>

### `tf.color.addMark`

Set the font color mark on the selected text.

<API name="tf.color.addMark">
<APIParameters>
  <APIItem name="value" type="string">
    The color value to set (e.g., `'#0000ff'`, `'blue'`).
  </APIItem>
</APIParameters>
</API>

### `tf.fontFamily.addMark`

Set the font family mark on the selected text.

<API name="tf.fontFamily.addMark">
<APIParameters>
  <APIItem name="value" type="string">
    The font family value to set (e.g., `'Arial'`, `'Times New Roman'`).
  </APIItem>
</APIParameters>
</API>

### `tf.fontSize.addMark`

Set the font size mark on the selected text.

<API name="tf.fontSize.addMark">
<APIParameters>
  <APIItem name="value" type="string">
    The font size value to set (e.g., `'16px'`, `'1.2em'`).
  </APIItem>
</APIParameters>
</API>

### `tf.fontWeight.addMark`

Set the font weight mark on the selected text.

<API name="tf.fontWeight.addMark">
<APIParameters>
  <APIItem name="value" type="string">
    The font weight value to set (e.g., `'bold'`, `'400'`, `'600'`).
  </APIItem>
</APIParameters>
</API>

## API

### `toUnitLess`

Convert a font size value to a unitless value.

<API name="toUnitLess">
<APIParameters>
  <APIItem name="fontSize" type="string">
    The font size value to convert.
  </APIItem>
</APIParameters>

<APIReturns type="string">
  The font size value without units.
</APIReturns>
</API>



# Indent

Source: https://platejs.org/docs/indent

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Indent
docs:
  - route: /docs/components/indent-toolbar-button
    title: Indent Toolbar Buttons
---

[indent-demo registry content](https://platejs.org/r/indent-demo)

<PackageInfo>

## Features

- Add indentation to block elements using Tab/Shift+Tab keyboard shortcuts.
- Apply consistent indentation with customizable offset and units.
- Injects an `indent` prop into targeted block elements.
- Support for maximum indentation depth control.

</PackageInfo>

## Kit Usage

<Steps>

### Installation

The fastest way to add indent functionality is with the `IndentKit`, which includes pre-configured `IndentPlugin` targeting paragraph, heading, blockquote, code block, and toggle elements.

[indent-kit registry content](https://platejs.org/r/indent-kit)

- Configures `Paragraph`, `Heading`, `Blockquote`, `CodeBlock`, and `Toggle` elements to support the `indent` property.
- Sets a custom offset of `24px` for indentation spacing.
- Provides Tab/Shift+Tab keyboard shortcuts for indenting and outdenting.

### Add Kit

Add the kit to your plugins:

```tsx
import { createPlateEditor } from 'platejs/react';
import { IndentKit } from '@/components/editor/plugins/indent-kit';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    ...IndentKit,
  ],
});
```

</Steps>

## Manual Usage

<Steps>

### Installation

```bash
npm install @platejs/indent
```

### Add Plugin

Include `IndentPlugin` in your Plate plugins array when creating the editor.

```tsx
import { IndentPlugin } from '@platejs/indent/react';
import { createPlateEditor } from 'platejs/react';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    IndentPlugin,
  ],
});
```

### Configure Plugin

You can configure the `IndentPlugin` to target specific elements and customize indentation behavior.

```tsx
import { IndentPlugin } from '@platejs/indent/react';
import { KEYS } from 'platejs';
import { createPlateEditor } from 'platejs/react';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    IndentPlugin.configure({
      inject: {
        nodeProps: {
          styleKey: 'marginLeft',
        },
        targetPlugins: [...KEYS.heading, KEYS.p, KEYS.blockquote],
      },
      options: {
        offset: 24,
        unit: 'px',
        indentMax: 10,
      },
    }),
  ],
});
```

- `inject.nodeProps.styleKey`: Maps the injected prop to the CSS `marginLeft` property.
- `inject.targetPlugins`: An array of plugin keys indicating which element types can be indented.
- `options.offset`: Indentation offset in pixels (default: `24`).
- `options.unit`: Unit for indentation values (default: `'px'`).
- `options.indentMax`: Maximum number of indentations allowed.

### Add Toolbar Button

You can add [`IndentToolbarButton`](/docs/components/indent-toolbar-button) to your [Toolbar](/docs/toolbar) to control indentation.

</Steps>

## Plugins

### `IndentPlugin`

Plugin for indenting block elements. It injects an `indent` prop into the elements specified by `inject.targetPlugins` and applies `marginLeft` styling.

<API name="IndentPlugin">
<APIOptions type="object">
  <APIItem name="inject.nodeProps.nodeKey" type="string" optional>
    The property name injected into target elements.
    - **Default:** `'indent'`
  </APIItem>
  <APIItem name="inject.nodeProps.styleKey" type="string" optional>
    CSS property name for styling.
    - **Default:** `'marginLeft'`
  </APIItem>
  <APIItem name="inject.targetPlugins" type="string[]" optional>
    Array of plugin keys to target for indent injection.
    - **Default:** `['p']`
  </APIItem>
  <APIItem name="options.offset" type="number" optional>
    Indentation offset used in `(offset * element.indent) + unit`.
    - **Default:** `24`
  </APIItem>
  <APIItem name="options.unit" type="string" optional>
    Indentation unit used in `(offset * element.indent) + unit`.
    - **Default:** `'px'`
  </APIItem>
  <APIItem name="options.indentMax" type="number" optional>
    Maximum number of indentations allowed.
  </APIItem>
</APIOptions>
</API>

## API

### `indent`

Indents the selected block(s) in the editor.

<API name="indent">
  <APIOptions type="SetIndentOptions" optional>
    Options for indenting blocks.
  </APIOptions>
</API>

### `outdent`

Decrease the indentation of the selected blocks.

<API name="outdent">
  <APIOptions type="SetIndentOptions" optional>
    Options for outdenting blocks.
  </APIOptions>
</API>

### `setIndent`

Add offset to the indentation of the selected blocks.

<API name="setIndent">
<APIOptions type="SetIndentOptions">
  <APIItem name="offset" type="number" optional>
    Indentation offset used in `(offset * element.indent) + unit`.
    - **Default:** `1`
  </APIItem>
  <APIItem name="getNodesOptions" type="EditorNodesOptions" optional>
    Options to get nodes to indent.
  </APIItem>
  <APIItem name="setNodesProps" type="object" optional>
    Additional props to set on nodes to indent.
  </APIItem>
  <APIItem name="unsetNodesProps" type="string[]" optional>
    Additional props to unset on nodes to indent.
    - **Default:** `[]`
  </APIItem>
</APIOptions>
</API>

## Types

### `SetIndentOptions`

Used to provide options for setting the indentation of a block of text.

<API name="SetIndentOptions">
<APIOptions>
  <APIItem name="offset" type="number">
    Change in indentation (1 to indent, -1 to outdent).
    - **Default:** `1`
  </APIItem>
  <APIItem name="getNodesOptions" type="EditorNodesOptions<V>">
    Additional `getNodes` options.
  </APIItem>
  <APIItem name="setNodesProps" type="object">
    Additional `setNodes` options.
  </APIItem>
  <APIItem name="unsetNodesProps" type="string[]">
    Properties to unset when indentation is 0.
  </APIItem>
</APIOptions>
</API>

## Hooks

### `useIndentButton`

A behavior hook for the indent button component.

<API name="useIndentButton">
<APIReturns type="object">
  <APIItem name="props" type="object">
    Props for the indent button.
    <APISubList>
      <APISubListItem parent="props" name="onClick" type="function">
        Callback to handle click event. Indents selected content and focuses editor.
      </APISubListItem>
    </APISubList>
  </APIItem>
</APIReturns>
</API>

### `useOutdentButton`

A behavior hook for the outdent button component.

<API name="useOutdentButton">
<APIReturns type="object">
  <APIItem name="props" type="object">
    Props for the outdent button.
    <APISubList>
      <APISubListItem parent="props" name="onClick" type="function">
        Callback to handle click event. Outdents selected content and focuses editor.
      </APISubListItem>
    </APISubList>
  </APIItem>
</APIReturns>
</API>

# Line Height

Source: https://platejs.org/docs/line-height

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Line Height
description: Set block line height.
docs:
  - route: /docs/examples/line-height
    title: Line Height Demo
  - route: /docs/components/line-height-toolbar-button
    title: Line Height Toolbar Button
---

`LineHeightPlugin` stores line height on blocks with a `lineHeight` property. Setting the default value removes the property, so saved values only carry overrides.

[line-height-demo registry content](https://platejs.org/r/line-height-demo)

<PackageInfo>

## Features

- Block-level `lineHeight` storage.
- HTML `line-height` style deserialization.
- Default-value cleanup.
- Configurable target block types.
- Shared `setLineHeight` transform.
- Registry dropdown toolbar driven by valid node values.

</PackageInfo>

## Kit Usage

<Steps>

### Add the Kit

Use `LineHeightKit` for the Plate UI setup. It targets paragraphs and all heading levels, with valid values `1`, `1.2`, `1.5`, `2`, and `3`.

[line-height-kit registry content](https://platejs.org/r/line-height-kit)

```tsx
import { createPlateEditor } from 'platejs/react';

import { LineHeightKit } from '@/components/editor/plugins/line-height-kit';

export const editor = createPlateEditor({
  plugins: [...LineHeightKit],
});
```

### Add the Toolbar Control

`LineHeightToolbarButton` reads `defaultNodeValue` and `validNodeValues` from the plugin inject props.

```tsx
import { LineHeightToolbarButton } from '@/components/ui/line-height-toolbar-button';

export function LineHeightControls() {
  return <LineHeightToolbarButton />;
}
```

</Steps>

## Manual Usage

<Steps>

### Install Package

```bash
npm install @platejs/basic-styles
```

### Add the Plugin

Configure target block types and the values your UI should expose.

```tsx
import { LineHeightPlugin } from '@platejs/basic-styles/react';
import { KEYS } from 'platejs';
import { createPlateEditor } from 'platejs/react';

export const editor = createPlateEditor({
  plugins: [
    LineHeightPlugin.configure({
      inject: {
        nodeProps: {
          defaultNodeValue: 1.5,
          validNodeValues: [1, 1.2, 1.5, 2, 3],
        },
        targetPlugins: [...KEYS.heading, KEYS.p],
      },
    }),
  ],
});
```

### Set Line Height

Use the bound transform or the headless utility.

```tsx
import { setLineHeight } from '@platejs/basic-styles';

editor.tf.lineHeight.setNodes(2);

setLineHeight(editor, 1.5, { at: [] });
```

</Steps>

## Ownership

| Surface | Owner | What It Does |
|---------|-------|--------------|
| `BaseLineHeightPlugin` | `@platejs/basic-styles` | Headless plugin that stores `lineHeight`, injects block props, and parses HTML line-height styles. |
| `LineHeightPlugin` | `@platejs/basic-styles/react` | React wrapper around `BaseLineHeightPlugin`. |
| `setLineHeight` | `@platejs/basic-styles` | Sets or clears `lineHeight` on matching blocks. |
| `tf.lineHeight.setNodes` | `@platejs/basic-styles` | Bound transform exposed by the plugin. |
| `BaseLineHeightKit` | Registry kit | Static/headless setup for paragraphs and headings. |
| `LineHeightKit` | Registry kit | React setup plus toolbar dependency. |
| `LineHeightToolbarButton` | Registry UI | Dropdown that writes values through `lineHeight.setNodes`. |

The package owns line-height storage and parsing. The registry owns the dropdown UI and allowed value list.

## Behavior

| Behavior | Source |
|----------|--------|
| Plugin key | `KEYS.lineHeight` |
| Stored property | `lineHeight` |
| Default target plugins | `[KEYS.p]` |
| Registry target plugins | `[...KEYS.heading, KEYS.p]` |
| Default node value | `1.5` |
| Registry valid values | `[1, 1.2, 1.5, 2, 3]` |
| HTML parser | Reads `element.style.lineHeight`. |
| Setting a custom value | Sets `{ lineHeight: value }` on matching blocks. |
| Setting the default value | Unsets `lineHeight` on matching blocks. |
| Non-target blocks | Are ignored by `setLineHeight`. |

## HTML

The plugin injects an HTML deserializer into each target plugin. When pasted HTML contains an inline `line-height` style on a target block, Plate stores the value on that block.

```html
<p style="line-height: 2">Readable spacing</p>
```

## API Reference

| API | Package | Use |
|-----|---------|-----|
| `LineHeightPlugin` | `@platejs/basic-styles/react` | React line-height plugin. |
| `BaseLineHeightPlugin` | `@platejs/basic-styles` | Headless line-height plugin. |
| `editor.tf.lineHeight.setNodes(value, options?)` | `@platejs/basic-styles` | Sets or clears line height on matching blocks. |
| `setLineHeight(editor, value, options?)` | `@platejs/basic-styles` | Headless transform behind the bound API. |

## Options

| Option | Surface | Use |
|--------|---------|-----|
| `inject.targetPlugins` | `LineHeightPlugin` | Block types that can keep `lineHeight`. |
| `inject.nodeProps.nodeKey` | `BaseLineHeightPlugin` | Stored block property; defaults to `lineHeight`. |
| `inject.nodeProps.defaultNodeValue` | `BaseLineHeightPlugin` | Value that clears the stored property when selected. |
| `inject.nodeProps.validNodeValues` | Registry toolbar | Dropdown values used by `LineHeightToolbarButton`. |
| `SetNodesOptions` | `setLineHeight` | Slate node update options passed to `setNodes` or `unsetNodes`. |


# List

Source: https://platejs.org/docs/list

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: List
docs:
  - route: /docs/components/list-toolbar-button
    title: List Toolbar Button
---

[list-demo registry content](https://platejs.org/r/list-demo)

<PackageInfo>

## Features

- **Flexible Block Indentation**: Transform any block type (paragraphs, headings, etc.) into list items through indentation.
- **Simplified Structure**: Flat DOM structure where each indented block is independent, unlike [List Classic plugin](/docs/list-classic).
- **List Types**: Support for bulleted lists (unordered) and numbered lists (ordered).
- **Markdown Shortcuts**: Register the shipped list input rules to create lists from markdown triggers like `-`, `*`, `1.`, and `[]`.

For more information about the underlying indentation system, see the [Indent plugin](/docs/indent).

</PackageInfo>

## Kit Usage

<Steps>

### Installation

The fastest way to add list functionality is with the `ListKit`, which includes pre-configured `ListPlugin`, the shipped list input rules, and the required [Indent plugin](/docs/indent) targeting paragraph, heading, blockquote, code block, and toggle elements.

[list-kit registry content](https://platejs.org/r/list-kit)

- [`BlockList`](/docs/components/block-list): Renders list wrapper elements with support for todo lists.
- Includes [`IndentKit`](/docs/indent) for the underlying indentation system.
- Configures `Paragraph`, `Heading`, `Blockquote`, `CodeBlock`, and `Toggle` elements to support list functionality.

### Add Kit

Add the kit to your plugins:

```tsx
import { createPlateEditor } from 'platejs/react';
import { ListKit } from '@/components/editor/plugins/list-kit';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    ...ListKit,
  ],
});
```

### Add Toolbar Button

You can add [`ListToolbarButton`](/docs/components/list-toolbar-button) to your [Toolbar](/docs/toolbar) to create and manage lists.

</Steps>

## Turn Into Toolbar Button

You can add these items to the [Turn Into Toolbar Button](/docs/toolbar#turn-into-toolbar-button) to convert blocks into lists:

```tsx
{
  icon: <ListIcon />,
  label: 'Bulleted list',
  value: KEYS.ul,
}
```

```tsx
{
  icon: <ListOrderedIcon />,
  label: 'Numbered list',
  value: KEYS.ol,
}
```

```tsx
{
  icon: <SquareIcon />,
  label: 'To-do list',
  value: KEYS.listTodo,
}
```

## Manual Usage

<Steps>

### Installation

```bash
npm install @platejs/list @platejs/indent
```

### Add Plugins

Include both `IndentPlugin` and `ListPlugin` in your Plate plugins array when creating the editor. The List plugin depends on the Indent plugin.

```tsx
import { IndentPlugin } from '@platejs/indent/react';
import { ListPlugin } from '@platejs/list/react';
import { createPlateEditor } from 'platejs/react';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    IndentPlugin,
    ListPlugin,
  ],
});
```

### Configure Plugins

You can configure both plugins to target specific elements, customize list behavior, and register the shipped markdown rules.

```tsx
import { IndentPlugin } from '@platejs/indent/react';
import {
  BulletedListRules,
  OrderedListRules,
  TaskListRules,
} from '@platejs/list';
import { ListPlugin } from '@platejs/list/react';
import { KEYS } from 'platejs';
import { createPlateEditor } from 'platejs/react';
import { BlockList } from '@/components/ui/block-list';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    IndentPlugin.configure({
      inject: {
        targetPlugins: [...KEYS.heading, KEYS.p, KEYS.blockquote, KEYS.codeBlock],
      },
    }),
    ListPlugin.configure({
      inputRules: [
        BulletedListRules.markdown({ variant: '-' }),
        OrderedListRules.markdown({ variant: '.' }),
        TaskListRules.markdown({ checked: false }),
      ],
      inject: {
        targetPlugins: [...KEYS.heading, KEYS.p, KEYS.blockquote, KEYS.codeBlock],
      },
      render: {
        belowNodes: BlockList,
      },
    }),
  ],
});
```

- `inject.targetPlugins`: An array of plugin keys indicating which element types can become list items.
- `inputRules`: Registers the feature-owned markdown shortcuts for bulleted, ordered, and task lists.
- `render.belowNodes`: Assigns [`BlockList`](/docs/components/block-list) to render list wrapper elements.

For the runtime model and other variants, see [Plugin Input Rules](/docs/plugin-input-rules).

</Steps>

## Plugins

### `ListPlugin`

Plugin for creating and managing lists. It works with the [Indent plugin](/docs/indent) to provide flexible list functionality where any block can be transformed into a list item through indentation.

<API name="ListPlugin">
<APIOptions>
  <APIItem name="getSiblingListOptions" type="GetSiblingListOptions<TElement>" optional>
    Function to determine indent list options for sibling elements.
  </APIItem>
  <APIItem name="getListStyleType" type="(element: HTMLElement) => ListStyleType" optional>
    Function mapping HTML elements to list style types.
  </APIItem>
</APIOptions>
</API>

## API

### `getNextList`

Gets the next sibling entry with an indent list.

<API name="getNextList">
<APIParameters>
  <APIItem name="entry" type="ElementEntryOf">
    Entry of the current element.
  </APIItem>
  <APIItem name="options" type="Partial<GetSiblingListOptions>" optional>
    Options for getting next indent list.
  </APIItem>
</APIParameters>

<APIReturns type="NodeEntry | undefined">
  Entry of the next sibling with an indent list, or `undefined` if not found.
</APIReturns>
</API>

### `getPreviousList`

Gets the previous sibling entry with an indent list.

<API name="getPreviousList">
<APIParameters>
  <APIItem name="entry" type="ElementEntryOf">
    Entry of the current element.
  </APIItem>
  <APIItem name="options" type="Partial<GetSiblingListOptions>" optional>
    Options for getting previous indent list.
  </APIItem>
</APIParameters>

<APIReturns type="NodeEntry | undefined">
  Entry of the previous sibling with an indent list, or `undefined` if not found.
</APIReturns>
</API>

### `indentList`

Increases the indentation of the selected blocks.

<API name="indentList">
<APIOptions type="ListOptions">
  <APIItem name="listStyleType" type="ListStyleType | string" optional>
    List style type to use.
    - **Default:** `ListStyleType.Disc`
  </APIItem>
</APIOptions>
</API>

### `outdentList`

Decreases the indentation of the selected blocks.

<API name="outdentList">
<APIOptions type="ListOptions">
  <APIItem name="listStyleType" type="ListStyleType | string" optional>
    List style type to use.
    - **Default:** `ListStyleType.Disc`
  </APIItem>
</APIOptions>
</API>

### `someList`

Checks if some of the selected blocks have a specific list style type.

<API name="someList">
<APIParameters>
  <APIItem name="type" type="string | string[]">
    List style type to check.
  </APIItem>
</APIParameters>
</API>

### `toggleList`

Toggles the indent list.

<API name="toggleList">
<APIOptions type="ListOptions">
  <APIItem name="listStyleType" type="ListStyleType | string" optional>
    List style type to use.
  </APIItem>

  <APIItem name="listRestart" type="number" optional>
    Override the number of the list item.
  </APIItem>

  <APIItem name="listRestartPolite" type="number" optional>
    Override the number of the list item, only taking effect if the list item is the first in the list.
  </APIItem>
</APIOptions>
</API>

## Types

### `GetSiblingListOptions`

Used to provide options for getting the sibling indent list in a block of text.

<API name="GetSiblingListOptions">
<APIOptions>
  <APIItem name="getPreviousEntry" type="function">
    This function is used to get the previous sibling entry from a given entry.
  </APIItem>
  <APIItem name="getNextEntry" type="function">
    This function is used to get the next sibling entry from a given entry.
  </APIItem>
  <APIItem name="query" type="function">
    This function is used to validate a sibling node during the lookup process.
    If it returns false, the next sibling is checked.
  </APIItem>
  <APIItem name="eqIndent" type="boolean">
    Indicates whether to break the lookup when the sibling node has an indent
    level equal to the current node. If true, the lookup stops when a sibling
    node with the same indent level is found.
  </APIItem>
  <APIItem name="breakQuery" type="(node: TNode) => boolean | undefined">
    A function that takes a `TNode` and returns a boolean value or undefined.
    This function is used to specify a condition under which the lookup process
    should be stopped.
  </APIItem>
  <APIItem name="breakOnLowerIndent" type="boolean">
    Indicates whether to break the lookup when a sibling node with a lower
    indent level is found. If true, the lookup stops when a sibling node with a
    lower indent level is found.
  </APIItem>
  <APIItem name="breakOnEqIndentNeqListStyleType" type="boolean">
    Indicates whether to break the lookup when a sibling node with the same
    indent level but a different list style type is found. If true, the lookup
    stops when such a sibling node is found.
  </APIItem>
</APIOptions>
</API>

## Hooks

### `useListToolbarButton`

A behavior hook for the indent list toolbar button.

<API name="useListToolbarButton">
<APIState>
  <APIItem name="nodeType" type="string">
    The list style type.
  </APIItem>
  <APIItem name="pressed" type="boolean">
    Whether the button is pressed.
  </APIItem>
</APIState>

<APIReturns type="object">
  <APIItem name="props" type="object">
    Props for the toolbar button.
     <APISubList>
      <APISubListItem parent="props" name="pressed" type="boolean">
        Whether the button is pressed.
      </APISubListItem>
      <APISubListItem parent="props" name="onClick" type="function">
        Callback to handle the click event. Toggles the indent list of the specified node type and focuses the editor.
      </APISubListItem>
    </APISubList>
  </APIItem>
</APIReturns>
</API>


# Text Align

Source: https://platejs.org/docs/text-align

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Text Align
description: Align block content.
docs:
  - route: /docs/examples/align
    title: Align Demo
  - route: /docs/components/align-toolbar-button
    title: Align Toolbar Button
---

`TextAlignPlugin` stores block alignment in an `align` property and renders it as CSS `text-align`. Setting the default `start` value removes the property from matching blocks.

[align-demo registry content](https://platejs.org/r/align-demo)

<PackageInfo>

## Features

- Block-level text alignment.
- `start`, `left`, `center`, `right`, `end`, and `justify` values.
- HTML `text-align` style deserialization.
- Default-value cleanup.
- Configurable target block types.
- Registry dropdown toolbar for common alignments.

</PackageInfo>

## Kit Usage

<Steps>

### Add the Kit

Use `AlignKit` for the Plate UI setup. It targets headings, paragraphs, images, and media embeds.

[align-kit registry content](https://platejs.org/r/align-kit)

```tsx
import { createPlateEditor } from 'platejs/react';

import { AlignKit } from '@/components/editor/plugins/align-kit';

export const editor = createPlateEditor({
  plugins: [...AlignKit],
});
```

### Add the Toolbar Control

`AlignToolbarButton` shows left, center, right, and justify controls.

```tsx
import { AlignToolbarButton } from '@/components/ui/align-toolbar-button';

export function AlignControls() {
  return <AlignToolbarButton />;
}
```

</Steps>

## Manual Usage

<Steps>

### Install Package

```bash
npm install @platejs/basic-styles
```

### Add the Plugin

Configure the blocks that can store alignment.

```tsx
import { TextAlignPlugin } from '@platejs/basic-styles/react';
import { KEYS } from 'platejs';
import { createPlateEditor } from 'platejs/react';

export const editor = createPlateEditor({
  plugins: [
    TextAlignPlugin.configure({
      inject: {
        nodeProps: {
          defaultNodeValue: 'start',
          nodeKey: 'align',
          styleKey: 'textAlign',
          validNodeValues: [
            'start',
            'left',
            'center',
            'right',
            'end',
            'justify',
          ],
        },
        targetPlugins: [...KEYS.heading, KEYS.p],
      },
    }),
  ],
});
```

### Set Alignment

Use the bound transform or the headless utility.

```tsx
import { setAlign } from '@platejs/basic-styles';

editor.tf.textAlign.setNodes('center');

setAlign(editor, 'start', { at: [] });
```

</Steps>

## Ownership

| Surface | Owner | What It Does |
|---------|-------|--------------|
| `BaseTextAlignPlugin` | `@platejs/basic-styles` | Headless plugin that stores alignment, injects block props, and parses HTML text-align styles. |
| `TextAlignPlugin` | `@platejs/basic-styles/react` | React wrapper around `BaseTextAlignPlugin`. |
| `setAlign` | `@platejs/basic-styles` | Sets or clears alignment on matching blocks. |
| `tf.textAlign.setNodes` | `@platejs/basic-styles` | Bound transform exposed by the plugin. |
| `BaseAlignKit` | Registry kit | Static/headless setup for headings, paragraphs, images, and media embeds. |
| `AlignKit` | Registry kit | React setup plus toolbar dependency. |
| `AlignToolbarButton` | Registry UI | Dropdown that writes alignment through `textAlign.setNodes`. |

The package owns alignment storage and parsing. The registry owns the dropdown UI.

## Behavior

| Behavior | Source |
|----------|--------|
| Plugin key | `KEYS.textAlign` |
| Stored property | `align` |
| Rendered CSS style | `textAlign` |
| Default target plugins | `[KEYS.p]` |
| Registry target plugins | `[...KEYS.heading, KEYS.p, KEYS.img, KEYS.mediaEmbed]` |
| Default value | `start` |
| Valid values | `start`, `left`, `center`, `right`, `end`, `justify` |
| HTML parser | Reads `element.style.textAlign`. |
| Setting a custom value | Sets `{ align: value }` on matching blocks. |
| Setting `start` | Unsets the stored alignment property. |
| Non-target blocks | Are ignored by `setAlign`. |

## HTML

The plugin injects an HTML deserializer into each target plugin. Pasted HTML with a `text-align` style becomes an `align` prop on matching blocks.

```html
<p style="text-align: center">Centered text</p>
```

## API Reference

| API | Package | Use |
|-----|---------|-----|
| `TextAlignPlugin` | `@platejs/basic-styles/react` | React alignment plugin. |
| `BaseTextAlignPlugin` | `@platejs/basic-styles` | Headless alignment plugin. |
| `editor.tf.textAlign.setNodes(value, options?)` | `@platejs/basic-styles` | Sets or clears alignment on matching blocks. |
| `setAlign(editor, value, options?)` | `@platejs/basic-styles` | Headless transform behind the bound API. |

## Options

| Option | Surface | Use |
|--------|---------|-----|
| `inject.targetPlugins` | `TextAlignPlugin` | Block types that can keep `align`. |
| `inject.nodeProps.nodeKey` | `TextAlignPlugin` | Stored block property; registry kits use `align`. |
| `inject.nodeProps.defaultNodeValue` | `TextAlignPlugin` | Value that clears the stored property when selected. |
| `inject.nodeProps.styleKey` | `TextAlignPlugin` | CSS property used for rendering. |
| `inject.nodeProps.validNodeValues` | Registry toolbar | Values exposed to alignment UI. |
| `SetNodesOptions` | `setAlign` | Slate node update options passed to `setNodes` or `unsetNodes`. |


# Plate Components

Source: https://platejs.org/docs/api/core/plate-components

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Plate Components
description: API reference for Plate React components.
---

Plate components connect a `PlateEditor` to React rendering. Use `Plate` and `PlateContent` for editable editors, `PlateView` for read-only static views, and the node primitives when writing custom plugin components.

## Editable Editor

`Plate` owns the editor store. `PlateContent` renders the editable surface under that store.

```tsx title="components/editor.tsx"
import { Plate, PlateContent, usePlateEditor } from 'platejs/react';

export function Editor() {
  const editor = usePlateEditor({
    value: [
      {
        children: [{ text: 'Start writing.' }],
        type: 'p',
      },
    ],
  });

  return (
    <Plate editor={editor}>
      <PlateContent placeholder="Write..." />
    </Plate>
  );
}
```

<Callout type="warning" title="Provider required">
  `PlateContent` must render below `Plate`. Hooks such as `useEditorRef`,
  `useEditorReadOnly`, and `usePlateStore` throw when there is no `Plate` or
  `PlateController` above them.
</Callout>

## Read-Only View

Use `PlateView` with a static editor when you need rendered content and Plate copy behavior without an editable surface.

```tsx title="components/read-only-editor.tsx"
import { PlateView, usePlateViewEditor } from 'platejs/react';

const value = [
  {
    children: [{ text: 'Published content.' }],
    type: 'p',
  },
];

export function ReadOnlyEditor() {
  const editor = usePlateViewEditor({ value });

  if (!editor) return null;

  return <PlateView editor={editor} />;
}
```

`PlateView` wraps `PlateStatic`. Its default `onCopy` writes Plate fragment data to the clipboard, unless you pass your own `onCopy` prop.

## Component Map

| Component | Use For |
|-----------|---------|
| `Plate` | Store provider for one editor instance. |
| `PlateContent` | Editable Slate surface with plugin handlers, decorators, renderers, hotkeys, and editor effects. |
| `PlateView` | Static read-only rendering with Plate fragment copy support. |
| `PlateContainer` | Editor container `div` plus `beforeContainer` and `afterContainer` plugin slots. |
| `PlateSlate` | Slate provider wrapper used by `PlateContent`; also applies `aboveSlate` plugin wrappers. |
| `PlateElement` | Default element renderer for block and inline elements. |
| `PlateLeaf` | Default decorated text-leaf renderer. |
| `PlateText` | Default text-node renderer for non-decoration leaf rendering. |
| `ContentVisibilityChunk` | Default chunk renderer when chunking uses `content-visibility: auto`. |
| `PlateTest` | Test helper that creates or wraps an editor and renders `PlateContent` with test attributes. |

## Render Pipeline

`PlateContent` builds the editable props with `useEditableProps`. That pipeline combines store-level renderers, `PlateContent` render props, plugin decorators, plugin DOM handlers, and chunking.

| Stage | Source |
|-------|--------|
| Slate provider | `PlateSlate` uses `editor.children`, `editor.meta.key`, and store callbacks. |
| Editable props | `useEditableProps` pipes decorators, DOM handlers, `renderChunk`, `renderElement`, `renderLeaf`, and `renderText`. |
| Plugin slots | `beforeEditable`, `aboveEditable`, and `afterEditable` wrap or sit around the editable surface. |
| Effects | `EditorMethodsEffect`, `EditorHotkeysEffect`, `EditorRefEffect`, and `PlateControllerEffect` run inside `PlateContent`. |
| Read-only state | `disabled` forces read-only; `readOnly` syncs back into the Plate store. |

## Node Primitives

Use `PlateElement`, `PlateLeaf`, and `PlateText` inside plugin components. They merge Slate attributes with your `className`, `style`, and `ref`.

```tsx title="components/paragraph-element.tsx"
import { PlateElement, type PlateElementProps } from 'platejs/react';

export function ParagraphElement(props: PlateElementProps) {
  return <PlateElement as="p" className="leading-7" {...props} />;
}
```

| Primitive | Behavior |
|-----------|----------|
| `PlateElement` | Adds `data-slate-node="element"`, preserves inline metadata, sets `data-block-id` for mounted block elements with an `id`, and adds directional-affinity spacers when needed. |
| `PlateLeaf` | Renders a text leaf and adds hard-affinity spacers when needed. |
| `PlateText` | Renders a text node without leaf-decoration matching. |
| `useNodeAttributes` | Merges Slate attributes, refs, class names, and styles for node primitives. |

## API Reference

### `Plate`

Root provider for one editor instance.

<API name="Plate">
<APIProps>
  <APIItem name="editor" type="PlateEditor | null">
    Editor instance. When `null`, `Plate` renders nothing.
  </APIItem>
  <APIItem name="children" type="React.ReactNode">
    React children that can read the Plate store.
  </APIItem>
  <APIItem name="decorate" type="({ editor, entry }) => TRange[]" optional>
    Store-level decorate function used by `PlateContent`.
  </APIItem>
  <APIItem name="readOnly" type="boolean" optional>
    Store-level read-only state. Defaults to `editor.dom.readOnly`.
  </APIItem>
  <APIItem name="primary" type="boolean" optional>
    Registers the editor as a primary editor for `PlateController`.
  </APIItem>
  <APIItem name="renderElement" type="EditableProps['renderElement']" optional>
    Fallback element renderer stored on the Plate store.
  </APIItem>
  <APIItem name="renderLeaf" type="EditableProps['renderLeaf']" optional>
    Fallback leaf renderer stored on the Plate store.
  </APIItem>
  <APIItem name="onChange" type="({ editor, value }) => void" optional>
    Runs after Slate change handling when plugin `onChange` handlers do not handle the event.
  </APIItem>
  <APIItem name="onValueChange" type="({ editor, value }) => void" optional>
    Runs when Slate reports a value change.
  </APIItem>
  <APIItem name="onSelectionChange" type="({ editor, selection }) => void" optional>
    Runs when Slate reports a selection change.
  </APIItem>
  <APIItem name="onNodeChange" type="({ editor, node, operation, prevNode }) => void" optional>
    Stored on `SlateExtensionPlugin` by `PlateContent` and called for node operations.
  </APIItem>
  <APIItem name="onTextChange" type="({ editor, node, operation, prevText, text }) => void" optional>
    Stored on `SlateExtensionPlugin` by `PlateContent` and called for text operations.
  </APIItem>
  <APIItem name="suppressInstanceWarning" type="boolean" optional>
    Suppresses the multiple-instance warning from `usePlateInstancesWarn`.
  </APIItem>
</APIProps>
</API>

### `PlateContent`

Editable surface for a `Plate` editor.

<API name="PlateContent">
<APIProps>
  <APIItem name="id" type="string" optional>
    Editor scope used by `useEditorRef(id)` and `usePlateStore(id)`.
  </APIItem>
  <APIItem name="autoFocusOnEditable" type="boolean" optional>
    Focuses the editor at the end when `readOnly` changes from `true` to `false`.
  </APIItem>
  <APIItem name="disabled" type="boolean" optional>
    Forces read-only state and sets `aria-disabled`.
  </APIItem>
  <APIItem name="readOnly" type="boolean" optional>
    Overrides the store read-only value and syncs it back to the store.
  </APIItem>
  <APIItem name="decorate" type="({ editor, entry }) => TRange[]" optional>
    Editable-level decorate function. Store-level `decorate` wins when present.
  </APIItem>
  <APIItem name="renderEditable" type="(editable: React.ReactElement) => React.ReactNode" optional>
    Wraps or replaces the generated `Editable` element.
  </APIItem>
  <APIItem name="renderChunk" type="RenderChunkFn" optional>
    Custom chunk renderer. Defaults to `ContentVisibilityChunk` when chunking enables `contentVisibilityAuto`.
  </APIItem>
  <APIItem name="renderElement" type="RenderElementFn" optional>
    Fallback element renderer after plugin renderers.
  </APIItem>
  <APIItem name="renderLeaf" type="RenderLeafFn" optional>
    Fallback leaf renderer after plugin leaf renderers.
  </APIItem>
  <APIItem name="renderText" type="RenderTextFn" optional>
    Fallback text renderer after non-decoration text renderers.
  </APIItem>
  <APIItem name="renderPlaceholder" type="EditableProps['renderPlaceholder']" optional>
    Placeholder renderer passed to Slate `Editable`.
  </APIItem>
  <APIItem name="placeholder" type="string" optional>
    Placeholder text passed to Slate `Editable`.
  </APIItem>
  <APIItem name="scrollSelectionIntoView" type="(editor, domRange) => void" optional>
    Slate selection scrolling hook.
  </APIItem>
  <APIItem name="onDOMBeforeInput" type="(event: InputEvent) => void" optional>
    DOM before-input handler passed through the plugin handler pipeline.
  </APIItem>
  <APIItem name="onKeyDown" type="(event: React.KeyboardEvent) => void" optional>
    Keyboard handler passed through the plugin handler pipeline.
  </APIItem>
  <APIItem name="as" type="React.ElementType" optional>
    Element type passed to Slate `Editable`.
  </APIItem>
  <APIItem name="disableDefaultStyles" type="boolean" optional>
    Passed to Slate `Editable`.
  </APIItem>
  <APIItem name="role" type="string" optional>
    ARIA role passed to Slate `Editable`.
  </APIItem>
  <APIItem name="style" type="React.CSSProperties" optional>
    Style object passed to Slate `Editable`.
  </APIItem>
</APIProps>
</API>

`PlateContent` also accepts the DOM handler props listed in `DOMHandlers`, including clipboard, composition, focus, keyboard, pointer, mouse, drag, touch, media, and form handlers.

### `PlateView`

Read-only static renderer with Plate copy support.

<API name="PlateView">
<APIProps>
  <APIItem name="editor" type="SlateEditor">
    Static editor instance.
  </APIItem>
  <APIItem name="value" type="Value" optional>
    Controlled value alias. When present, `PlateStatic` assigns it to `editor.children`.
  </APIItem>
  <APIItem name="onCopy" type="React.ClipboardEventHandler<HTMLDivElement>" optional>
    Overrides the default Plate fragment copy handler.
  </APIItem>
  <APIItem name="className" type="string" optional>
    Merged with the `slate-editor` class by `PlateStatic`.
  </APIItem>
  <APIItem name="style" type="React.CSSProperties" optional>
    Style object passed to the static root `div`.
  </APIItem>
</APIProps>
</API>

### `PlateContainer`

Container `div` with plugin container slots.

<API name="PlateContainer">
<APIProps>
  <APIItem name="children" type="React.ReactNode" optional>
    Content rendered inside the container.
  </APIItem>
  <APIItem name="...props" type="React.HTMLAttributes<HTMLDivElement>" optional>
    HTML props passed to the container `div` and container slot components.
  </APIItem>
</APIProps>
</API>

### Render Primitives

| API | Default Element | Notes |
|-----|-----------------|-------|
| `PlateElement` | `div` | Accepts `as`, `attributes`, `className`, `style`, `ref`, `element`, `path`, `editor`, `plugin`, and `insetProp`. |
| `PlateLeaf` | `span` | Accepts `as`, `attributes`, `className`, `style`, `ref`, `leaf`, `text`, `editor`, `plugin`, and `inset`. |
| `PlateText` | `span` | Accepts `as`, `attributes`, `className`, `style`, `ref`, `text`, `editor`, and `plugin`. |
| `ContentVisibilityChunk` | `div` | Wraps children only when `lowest` is true. |
| `withHOC` | `React.forwardRef` | Wraps one ref-capable component with another ref-capable component. |


# Plate Controller

Source: https://platejs.org/docs/api/core/plate-controller

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Plate Controller
description: API reference for PlateController.
---

`PlateController` lets UI outside a single `<Plate>` subtree read the active editor store. Use it for shared toolbars, side panels, inspectors, and multi-editor shells.

## Quick Use

Wrap the shared UI and all editors in `PlateController`. `PlateContent` registers each mounted editor store through `PlateControllerEffect`.

```tsx title="components/editor-shell.tsx" showLineNumbers
import {
  Plate,
  PlateContent,
  PlateController,
  usePlateEditor,
} from 'platejs/react';

export function EditorShell() {
  return (
    <PlateController>
      <ActiveEditorLabel />
      <MainEditor />
      <SecondaryEditor />
    </PlateController>
  );
}

function MainEditor() {
  const editor = usePlateEditor({ id: 'main' });

  return (
    <Plate editor={editor}>
      <PlateContent />
    </Plate>
  );
}

function SecondaryEditor() {
  const editor = usePlateEditor({ id: 'secondary' });

  return (
    <Plate editor={editor} primary={false}>
      <PlateContent />
    </Plate>
  );
}
```

`primary` belongs on `Plate`, not on `createPlateEditor` or `usePlateEditor`.

## Active Editor Lookup

Hooks such as `useEditorRef()` and `useEditorMounted()` normally read the nearest `Plate` store. Inside `PlateController`, the same hooks can resolve a store outside a specific editor tree.

| Lookup | Behavior |
|--------|----------|
| `useEditorRef('main')` | Resolves the store registered for `main`. |
| `useEditorRef()` | Resolves the active editor store, then the first mounted primary editor store. |
| Missing store with controller | Returns the fallback store, so `useEditorRef()` returns a fallback editor. |
| Missing store without controller | Throws `Plate hooks must be used inside a Plate or PlateController`. |

Controller lookup order without an explicit ID:

1. `activeId`
2. each ID in `primaryEditorIds`
3. fallback store when no store is available

## Fallback Editors

The fallback editor exists so read-only UI can render while no editor is active. It is not safe for transforms.

```tsx title="components/active-editor-label.tsx"
import { useEditorMounted, useEditorRef } from 'platejs/react';

export function ActiveEditorLabel() {
  const editor = useEditorRef();
  const mounted = useEditorMounted();

  if (!mounted || editor.meta.isFallback) {
    return <p>No editor selected.</p>;
  }

  return <p>Active editor: {editor.id}</p>;
}
```

<Callout type="warning" title="Guard transforms">
  Check `useEditorMounted(id?)` or `!editor.meta.isFallback` before running
  transforms from UI that lives under `PlateController`.
</Callout>

## Registration

`PlateControllerEffect` runs inside `PlateContent`. It registers the current `Plate` store by editor ID, appends primary editors to `primaryEditorIds`, removes them on unmount, and sets `activeId` when Slate focus enters that editor.

| State | Owner | Behavior |
|-------|-------|----------|
| `editorStores` | `PlateControllerEffect` | Maps mounted editor IDs to their Jotai stores. Unmounted IDs are set to `null`. |
| `primaryEditorIds` | `PlateControllerEffect` | Appends mounted editors whose `Plate` store has `primary: true`; removes them on unmount. |
| `activeId` | `PlateControllerEffect` | Set to the focused editor ID. Cleared on unmount when the unmounted editor was active. |

## API Reference

### `PlateController`

Provider for cross-editor lookup state.

<API name="PlateController">
<APIProps>
  <APIItem name="children" type="React.ReactNode">
    Shared UI and editor trees that should participate in controller lookup.
  </APIItem>
  <APIItem name="activeId" type="string | null" optional>
    Initial active editor ID.
  </APIItem>
  <APIItem name="editorStores" type="Record<string, JotaiStore | null>" optional>
    Initial editor-store map.
  </APIItem>
  <APIItem name="primaryEditorIds" type="string[]" optional>
    Initial primary editor ID list.
  </APIItem>
</APIProps>
</API>

### Controller Store State

| State | Type | Default |
|-------|------|---------|
| `activeId` | `string \| null` | `null` |
| `editorStores` | `Record<string, JotaiStore \| null>` | `{}` |
| `primaryEditorIds` | `string[]` | `[]` |

### `usePlateControllerStore`

Resolve a Plate Jotai store from the controller.

<API name="usePlateControllerStore">
<APIParameters>
  <APIItem name="idProp" type="string" optional>
    Editor ID to resolve directly.
  </APIItem>
</APIParameters>
<APIReturns type="JotaiStore | null">
  Matching editor store, active editor store, first mounted primary editor store, or `null`.
</APIReturns>
</API>

### `usePlateControllerExists`

Check whether a local controller provider exists.

<API name="usePlateControllerExists">
<APIReturns type="boolean">
  `true` when `usePlateControllerLocalStore()` finds a controller store.
</APIReturns>
</API>

### `usePlateControllerLocalStore`

Read the local controller atom store.

<API name="usePlateControllerLocalStore">
<APIParameters>
  <APIItem name="options" type="string | { scope?: string; warnIfNoStore?: boolean }" optional>
    Scope options passed to the generated controller store hook. A string is treated as `scope`.
  </APIItem>
</APIParameters>
<APIReturns type="PlateControllerStore">
  Local controller store hook result.
</APIReturns>
</API>

### `PlateControllerEffect`

Register a `Plate` store with the nearest controller.

<API name="PlateControllerEffect">
<APIProps>
  <APIItem name="id" type="string" optional>
    Editor ID to register. Defaults to the ID from the current Plate store.
  </APIItem>
</APIProps>
</API>

`PlateContent` renders `PlateControllerEffect` for you. Render it directly only when you build a custom content surface that still needs controller registration.


# Plate Editor

Source: https://platejs.org/docs/api/core/plate-editor

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Plate Editor
description: API reference for the Plate editor runtime.
---

`PlateEditor` is the React editor type returned by `createPlateEditor`, `usePlateEditor`, and `withPlate`. It extends the base Slate editor with plugin registries, typed `api` and `tf` surfaces, DOM state, metadata, and plugin option helpers.

## Ownership

| Surface | Owner | Notes |
| --- | --- | --- |
| `PlateEditor` | `@platejs/core/react` | React editor type with Plate plugin APIs, transforms, handlers, renders, and hooks. |
| `SlateEditor` | `@platejs/core` | Non-React editor type used by server-side and static editor paths. |
| Slate primitives | `@platejs/slate` | `children`, `selection`, `operations`, core `api`, and core `tf` transforms. |
| Core plugins | `@platejs/core` | Debugging, HTML parsing, parser pipeline, length, node id, history, input rules, and base paragraph behavior. |
| React core plugins | `@platejs/core/react` | React extension, DOM integration, event editor, navigation feedback, and React paragraph plugin. |

Use `PlateEditor` when a page or component runs inside React. Use `SlateEditor` when you need the headless editor from `createSlateEditor`.

## Editor Shape

The editor is still a Slate editor. Plate adds typed plugin access, plugin metadata, DOM state, and option stores on top of that shape.

<API name="PlateEditor">
<APIAttributes>
  <APIItem name="id" type="string">
    Unique editor instance id. `withSlate` uses the provided `id`, an existing editor id, or `nanoid()`.
  </APIItem>
  <APIItem name="children" type="Value">
    Current document value.
  </APIItem>
  <APIItem name="selection" type="TRange | null">
    Current Slate selection.
  </APIItem>
  <APIItem name="operations" type="Operation[]">
    Operations applied since Slate last flushed the editor.
  </APIItem>
  <APIItem name="api" type="EditorApi & CorePluginApi">
    Core Slate APIs plus APIs contributed by resolved Plate plugins.
  </APIItem>
  <APIItem name="tf" type="EditorTransforms & CorePluginTransforms">
    Core Slate transforms plus transforms contributed by resolved Plate plugins.
  </APIItem>
  <APIItem name="transforms" type="PlateEditor['tf']">
    Alias for `tf`.
  </APIItem>
  <APIItem name="plugins" type="Record<string, AnyEditorPlatePlugin>">
    Resolved plugin map keyed by plugin key.
  </APIItem>
  <APIItem name="dom" type="PlateEditor['dom']">
    Runtime DOM state owned by the editor instance.
  </APIItem>
  <APIItem name="meta" type="PlateEditor['meta']">
    Runtime metadata and plugin caches built during plugin resolution.
  </APIItem>
</APIAttributes>
</API>

## Runtime State

`editor.dom` is mutable runtime state. It is updated by React integration, event handlers, focus tracking, and read-only setup.

| Field | Type | Set by |
| --- | --- | --- |
| `composing` | `boolean` | Composition handlers. |
| `currentKeyboardEvent` | `KeyboardEventLike \| null` | `SlateReactExtensionPlugin` while handling keyboard shortcuts. |
| `focused` | `boolean` | DOM focus integration. |
| `prevSelection` | `TRange \| null` | Selection tracking. |
| `readOnly` | `boolean` | `withSlate({ readOnly })`, then React read-only state. |

`editor.meta` carries plugin resolution output. Most application code reads this indirectly through helpers like `getPlugin`, `getOptions`, and render utilities.

| Field | Type | Notes |
| --- | --- | --- |
| `key` | `string` | Internal editor key. `withSlate` creates one with `nanoid()` when missing. |
| `uid` | `string \| undefined` | Stable id used by Plate containers across RSC and client hydration. |
| `userId` | `string \| null \| undefined` | Collaborative identity passed through editor options. |
| `components` | `NodeComponents` | Resolved node components keyed by plugin key. |
| `isFallback` | `boolean` | `false` for normal editors. Fallback editors are created by the controller layer. |
| `pluginList` | `AnyEditorPlatePlugin[]` | Ordered resolved plugin list. |
| `inputRules` | `ResolvedInputRulesMeta` | Input-rule metadata built by the input-rules plugin. |
| `shortcuts` | `Shortcuts` | Resolved shortcut metadata. |
| `pluginCache` | `object` | Precomputed plugin key lists for render hooks, handlers, rules, nodes, decorators, and injection. |

## Plugin Access

Use editor helpers when you need the resolved plugin instance, typed plugin API, typed transforms, or live plugin options.

```tsx title="Plugin option access"
import { ParagraphPlugin, useEditorPlugin } from 'platejs/react';

export function ParagraphType() {
  const { editor } = useEditorPlugin(ParagraphPlugin);

  return <span>{editor.getType(ParagraphPlugin.key)}</span>;
}
```

| Helper | Type | Use it for |
| --- | --- | --- |
| `getPlugin(plugin)` | `<C>(plugin: WithRequiredKey<C>) => EditorPlatePlugin<C>` | Read the resolved plugin instance after overrides and configuration. |
| `getApi(plugin?)` | `<C>(plugin?: WithRequiredKey<C>) => editor.api & InferApi<C>` | Get a typed view of editor APIs. The runtime value is `editor.api`. |
| `getTransforms(plugin?)` | `<C>(plugin?: WithRequiredKey<C>) => editor.tf & InferTransforms<C>` | Get a typed view of editor transforms. The runtime value is `editor.transforms`. |
| `getType(pluginKey)` | `(pluginKey: string) => string` | Resolve the node type for a plugin key. |
| `getInjectProps(plugin)` | `(plugin) => InjectNodeProps` | Read injected node props with default `nodeKey` and `styleKey` filled from the plugin type. |
| `getOptionsStore(plugin)` | `(plugin) => TStateApi` | Read the plugin option store. |
| `getOptions(plugin)` | `(plugin) => InferOptions<C>` | Read all current options for a plugin. |
| `getOption(plugin, key, ...args)` | `(plugin, key, ...args) => value` | Read one option or selector result. Missing stored keys report through `editor.api.debug.error`. |
| `setOption(plugin, key, value)` | `(plugin, key, value) => void` | Update one option in the plugin store. |
| `setOptions(plugin, options)` | `(plugin, partialOrRecipe) => void` | Merge a partial object or run a mutative recipe against the plugin state. |

## Initialization

`withPlate` wraps `withSlate` with React defaults. It uses `createZustandStore` for plugin option stores and prepends the React core plugins before user plugins.

```tsx title="Create a typed editor"
import { usePlateEditor } from 'platejs/react';
import { BoldPlugin } from '@platejs/basic-nodes/react';

export function useBasicEditor() {
  return usePlateEditor({
    plugins: [BoldPlugin],
    value: [
      {
        type: 'p',
        children: [{ text: 'Bold text is ready.' }],
      },
    ],
  });
}
```

`withSlate` does the lower-level setup:

| Step | Behavior |
| --- | --- |
| Editor identity | Sets `editor.id`, `editor.meta.key`, `editor.meta.isFallback`, `editor.meta.userId`, and `editor.dom`. |
| Helper methods | Installs `getApi`, `getTransforms`, `getPlugin`, `getType`, option helpers, and injection helpers. |
| Core plugins | Resolves core plugins, replaces core plugins with custom plugins that share the same key, and resolves the root plugin. |
| Components | Merges `components` into root-plugin component overrides. |
| Normalization guard | Wraps `normalizeNode` so `editor.api.shouldNormalizeNode(entry)` can skip a normalization pass. |
| Initial value | Calls `editor.tf.init({ value, selection, autoSelect, shouldNormalizeEditor, onReady })` unless `skipInitialization` is `true`. |

`value` accepts a Plate value, an HTML string, or a function that returns the value. `onReady` receives `{ editor, isAsync, value }` after initialization completes.

## Core APIs

These APIs exist on every Plate editor because core plugins are always resolved before user plugins.

<API name="Core plugin APIs">
<APIMethods>
  <APIItem name="editor.api.debug.log" type="(message: string, type?: DebugErrorType, details?: any) => void">
    Log a debug message when debug logging is enabled.
  </APIItem>
  <APIItem name="editor.api.debug.info" type="(message: string, type?: DebugErrorType, details?: any) => void">
    Log an info message when the configured log level allows it.
  </APIItem>
  <APIItem name="editor.api.debug.warn" type="(message: string, type?: DebugErrorType, details?: any) => void">
    Log a warning when the configured log level allows it.
  </APIItem>
  <APIItem name="editor.api.debug.error" type="(message: unknown, type?: DebugErrorType, details?: any) => void">
    Throw a `PlateError` by default in development. Configure `DebugPlugin` to change logging or `throwErrors`.
  </APIItem>
  <APIItem name="editor.api.html.deserialize" type="(options: { element: HTMLElement | string; collapseWhiteSpace?: boolean; defaultElementPlugin?: WithRequiredKey }) => Descendant[]">
    Deserialize an HTML element into Plate nodes. The HTML parser plugin calls this for `text/html` paste data.
  </APIItem>
  <APIItem name="editor.api.redecorate" type="() => void">
    Trigger decoration refresh. The React extension warns through `editor.api.debug.warn` until an integration overrides it.
  </APIItem>
  <APIItem name="editor.api.navigation.activeTarget" type="() => NavigationFeedbackTarget | null">
    Read the current navigation feedback target and clear it if the stored target no longer resolves.
  </APIItem>
  <APIItem name="editor.api.navigation.clear" type="() => void">
    Clear the current navigation feedback target.
  </APIItem>
  <APIItem name="editor.api.navigation.isTarget" type="(path: Path) => boolean">
    Check whether a path matches the active navigation feedback target.
  </APIItem>
</APIMethods>
</API>

## Core Transforms

Core transforms live on `editor.tf` and `editor.transforms`. Plugin docs normally show the plugin-specific transform names, but the editor always includes these runtime transforms.

<API name="Core transforms">
<APITransforms>
  <APIItem name="editor.tf.init" type="(options: InitOptions) => void">
    Initialize value, selection, optional normalization, optional auto-selection, and `onReady`.
  </APIItem>
  <APIItem name="editor.tf.insertExitBreak" type="(options?: InsertExitBreakOptions) => boolean | undefined">
    Insert an exit break for plugins that route to the core exit-break transform.
  </APIItem>
  <APIItem name="editor.tf.liftBlock" type="(options?: LiftBlockOptions) => boolean | undefined">
    Lift the selected block through Plate's block transform wrapper.
  </APIItem>
  <APIItem name="editor.tf.resetBlock" type="(options?: { at?: Path }) => boolean | undefined">
    Reset the selected block to the requested type or default block type.
  </APIItem>
  <APIItem name="editor.tf.setValue" type="(value?: Value | string) => void">
    Replace editor children. Use controlled state patterns when React owns the value.
  </APIItem>
  <APIItem name="editor.tf.navigation.clear" type="() => void">
    Clear navigation feedback state.
  </APIItem>
  <APIItem name="editor.tf.navigation.flashTarget" type="(options: NavigationFlashTargetOptions) => boolean">
    Store a target temporarily so components can render navigation feedback.
  </APIItem>
  <APIItem name="editor.tf.navigation.navigate" type="(options: NavigationNavigateOptions) => boolean">
    Navigate to a target and flash it through the navigation feedback plugin.
  </APIItem>
  <APIItem name="editor.tf.reset" type="(options?: ResetOptions) => void">
    React extension wrapper. It restores focus to the editor when the editor was focused before reset.
  </APIItem>
</APITransforms>
</API>

## Plugin Pipeline Effects

Some core behavior is exposed by overriding existing Slate transforms rather than by adding named methods.

| Plugin | Effect |
| --- | --- |
| `ParserPlugin` | Overrides `insertData` and scans plugin parsers in reverse plugin order. Matching parsers transform data, deserialize a fragment, transform the fragment, and insert it. |
| `LengthPlugin` | Wraps `apply` in `withoutNormalizing` and trims overflow when `maxLength` is configured. |
| `SlateExtensionPlugin` | Wraps `apply` so `onNodeChange` and `onTextChange` handlers can receive previous and next node or text state. |
| `SlateReactExtensionPlugin` | Handles line movement, tab, untab, select-all, escape, `currentKeyboardEvent`, focus-preserving reset, and `_memo` cleanup during normalization. |
| `HtmlPlugin` | Registers the `text/html` parser path and delegates HTML elements to `editor.api.html.deserialize`. |
| `BaseParagraphPlugin` | Registers the default paragraph element under key `p` and maps HTML `<p>` elements, excluding code-font paragraphs. |

## Type Helpers

Use `TPlateEditor` when you want an editor typed to a specific value and plugin union.

```ts title="Typed editor helper"
import type { TPlateEditor } from 'platejs/react';
import type { Value } from 'platejs';
import { BoldPlugin } from '@platejs/basic-nodes/react';

type BasicEditor = TPlateEditor<Value, typeof BoldPlugin>;
```

| Type | Purpose |
| --- | --- |
| `PlateEditor` | Runtime editor type with the default Plate core plugin surface. |
| `TPlateEditor<V, P>` | Typed editor for a specific `Value` and plugin union. |
| `KeyofPlugins<T>` | String key union for Plate core plugins plus the supplied plugin config union. |

## Related APIs

- [Plate components](/docs/api/core/plate-components) covers `Plate`, `PlateContent`, `PlateView`, and component-layer runtime effects.
- [PlateController](/docs/api/core/plate-controller) covers active, primary, and fallback editor lookup.
- [Plate plugin](/docs/api/core/plate-plugin) covers plugin configuration, methods, options, handlers, and render hooks.
- [Controlled Value](/docs/controlled) covers React-owned value patterns around `editor.tf.setValue`.


# Plate Plugin

Source: https://platejs.org/docs/api/core/plate-plugin

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Plate Plugin
description: API reference for Plate plugins.
---

Plate plugins are objects passed to `Plate` [plugins](/docs/api/core/plate-components#plugins) prop.

## Plugin Properties

<API name="Properties">
<APIAttributes>
<APIItem name="key" type="C['key']" required>
Unique identifier used by Plate to store the plugins by key in `editor.plugins`.
</APIItem>

<APIItem name="api" type="Record<string, Function>">
An object of API functions provided by the plugin. These functions are accessible via `editor.api[key]`.
</APIItem>

<APIItem name="transforms" type="Record<string, Function>">
Transform functions provided by the plugin that modify the editor state. These are accessible via `editor.tf[key]`.
</APIItem>

<APIItem name="options" type="Record<string, any>">
Extended properties used by the plugin as options.
</APIItem>

<APIItem name="handlers" type="{ onChange?: (editor: PlateEditor) => void } & Record<string, Function>">
Event handlers for various editor events.

<APISubList>
<APISubListItem parent="handlers" name="onChange" type="(editor: PlateEditor) => void" optional>
Called whenever the editor content changes.
</APISubListItem>
<APISubListItem parent="handlers" name="onNodeChange" type="OnNodeChange" optional>
Called whenever a node operation occurs (insert, remove, set, merge, split, move).

```ts
type OnNodeChange = (ctx: PlatePluginContext & {
  node: Descendant;
  operation: NodeOperation;
  prevNode: Descendant;
}) => HandlerReturnType;
```

**Parameters:**
- `node`: The node after the operation
- `operation`: The node operation that occurred
- `prevNode`: The node before the operation

**Note:** For `insert_node` and `remove_node` operations, both `node` and `prevNode` contain the same value to avoid null cases.
</APISubListItem>
<APISubListItem parent="handlers" name="onTextChange" type="OnTextChange" optional>
Called whenever a text operation occurs (insert or remove text).

```ts
type OnTextChange = (ctx: PlatePluginContext & {
  node: Descendant;
  operation: TextOperation;
  prevText: string;
  text: string;
}) => HandlerReturnType;
```

**Parameters:**
- `node`: The parent node containing the text that changed
- `operation`: The text operation that occurred (`insert_text` or `remove_text`)
- `prevText`: The text content before the operation
- `text`: The text content after the operation
</APISubListItem>
</APISubList>
</APIItem>

<APIItem name="inject" type="object">
Defines how the plugin injects functionality into other plugins or the editor.

<APISubList>
<APISubListItem parent="inject" name="nodeProps" type="Record<string, any>" optional>
Properties used by Plate to inject props into any node component.
</APISubListItem>


<APISubListItem parent="inject" name="excludePlugins" type="string[]" optional>
An array of plugin keys to exclude from node prop injection.
</APISubListItem>

<APISubListItem parent="inject" name="excludeBelowPlugins" type="string[]" optional>
An array of plugin keys. Node prop injection will be excluded for any nodes that are descendants of elements with these plugin types.
</APISubListItem>
<APISubListItem parent="inject" name="isBlock" type="boolean" optional>
If true, only matches block elements. Used to restrict prop injection to block-level nodes.
</APISubListItem>

<APISubListItem parent="inject" name="isElement" type="boolean" optional>
If true, only matches element nodes. Used to restrict prop injection to element nodes.
</APISubListItem>
<APISubListItem parent="inject" name="isLeaf" type="boolean" optional>
If true, only matches leaf nodes. Used to restrict prop injection to leaf nodes.
</APISubListItem>
<APISubListItem parent="inject" name="maxLevel" type="number" optional>
Maximum nesting level for node prop injection. Nodes deeper than this level will not receive injected props.
</APISubListItem>
<APISubListItem parent="inject" name="plugins" type="Record<string, Partial<PlatePlugin>>" optional>
Property that can be used by a plugin to allow other plugins to inject code.
</APISubListItem>
<APISubListItem parent="inject" name="targetPluginToInject" type="function" optional>
A function that returns a plugin config to be injected into other plugins `inject.plugins` specified by targetPlugins.
</APISubListItem>
<APISubListItem parent="inject" name="targetPlugins" type="string[]" optional>
Plugin keys used by `InjectNodeProps` and the `targetPluginToInject` function.

- **Default:** `[ParagraphPlugin.key]`
</APISubListItem>
</APISubList>
</APIItem>

<APIItem name="node" type="object">
Defines the node-specific configuration for the plugin.

<APISubList>
<APISubListItem parent="node" name="isDecoration" type="boolean" optional>
Indicates if this plugin's nodes can be rendered as decorated leaf. Set to false to render node component only once per text node.

- **Default:** `true`
</APISubListItem>
<APISubListItem parent="node" name="isElement" type="boolean" optional>
Indicates if this plugin's nodes should be rendered as elements.
</APISubListItem>
<APISubListItem parent="node" name="isInline" type="boolean" optional>
Indicates if this plugin's elements should be treated as inline.
</APISubListItem>
<APISubListItem parent="node" name="isLeaf" type="boolean" optional>
Indicates if this plugin's nodes should be rendered as leaves.
</APISubListItem>
<APISubListItem parent="node" name="isContainer" type="boolean" optional>
When `true`, indicates that the plugin's elements are primarily containers for other content. This property is typically used by fragment queries to unwrap the container nodes.
</APISubListItem>
<APISubListItem parent="rules" name="selection.affinity" type="'default' | 'directional' | 'outward' | 'hard'" optional>
Defines the selection behavior at the boundaries of nodes. See [Plugin Rules](/docs/plugin-rules#rulesselection).

- `'default'`: Uses Slate's default behavior
- `'directional'`: Selection affinity is determined by the direction of cursor movement. Maintains inward or outward affinity based on approach
- `'outward'`: Forces outward affinity. Typing at the edge of a mark will not apply the mark to new text
- `'hard'`: Creates a 'hard' edge that requires two key presses to move across. Uses offset-based navigation

- **Default:** `undefined` (Slate's default behavior)
</APISubListItem>
<APISubListItem parent="node" name="isMarkableVoid" type="boolean" optional>
Indicates if this plugin's void elements should be markable.
</APISubListItem>
<APISubListItem parent="node" name="isSelectable" type="boolean" optional>
Indicates if this plugin's nodes should be selectable.

- **Default:** `true`
</APISubListItem>
<APISubListItem parent="node" name="isStrictSiblings" type="boolean" optional>
Indicates whether this element enforces strict sibling type constraints. Set to `true` when the element only allows specific siblings (e.g., `td` can only have `td` siblings, `column` can only have `column` siblings) and prevents standard text blocks like paragraphs from being inserted as siblings.

Used by exit break functionality to determine appropriate exit points in nested structures. See [Exit Break](/docs/exit-break).

- **Default:** `false`
</APISubListItem>
<APISubListItem parent="rules" name="break.empty" type="'default' | 'deleteExit' | 'exit' | 'lift' | 'reset'" optional>
Action when Enter is pressed in an empty block. See [Plugin Rules](/docs/plugin-rules).

- `'default'`: Default behavior
- `'reset'`: Reset block to default paragraph type
- `'exit'`: Exit the current block
- `'lift'`: Lift the current block out of the nearest matching ancestor
- `'deleteExit'`: Delete backward then exit
</APISubListItem>
<APISubListItem parent="rules" name="break.emptyLineEnd" type="'default' | 'deleteExit' | 'exit'" optional>
Action when Enter is pressed at the end of an empty line. This is typically used with `rules.break.default: 'lineBreak'`. See [Plugin Rules](/docs/plugin-rules).

- `'default'`: Default behavior
- `'exit'`: Exit the current block
- `'deleteExit'`: Delete backward then exit
</APISubListItem>
<APISubListItem parent="rules" name="break.default" type="'default' | 'deleteExit' | 'exit' | 'lineBreak'" optional>
Default action when Enter is pressed. Defaults to splitting the block. See [Plugin Rules](/docs/plugin-rules).

- `'default'`: Default behavior
- `'exit'`: Exit the current block
- `'lineBreak'`: Insert newline character
- `'deleteExit'`: Delete backward then exit
</APISubListItem>
<APISubListItem parent="rules" name="break.splitReset" type="boolean" optional>
If true, the new block after splitting will be reset to the default type. See [Plugin Rules](/docs/plugin-rules).
</APISubListItem>
<APISubListItem parent="rules" name="delete.start" type="'default' | 'lift' | 'reset'" optional>
Action when Backspace is pressed at the start of the block. This applies whether the block is empty or not. See [Plugin Rules](/docs/plugin-rules).

- `'default'`: Default behavior
- `'lift'`: Lift the current block out of the nearest matching ancestor
- `'reset'`: Reset block to default paragraph type
</APISubListItem>
<APISubListItem parent="rules" name="delete.empty" type="'default' | 'reset'" optional>
Action when Backspace is pressed and the block is empty. See [Plugin Rules](/docs/plugin-rules).

- `'default'`: Default behavior
- `'reset'`: Reset block to default paragraph type
</APISubListItem>
<APISubListItem parent="rules" name="match" type="MatchRules" optional>
Function to determine if this plugin's rules should apply to a node. Used to override behavior based on node properties beyond just type matching.

**Default:** `type === node.type`

**Example:** `matchRules: ({ node }) => Boolean(node.listStyleType)`

Example: List plugin sets `match: ({ node }) => !!node.listStyleType` to override paragraph behavior when the paragraph is a list item.

</APISubListItem>
<APISubListItem parent="rules" name="merge.removeEmpty" type="boolean" optional>
Whether to remove the node when it's empty during merge operations. See [Plugin Rules](/docs/plugin-rules).

- **Default:** `false`
</APISubListItem>
<APISubListItem parent="rules" name="normalize.removeEmpty" type="boolean" optional>
Whether to remove nodes with empty text during normalization. See [Plugin Rules](/docs/plugin-rules).

- **Default:** `false`
</APISubListItem>
<APISubListItem parent="node" name="isVoid" type="boolean" optional>
Indicates if this plugin's elements should be treated as void.
</APISubListItem>
<APISubListItem parent="node" name="type" type="string" optional>
Specifies the type identifier for this plugin's nodes. 

- **Default:** `plugin.key`
</APISubListItem>
<APISubListItem parent="node" name="component" type="NodeComponent | null" optional>
React component used to render this plugin's nodes.
</APISubListItem>
<APISubListItem parent="node" name="leafProps" type="LeafNodeProps<WithAnyKey<C>>" optional>
Override `data-slate-leaf` element attributes.
</APISubListItem>
<APISubListItem parent="node" name="props" type="NodeProps<WithAnyKey<C>>" optional>
Override node attributes.
</APISubListItem>
<APISubListItem parent="node" name="textProps" type="TextNodeProps<WithAnyKey<C>>" optional>
Override `data-slate-node="text"` element attributes.
</APISubListItem>
</APISubList>
</APIItem>

<APIItem name="override" type="object">
Allows overriding components and plugins by key.

<APISubList>
<APISubListItem parent="override" name="components" type="Record<string, NodeComponent>" optional>
Replace plugin `NodeComponent` by key.
</APISubListItem>
<APISubListItem parent="override" name="plugins" type="Record<string, Partial<EditorPlatePlugin<AnyPluginConfig>>>" optional>
Extend `PlatePlugin` by key.
</APISubListItem>
<APISubListItem parent="override" name="enabled" type="Partial<Record<string, boolean>>" optional>
Enable or disable plugins.
</APISubListItem>
</APISubList>
</APIItem>

<APIItem name="parser" type="Nullable<Parser<WithAnyKey<C>>>">
Defines how the plugin parses content.
</APIItem>

<APIItem name="parsers" type="object">
Defines serializers and deserializers for various formats.

<APISubList>
<APISubListItem parent="parsers" name="html" type="Nullable<{ deserializer?: HtmlDeserializer<WithAnyKey<C>>; serializer?: HtmlSerializer<WithAnyKey<C>> }>" optional>
HTML parser configuration.
</APISubListItem>
<APISubListItem parent="parsers" name="htmlReact" type="Nullable<{ serializer?: HtmlReactSerializer<WithAnyKey<C>> }>" optional>
HTML React serializer configuration.
</APISubListItem>
</APISubList>
</APIItem>

<APIItem name="render" type="object">
Defines how the plugin renders components.

<APISubList>
<APISubListItem parent="render" name="aboveEditable" type="Component" optional>
Component rendered above the Editable component but inside the Slate wrapper.
</APISubListItem>
<APISubListItem parent="render" name="aboveNodes" type="RenderNodeWrapper<WithAnyKey<C>>" optional>
Create a function that generates a parent React node for all other plugins' node components.
</APISubListItem>
<APISubListItem parent="render" name="aboveSlate" type="Component" optional>
Component rendered above the Slate wrapper.
</APISubListItem>
<APISubListItem parent="render" name="afterEditable" type="EditableSiblingComponent" optional>
Renders a component after the Editable component.
</APISubListItem>
<APISubListItem parent="render" name="beforeEditable" type="EditableSiblingComponent" optional>
Renders a component before the Editable component.
</APISubListItem>
<APISubListItem parent="render" name="belowNodes" type="RenderNodeWrapper<WithAnyKey<C>>" optional>
Create a function that generates a React node below all other plugins' node React node, but above their children.
</APISubListItem>
<APISubListItem parent="render" name="belowRootNodes" type="(props: PlateElementProps<TElement, C>) => React.ReactNode" optional>
Renders a component after the direct children of the root element. This differs from `belowNodes` in that it's the direct child of `PlateElement` rather than wrapping the children that could be nested. This is useful when you need components relative to the root element.
</APISubListItem>
<APISubListItem parent="render" name="leaf" type="NodeComponent" optional>
Renders a component below leaf nodes when `isLeaf: true` and `isDecoration: false`. Use `render.node` instead when `isDecoration: true`.
</APISubListItem>
<APISubListItem parent="render" name="node" type="NodeComponent" optional>
Renders a component for:
- Elements nodes if `isElement: true`
- Below text nodes if `isLeaf: true` and `isDecoration: false`
- Below leaf if `isLeaf: true` and `isDecoration: true`
</APISubListItem>
<APISubListItem parent="render" name="as" type="keyof HTMLElementTagNameMap" optional>
Specifies the HTML tag name to use when rendering the node component. Only used when no custom `component` is provided for the plugin.

- **Default:** `'div'` for elements, `'span'` for leaves

</APISubListItem>
</APISubList>
</APIItem>

<APIItem name="shortcuts" type="Shortcuts">
Defines keyboard shortcuts for the plugin.
</APIItem>

<APIItem name="useOptionsStore" type="StoreApi<C['key'], C['options']>">
Zustand store for managing plugin options.
</APIItem>

<APIItem name="dependencies" type="string[]">
An array of plugin keys that this plugin depends on.
</APIItem>

<APIItem name="enabled" type="boolean" optional>
Enables or disables the plugin. Used by Plate to determine if the plugin should be used.
</APIItem>

<APIItem name="plugins" type="any[]">
Recursive plugin support to allow having multiple plugins in a single plugin.
</APIItem>

<APIItem name="priority" type="number">
Defines the order in which plugins are registered and executed.

- **Default:** `100`
</APIItem>

<APIItem name="decorate" type="Decorate<WithAnyKey<C>>" optional>
Property used by Plate to decorate editor ranges.
</APIItem>

<APIItem name="extendEditor" type="ExtendEditor<WithAnyKey<C>>" optional>
Function to extend the editor instance. Used primarily for integrating legacy Slate plugins that need direct editor mutation. Only one `extendEditor` is allowed per plugin.

```ts
extendEditor: ({ editor }) => {
  // Example: Integrating a legacy Slate plugin
  return withYjs(editor);
}
```
</APIItem>

<APIItem name="useHooks" type="() => void" optional>
Hook called when the editor is initialized.
</APIItem>

<APIItem name="editOnly" type="boolean | EditOnlyConfig" optional>
Configures which plugin functionalities should only be active when the editor is not read-only.

Can be either a boolean or an object configuration:

```ts
type EditOnlyConfig = {
  render?: boolean;      // default: true
  handlers?: boolean;    // default: true
  inject?: boolean;      // default: true
  transformInitialValue?: boolean;  // default: false
}
```

When set to `true` (boolean):
- `render`, `handlers`, and `inject.nodeProps` are only active when editor is not read-only
- `transformInitialValue` remains active regardless of read-only state

When set to an object:
- Each property can be individually configured
- Properties default to being edit-only (`true`) except `transformInitialValue` which defaults to always active (`false`)
- Set a property to `false` to make it always active regardless of read-only state
- For `transformInitialValue`, set to `true` to make it edit-only

Examples:
```ts
// All features (except transformInitialValue) are edit-only
editOnly: true

// transformInitialValue is edit-only, others remain edit-only by default
editOnly: { transformInitialValue: true }

// render is always active, others follow default behavior
editOnly: { render: false }
```
</APIItem>
</APIAttributes>
</API>

## Plugin Methods

<API name="Methods">
<APIMethods>
<APIItem name="configure" type="(config: PlatePluginConfig | ((ctx: PlatePluginContext) => PlatePluginConfig)) => PlatePlugin">
Creates a new plugin instance with updated options.

```ts
(config: PlatePluginConfig<C['key'], InferOptions<C>, InferApi<C>, InferTransforms<C>> | ((ctx: PlatePluginContext<C>) => PlatePluginConfig<C['key'], InferOptions<C>, InferApi<C>, InferTransforms<C>>)) => PlatePlugin<C>
```
</APIItem>

<APIItem name="extend" type="(config: Partial<PlatePlugin> | ((ctx: PlatePluginContext) => Partial<PlatePlugin>)) => PlatePlugin">
Creates a new plugin instance with additional configuration.

```ts
(extendConfig: Partial<PlatePlugin> | ((ctx: PlatePluginContext<AnyPluginConfig>) => Partial<PlatePlugin>)) => PlatePlugin
```
</APIItem>

<APIItem name="extendPlugin" type="(key: string, config: Partial<PlatePlugin> | ((ctx: PlatePluginContext) => Partial<PlatePlugin>)) => PlatePlugin">
Extends an existing nested plugin or adds a new one if not found. Supports deep nesting.

```ts
(key: string, extendConfig: Partial<PlatePlugin> | ((ctx: PlatePluginContext<AnyPluginConfig>) => Partial<PlatePlugin>)) => PlatePlugin
```
</APIItem>

<APIItem name="withComponent" type="function">
Sets or replaces the component associated with a plugin.

```ts
(component: NodeComponent) => PlatePlugin<C>
```
</APIItem>

<APIItem name="overrideEditor" type="function">
Creates a new plugin instance with overridden editor methods. Provides access to original methods via `tf` and `api` parameters. Can be called multiple times to layer different overrides.

```ts
overrideEditor(({ editor, tf: { deleteForward }, api: { isInline } }) => ({
  transforms: {
    // Override transforms
    deleteForward(options) {
      deleteForward(options);
    },
  },
  api: {
    // Override API methods
    isInline(element) {
      return isInline(element);
    },
  },
})) => PlatePlugin<C>
```

- Preferred method for modifying editor behavior
- Type-safe access to original methods
- Clean separation between transforms and API
- Can be chained multiple times
</APIItem>

<APIItem name="extendApi" type="(api: (ctx: PlatePluginContext) => Record<string, Function>) => PlatePlugin">
Extends the plugin's API.

```ts
(api: (ctx: PlatePluginContext) => Record<string, Function>) => PlatePlugin
```
</APIItem>

<APIItem name="extendEditorApi" type="(api: (ctx: PlatePluginContext) => Record<string, Function>) => PlatePlugin">
Extends the editor's API with plugin-specific methods.

```ts
(api: (ctx: PlatePluginContext) => Record<string, Function>) => PlatePlugin
```
</APIItem>

<APIItem name="extendTransforms" type="(transforms: (ctx: PlatePluginContext) => Record<string, Function>) => PlatePlugin">
Extends the plugin's transforms.

```ts
(transforms: (ctx: PlatePluginContext) => Record<string, Function>) => PlatePlugin
```
</APIItem>

<APIItem name="extendEditorTransforms" type="(transforms: (ctx: PlatePluginContext) => Record<string, Function>) => PlatePlugin">
Extends the editor's transforms with plugin-specific methods.

```ts
(transforms: (ctx: PlatePluginContext) => Record<string, Function>) => PlatePlugin
```
</APIItem>

<APIItem name="extendSelectors" type="(options: (ctx: PlatePluginContext) => Record<string, any>) => PlatePlugin">
Extends the plugin with selectors.

```ts
(options: (ctx: PlatePluginContext) => Record<string, any>) => PlatePlugin
```
</APIItem>
</APIMethods>
</API>

## Plugin Context

<API name="Context">
<APIAttributes>
<APIItem name="editor" type="PlateEditor">
The current editor instance.
</APIItem>
<APIItem name="plugin" type="EditorPlatePlugin<C>">
The current plugin instance.
</APIItem>
<APIItem name="getOption" type="function">
Function to get a specific option value.
</APIItem>
<APIItem name="getOptions" type="function">
Function to get all options for the plugin.
</APIItem>
<APIItem name="setOption" type="function">
Function to set a specific option value.
</APIItem>
<APIItem name="setOptions" type="function">
Function to set multiple options.
</APIItem>
</APIAttributes>
</API>

For more detailed information on specific aspects of Plate plugins, refer to the individual guides on [Plugin Configuration](/docs/plugin), [Plugin Methods](/docs/plugin-methods), [Plugin Context](/docs/plugin-context), [Plugin Components](/docs/plugin-components), and [Plugin Shortcuts](/docs/plugin-shortcuts).

## Generic Types

<API name="GenericTypes">
<APIAttributes>
<APIItem name="C" type="AnyPluginConfig = PluginConfig">
Represents the plugin configuration. This type extends `PluginConfig` which includes `key`, `options`, `api`, and `transforms`.
</APIItem>
</APIAttributes>
</API>

Usage example:

```typescript
type MyPluginConfig = PluginConfig<
  'myPlugin',
  { customOption: boolean },
  { getData: () => string },
  { customTransform: () => void }
>;

const MyPlugin = createPlatePlugin<MyPluginConfig>({
  key: 'myPlugin',
  // plugin implementation
});
```


# Store

Source: https://platejs.org/docs/api/core/plate-store

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Store
description: API reference for Plate store.
---

`Plate` is using [jotai-x](https://github.com/udecode/jotai-x) to store the state of the editor.

## Plate Store

<API name="Store">
The `PlateStoreState` object stores the state of the Plate editor. It contains information about the editor's ID, its current value, its plugins, and other settings.

<APIState>
<APIItem name="editor" type="PlateEditor">
Plate editor reference.

- **Default:** `createPlateFallbackEditor()`
</APIItem>

<APIItem name="id" type="string">
A unique ID used as a provider scope. Use it if you have multiple `Plate` in the same React tree.

- **Default:** random id
</APIItem>

<APIItem name="containerRef" type="React.RefObject<HTMLDivElement>">
A reference to the editor container element.
</APIItem>

<APIItem name="decorate" type="function" optional>
Function used to decorate ranges in the editor.

```ts
(options: { editor: PlateEditor; entry: NodeEntry }) => TRange[]
```
</APIItem>

<APIItem name="isMounted" type="boolean" optional>
Whether `Editable` is rendered so slate DOM is resolvable.
</APIItem>

<APIItem name="onChange" type="function" optional>
Controlled callback called when the editor state changes.

```ts
(options: { editor: PlateEditor; value: ValueOf<PlateEditor> }) => void
```
</APIItem>

<APIItem name="onSelectionChange" type="function" optional>
Controlled callback called when the editor.selection changes.

```ts
(options: { editor: PlateEditor; selection: TSelection }) => void
```
</APIItem>

<APIItem name="onValueChange" type="function" optional>
Controlled callback called when the editor.children changes.

```ts
(options: { editor: PlateEditor; value: ValueOf<PlateEditor> }) => void
```
</APIItem>

<APIItem name="onNodeChange" type="function" optional>
Controlled callback called when a node operation occurs.

```ts
(options: { 
  editor: PlateEditor; 
  node: Descendant; 
  operation: NodeOperation; 
  prevNode: Descendant 
}) => void
```

**Parameters:**
- `editor`: The Plate editor instance
- `node`: The node after the operation
- `operation`: The node operation that occurred (insert, remove, set, merge, split, move)
- `prevNode`: The node before the operation

**Note:** For `insert_node` and `remove_node` operations, both `node` and `prevNode` contain the same value to avoid null cases.
</APIItem>

<APIItem name="onTextChange" type="function" optional>
Controlled callback called when a text operation occurs.

```ts
(options: { 
  editor: PlateEditor; 
  node: Descendant; 
  operation: TextOperation; 
  prevText: string; 
  text: string 
}) => void
```

**Parameters:**
- `editor`: The Plate editor instance
- `node`: The parent node containing the text that changed
- `operation`: The text operation that occurred (`insert_text` or `remove_text`)
- `prevText`: The text content before the operation
- `text`: The text content after the operation
</APIItem>

<APIItem name="primary" type="boolean" optional>
Whether the editor is primary. If no editor is active, then PlateController will use the first-mounted primary editor.

- **Default:** `true`
</APIItem>

<APIItem name="readOnly" type="boolean" optional>
Whether the editor is read-only.
</APIItem>

<APIItem name="renderElement" type="function" optional>
Function to render elements in the editor.
</APIItem>

<APIItem name="renderLeaf" type="function" optional>
Function to render leaf nodes in the editor.
</APIItem>

<APIItem name="versionDecorate" type="number" optional>
Version incremented when calling `redecorate`. This is a dependency of the `decorate` function.
</APIItem>

<APIItem name="versionEditor" type="number" optional>
Version incremented on each editor change.
</APIItem>

<APIItem name="versionSelection" type="number" optional>
Version incremented on each editor.selection change.
</APIItem>

<APIItem name="versionValue" type="number" optional>
Version incremented on each editor.children change.
</APIItem>
</APIState>
</API>

## Accessing the Store

```ts
import { usePlateStore, useEditorRef, useEditorPlugin } from 'platejs/react'

// Direct store access
const store = usePlateStore(id?) 

// Via editor reference
const store = useEditorRef().store

// Via plugin context
const store = useEditorPlugin(myPlugin).store
```

Note: The `id` parameter is optional and defaults to the closest editor.

## Store Hooks

The following hooks are available to interact with the Plate store:

```ts
import { usePlateState, usePlateValue, usePlateSet } from 'platejs/react'
```

### usePlateState

Get and set a store property value.

```ts
const [readOnly, setReadOnly] = usePlateState('readOnly', id?)
```

### usePlateValue

Subscribe to a store property value.

```ts
const readOnly = usePlateValue('readOnly', id?)
```

### usePlateSet

Set a store property value.

```ts
const setReadOnly = usePlateSet('readOnly', id?)
```

## Event Editor Store

This store is an object whose property keys are event names (e.g. `'focus'`) and whose property values are [editor IDs](Plate#id).

- This is useful when having [multiple editors](multiple-editors) and get one based on DOM events (e.g. the last focused editor).
- One of the core plugins of [Plate](Plate) will store the following events.

<API name="EventEditorStore">
<APIState>
<APIItem name="blur" type="string | null">

Last editor ID that has been blurred.

</APIItem>

<APIItem name="focus" type="string | null">

Editor ID that is currently being focused.

</APIItem>

<APIItem name="last" type="string | null">

Last editor ID.

</APIItem>
</APIState>
</API>


```ts
import { EventEditorStore, useEventEditorValue } from 'platejs'

// Get a value
const focusedId = EventEditorStore.get('focus')

// Set a value
EventEditorStore.set('focus', editorId)

// Subscribe to changes
const focusedId = useEventEditorValue('focus')
```

### `useEventPlateId`

Get the last event editor ID.

<API name="useEventPlateId">
<APIParameters>
<APIItem name="id" type="string | null">

Returned ID if defined.

</APIItem>
</APIParameters>

<APIReturns type="string">
  The plate id from the context if available, otherwise the last event editor
  ID or `PLATE_SCOPE`.
</APIReturns>
</API>


# Editor API

Source: https://platejs.org/docs/api/slate/editor-api

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Editor API
description: API reference for the Editor API.
---

The Editor API provides a set of helper functions for querying and manipulating the editor state.

## Common Options

### `At`

A location reference in the editor. Can be either a Location or a Node.

```ts
type At = TLocation | TNode
```

When a Node is passed, its path will be found using [`editor.api.findPath()`](/docs/api/slate/editor-api#findpath). This allows you to reference a location by either:
- A [Location](/docs/api/slate/location) ([Path](/docs/api/slate/path), [Point](/docs/api/slate/point), or [Range](/docs/api/slate/range))
- A [Node](/docs/api/slate/node)

Example:
```ts
// Using a location
editor.api.nodes({ at: [0, 0] }) // Path location
editor.api.nodes({ at: { path: [0], offset: 0 } }) // Point location 
editor.api.nodes({ at: { anchor: point1, focus: point2 } }) // Range location

// Using a node reference
const node = editor.children[0]
editor.api.nodes({ at: node }) // Will find node's path internally
```

### Match

A predicate for matching nodes. The predicate can be either:
- A function that takes a `node` and its `path` and returns a `boolean`
- An object where each key-value pair must match the node's properties
  - Values can be single values or arrays of values to match against

Example:
```ts
// Function predicate
editor.api.nodes({
  match: (node) => node.type === 'p'
})

// Object predicate
editor.api.nodes({
  match: { type: 'p' }
})

// Object predicate with multiple possible values
editor.api.nodes({
  match: { type: ['p', 'h1'] }
})
```

### `QueryMode`

Mode for querying nodes in a hierarchy.

<API name="QueryMode">
<APIOptions type="QueryMode">
  <APIItem name="mode" type="'all' | 'highest' | 'lowest'" optional>
    - `'all'` (default): Return all matching nodes
    - `'highest'`: In a hierarchy of nodes, only return the highest-level matching nodes
    - `'lowest'`: In a hierarchy of nodes, only return the lowest-level matching nodes

    Example:
    ```ts
    // Given this structure:
    // - blockquote (matches)
    //   - paragraph (matches)
    //     - text
    
    // mode: 'all' returns both blockquote and paragraph
    editor.api.nodes({ match: { type: ['blockquote', 'paragraph'] }, mode: 'all' })
    
    // mode: 'highest' returns only blockquote
    editor.api.nodes({ match: { type: ['blockquote', 'paragraph'] }, mode: 'highest' })
    
    // mode: 'lowest' returns only paragraph
    editor.api.nodes({ match: { type: ['blockquote', 'paragraph'] }, mode: 'lowest' })
    ```
  </APIItem>
</APIOptions>
</API>

### `QueryOptions`

Common options for querying nodes in the editor.

<API name="QueryOptions">
<APIOptions type="QueryOptions<V>">
  <APIItem name="at" type="At" optional>
    Where to start querying from. Defaults to current editor selection.
  </APIItem>
  <APIItem name="block" type="boolean" optional>
    Match block nodes. When true, only matches block elements.
  </APIItem>
  <APIItem name="empty" type="boolean" optional>
    Match empty/non-empty nodes.
    - When true, matches only empty nodes
    - When false, matches only non-empty nodes
  </APIItem>
  <APIItem name="id" type="boolean | string" optional>
    Match the node by id.
    - When true, matches all nodes with an id
    - When string, matches nodes with that specific id
  </APIItem>
  <APIItem name="match" type="Predicate<NodeIn<V>>" optional>
    Custom function or object to match nodes.
    - Function: `(node, path) => boolean`
    - Object: Key-value pairs that should match the node
  </APIItem>
  <APIItem name="text" type="boolean" optional>
    Match text nodes. When true, matches only text nodes.
  </APIItem>
</APIOptions>
</API>

## `editor.api`

### `above`

Get the matching ancestor above a location in the document.

<API name="above">
<APIOptions type="EditorAboveOptions<V>">
  <APIItem name="...options" type="QueryOptions<V>" optional>
    Common query options.
  </APIItem>
  <APIItem name="mode" type="QueryMode" optional>
    Query mode options.
  </APIItem>
  <APIItem name="voids" type="boolean" optional>
    Whether to include void nodes in the search.
  </APIItem>
</APIOptions>

<APIReturns type="NodeEntry<N> | undefined">
  A tuple containing the matching ancestor node and its path, or `undefined` if no match is found.
</APIReturns>
</API>

### `block`

Get the block at a location or find the first block that matches options.  
Blocks are typically top-level nodes, so this is a common way to retrieve the ancestor block.

```ts
editor.api.block() // Get block above selection
editor.api.block({ above: true }) // Get block above selection
editor.api.block({ at: [0, 0] }) // Get block at [0, 0]
editor.api.block({ at: [0, 0], above: true }) // Get block at [0]
editor.api.block({ highest: true }) // Get highest block at selection
```

<API name="block">
<APIOptions type="EditorBlockOptions<V>">
  <APIItem name="...options" type="QueryOptions<V>" optional>
    Common query options for matching blocks.
  </APIItem>
  <APIItem name="at" type="At | Span" optional>
    The location to query at. Defaults to current selection.
  </APIItem>
  <APIItem name="ignoreNonSelectable" type="boolean" optional>
    Whether to ignore non-selectable nodes during traversal.
  </APIItem>
  <APIItem name="reverse" type="boolean" optional>
    Whether to traverse in reverse order.
  </APIItem>
  <APIItem name="universal" type="boolean" optional>
    Whether to ensure the operation works universally across all nodes.
  </APIItem>
  <APIItem name="above" type="boolean" optional>
    If true, get the block above the location. Ignored if `at` is not a block path.
  </APIItem>
  <APIItem name="highest" type="boolean" optional>
    If true, get the highest block at the location (root-level block).
  </APIItem>
  <APIItem name="mode" type="QueryMode" optional>
    Query mode for matching blocks.
  </APIItem>
  <APIItem name="voids" type="boolean" optional>
    Whether to include void nodes in the search.
  </APIItem>
</APIOptions>

<APIReturns type="NodeEntry<N> | undefined">
  The matching block node entry or `undefined` if no match is found.
</APIReturns>
</API>

### `blocks`

Returns all matching blocks.

<API name="blocks">
<APIOptions type="EditorNodesOptions<V>">
  <APIItem name="...options" type="QueryOptions<V>" optional>
    Common query options for matching blocks.
  </APIItem>
  <APIItem name="at" type="At | Span" optional>
    The location to query at. Defaults to current selection.
  </APIItem>
  <APIItem name="ignoreNonSelectable" type="boolean" optional>
    Whether to ignore non-selectable nodes during traversal.
  </APIItem>
  <APIItem name="reverse" type="boolean" optional>
    Whether to traverse in reverse order.
  </APIItem>
  <APIItem name="universal" type="boolean" optional>
    Whether to ensure the operation works universally across all nodes.
  </APIItem>
  <APIItem name="mode" type="QueryMode" optional>
    Query mode for matching blocks.
  </APIItem>
  <APIItem name="voids" type="boolean" optional>
    Whether to include void nodes in the search.
  </APIItem>
</APIOptions>

<APIReturns type="NodeEntry<ElementIn<V>>[]">
  An array of matching block node entries.
</APIReturns>
</API>

### `edgeBlocks`

Returns the edge blocks above a location (default: selection).  
Useful for retrieving the start and end block of a range.

<API name="edgeBlocks">
<APIOptions type="EditorNodesOptions<V>">
  <APIItem name="...options" type="QueryOptions<V>" optional>
    Common query options for matching blocks.
  </APIItem>
  <APIItem name="at" type="At | Span" optional>
    The location to get edge blocks from. Defaults to current selection.
  </APIItem>
  <APIItem name="ignoreNonSelectable" type="boolean" optional>
    Whether to ignore non-selectable nodes during traversal.
  </APIItem>
  <APIItem name="reverse" type="boolean" optional>
    Whether to traverse in reverse order.
  </APIItem>
  <APIItem name="universal" type="boolean" optional>
    Whether to ensure the operation works universally across all nodes.
  </APIItem>
  <APIItem name="mode" type="QueryMode" optional>
    Query mode for matching blocks.
  </APIItem>
  <APIItem name="voids" type="boolean" optional>
    Whether to include void nodes in the search.
  </APIItem>
</APIOptions>

<APIReturns type="[NodeEntry<N1>, NodeEntry<N2>] | null">
  A tuple of `[startBlock, endBlock]` above the location, or `null` if not found.
</APIReturns>
</API>

### `first`

Get the first node at a location.

<API name="first">
<APIParameters>
  <APIItem name="at" type="At">
    The location to get the first node from.
  </APIItem>
</APIParameters>

<APIReturns type="NodeEntry<DescendantIn<V>> | undefined">
  A tuple containing the first node and its path, or undefined if not found.
</APIReturns>
</API>

### `fragment`

Get the fragment at a location or selection.

<API name="fragment">
<APIParameters>
  <APIItem name="at" type="At | null" optional>
    The location to extract the fragment from. Defaults to current selection.
  </APIItem>
  <APIItem name="options" type="EditorFragmentOptions" optional>
    Options for extracting and processing the fragment.
  </APIItem>
</APIParameters>

<APIReturns type="ElementOrTextIn<V>[] | undefined">
  The fragment at the location.
</APIReturns>
</API>

### `getFragment`

Returns the fragment at the current selection. Used when cutting or copying, as an example, to get the fragment at the current selection.

<API name="getFragment">
<APIParameters>
  <APIItem name="at" type="At" optional>
    The location to get the fragment from. Defaults to current selection.
  </APIItem>
</APIParameters>

<APIReturns type="ElementOrTextIn<V>[]">
  The fragment at the current selection.
</APIReturns>
</API>

### `hasBlocks`

Check if a node has block children.

<API name="hasBlocks">
<APIParameters>
  <APIItem name="element" type="ElementIn<V>">
    The element to check.
  </APIItem>
</APIParameters>

<APIReturns type="boolean">
  True if the element has block children, false otherwise.
</APIReturns>
</API>

### `hasInlines`

Check if a node has inline and text children.

<API name="hasInlines">
<APIParameters>
  <APIItem name="element" type="ElementIn<V>">
    The element to check.
  </APIItem>
</APIParameters>

<APIReturns type="boolean">
  True if the element has inline and text children, false otherwise.
</APIReturns>
</API>

### `hasMark`

Check if mark is active at selection.

<API name="hasMark">
<APIParameters>
  <APIItem name="key" type="keyof MarksIn<V>">
    The mark key to check.
  </APIItem>
</APIParameters>

<APIReturns type="boolean">
  True if the mark is active at the current selection, false otherwise.
</APIReturns>
</API>

### `hasPath`

Check if a path exists in the editor.

<API name="hasPath">
<APIParameters>
  <APIItem name="path" type="Path">
    The path to check.
  </APIItem>
</APIParameters>

<APIReturns type="boolean">
  True if the path exists, false otherwise.
</APIReturns>
</API>

### `hasTexts`

Check if a node has text children.

<API name="hasTexts">
<APIParameters>
  <APIItem name="element" type="ElementIn<V>">
    The element to check.
  </APIItem>
</APIParameters>

<APIReturns type="boolean">
  True if the element has text children, false otherwise.
</APIReturns>
</API>

### `isAt`

Check if a location (point/range) is at a specific position.

```ts
// For ranges:
editor.api.isAt({ text: true }) // Check if range is in a single text node
editor.api.isAt({ block: true }) // Check if range is in a single block
editor.api.isAt({ blocks: true }) // Check if range is across multiple blocks
editor.api.isAt({ start: true }) // Check if range starts at block start
editor.api.isAt({ end: true }) // Check if range ends at block end

// For points:
editor.api.isAt({ word: true }) // Check relative to word boundaries
editor.api.isAt({ start: true }) // Check if at start
editor.api.isAt({ end: true }) // Check if at end
```

<API name="isAt">
<APIOptions type="object">
  <APIItem name="at" type="At" optional>
    The location to check. Defaults to current selection.
  </APIItem>
  <APIItem name="text" type="boolean" optional>
    Check if range is in a single text node.
  </APIItem>
  <APIItem name="block" type="boolean" optional>
    Check if range is in a single block.
  </APIItem>
  <APIItem name="blocks" type="boolean" optional>
    Check if range is across multiple blocks.
  </APIItem>
  <APIItem name="start" type="boolean" optional>
    Check if at start position.
  </APIItem>
  <APIItem name="end" type="boolean" optional>
    Check if at end position.
  </APIItem>
  <APIItem name="word" type="boolean" optional>
    Check relative to word boundaries.
  </APIItem>
</APIOptions>

<APIReturns type="boolean">
  True if the location matches all specified position criteria, false otherwise.
</APIReturns>
</API>

### `isCollapsed`

Check if the selection is collapsed (start and end points are the same).

<API name="isCollapsed">
<APIReturns type="boolean">
  True if the selection is collapsed, false otherwise.
</APIReturns>
</API>

### `isEdge`

Check if a point is an edge of a location.

<API name="isEdge">
<APIParameters>
  <APIItem name="point" type="Point">
    The point to check.
  </APIItem>
  <APIItem name="at" type="At" optional>
    The location to check against. Defaults to current selection.
  </APIItem>
</APIParameters>

<APIReturns type="boolean">
  True if the point is an edge of the location, false otherwise.
</APIReturns>
</API>


### `isEditorEnd`

Check if selection is at editor end.

<API name="isEditorEnd">
<APIReturns type="boolean">
  True if the selection is at the editor end, false otherwise.
</APIReturns>
</API>

### `isEmpty`

Check if an element is empty, accounting for void nodes.

```ts
editor.api.isEmpty() // Check if editor is empty
editor.api.isEmpty(at) // Check if nodes at location are empty
editor.api.isEmpty(at, { after: true }) // Check if text after location is empty
editor.api.isEmpty(at, { block: true }) // Check if block above location is empty
```

<API name="isEmpty">
<APIParameters>
  <APIItem name="at" type="At | null" optional>
    The location to check for emptiness. Defaults to current selection.
  </APIItem>
  <APIItem name="options" type="EditorEmptyOptions" optional>
    Options for determining emptiness.
  </APIItem>
</APIParameters>
<APIOptions type="EditorEmptyOptions">
  <APIItem name="...options" type="QueryOptions<V>" optional />
  <APIItem name="after" type="boolean" optional>
    Check if text after selection is empty.
  </APIItem>
  <APIItem name="block" type="boolean" optional>
    Check if the block above location is empty.
  </APIItem>
</APIOptions>

<APIReturns type="boolean" />
</API>

### `isEnd`

Check if a point is the end point of a location.

<API name="isEnd">
<APIParameters>
  <APIItem name="point" type="Point">
    The point to check.
  </APIItem>
  <APIItem name="at" type="At" optional>
    The location to check against. Defaults to current selection.
  </APIItem>
</APIParameters>

<APIReturns type="boolean">
  True if the point is the end point of the location, false otherwise.
</APIReturns>
</API>

### `isExpanded`

Check if the selection is expanded (start and end points are different).

<API name="isExpanded">
<APIReturns type="boolean">
  True if the selection is expanded, false otherwise.
</APIReturns>
</API>

### `isNormalizing`

Check if the editor is currently normalizing after each operation.

<API name="isNormalizing">
<APIReturns type="boolean">
  True if the editor is currently normalizing, false otherwise.
</APIReturns>
</API>

### `isStart`

Check if a point is the start point of a location.

<API name="isStart">
<APIParameters>
  <APIItem name="point" type="Point">
    The point to check.
  </APIItem>
  <APIItem name="at" type="At" optional>
    The location to check against. Defaults to current selection.
  </APIItem>
</APIParameters>

<APIReturns type="boolean">
  True if the point is the start point of the location, false otherwise.
</APIReturns>
</API>

### `isSelected`

Check if a path is selected by the current selection.

<API name="isSelected">
<APIParameters>
  <APIItem name="target" type="Path | TRange">
    The path or range to check.
  </APIItem>
  <APIItem name="options" type="EditorIsSelectedOptions" optional>
    Options for checking selection.
  </APIItem>
</APIParameters>
<APIOptions type="EditorIsSelectedOptions">
  <APIItem name="contains" type="boolean" optional>
    Check if selection contains the entire path range.
  </APIItem>
</APIOptions>

<APIReturns type="boolean">
  True if the path is selected, false otherwise.
</APIReturns>
</API>

### `leaf`

Get the leaf text node at a location.

<API name="leaf">
<APIParameters>
  <APIItem name="at" type="At">
    The location to get the leaf from.
  </APIItem>
  <APIItem name="options" type="EditorLeafOptions" optional>
    Options for getting the leaf.
  </APIItem>
</APIParameters>
<APIOptions type="EditorLeafOptions">
  <APIItem name="depth" type="number" optional>
    The depth to traverse to find the leaf.
  </APIItem>
  <APIItem name="edge" type="LeafEdge" optional>
    Which edge of the location to get the leaf from (`'start' | 'end'`).
  </APIItem>
</APIOptions>

<APIReturns type="NodeEntry<TextIn<V>> | undefined">
  A tuple containing the leaf text node and its path, or undefined if not found.
</APIReturns>
</API>

### `levels`

Iterate through all levels at a location. This includes all ancestors up to the root editor node.

<API name="levels">
<APIOptions type="EditorLevelsOptions<V>">
  <APIItem name="...options" type="QueryOptions<V>" optional>
    Common query options for matching levels.
  </APIItem>
  <APIItem name="reverse" type="boolean" optional>
    Whether to traverse in reverse order (bottom-up vs. top-down).
  </APIItem>
  <APIItem name="voids" type="boolean" optional>
    Whether to include void nodes in the traversal.
  </APIItem>
</APIOptions>

<APIReturns type="Generator<NodeEntry<NodeIn<V>>, void, undefined>">
  A generator that yields tuples of [node, path] for each ancestor level.
</APIReturns>
</API>

### `last`

Get the last node at a location.

<API name="last">
<APIParameters>
  <APIItem name="at" type="At">
    The location to get the last node from.
  </APIItem>
  <APIItem name="options" type="EditorLastOptions" optional>
    Options for getting the last node.
  </APIItem>
</APIParameters>
<APIOptions type="EditorLastOptions">
  <APIItem name="level" type="number" optional>
    Get last node at this level (0-based).
  </APIItem>
</APIOptions>

<APIReturns type="NodeEntry<DescendantIn<V>> | undefined">
  A tuple containing the last node and its path, or undefined if not found.
</APIReturns>
</API>

### `mark`

Returns the selection mark value by key.

<API name="mark">
<APIParameters>
  <APIItem name="key" type="keyof MarksIn<V>">
    The mark key.
  </APIItem>
</APIParameters>

<APIReturns type="MarksIn<V>[K] | null | undefined">
  The mark value if it exists, null if not set, or undefined if multiple different values exist.
</APIReturns>
</API>

### `marks`

Get the marks that would be added to text at the current selection.

<API name="marks">
<APIReturns type="MarksIn<V> | null">
  The marks at the current selection, or null if there are no marks.
</APIReturns>
</API>

### `next`

Get the matching node in the branch of the document after a location.

<API name="next">
<APIOptions type="EditorNextOptions<V>">
  <APIItem name="...options" type="QueryOptions<V>" optional>
    Common query options for matching nodes.
  </APIItem>
  <APIItem name="at" type="At | Span" optional>
    The location to start searching from. Defaults to current selection.
  </APIItem>
  <APIItem name="mode" type="QueryMode" optional>
    Query mode for matching nodes.
  </APIItem>
  <APIItem name="voids" type="boolean" optional>
    Whether to include void nodes in the search.
  </APIItem>
  <APIItem name="from" type="'after' | 'child'" optional>
    - `'after'`: Start from point after current location
    - `'child'`: Start from the first child of current path
  </APIItem>
</APIOptions>

<APIReturns type="NodeEntry<DescendantIn<V>> | undefined">
  A tuple containing the next matching node and its path, or undefined if not found.
</APIReturns>
</API>


### `node`

Get the node at a location or find the first node that matches options.

<API name="node">
<APIParameters>
  <APIItem name="at" type="At" optional>
    The location to get a node from.
  </APIItem>
  <APIItem name="nodeOptions" type="EditorNodeOptions" optional>
    Options for getting a node.
  </APIItem>
</APIParameters>
<APIOptions type="EditorNodeOptions">
  <APIItem name="depth" type="number" optional>
    The depth to traverse to find the node.
  </APIItem>
  <APIItem name="edge" type="'start' | 'end'" optional>
    Which edge of the location to get the node from.
  </APIItem>
</APIOptions>

<APIReturns type="NodeEntry<NodeIn<V>> | undefined">
  A tuple containing the matching node and its path, or undefined if not found.
</APIReturns>
</API>

### `nodes`

Iterate through all nodes in the editor that match the given options.

<API name="nodes">
<APIOptions type="EditorNodesOptions<V>">
  <APIItem name="...options" type="QueryOptions<V>" optional>
    Common query options for matching nodes.
  </APIItem>
  <APIItem name="at" type="At | Span" optional>
    Where to start iterating. Defaults to editor selection.
  </APIItem>
  <APIItem name="ignoreNonSelectable" type="boolean" optional>
    Whether to ignore non-selectable nodes during traversal.
  </APIItem>
  <APIItem name="reverse" type="boolean" optional>
    Whether to traverse in reverse order.
  </APIItem>
  <APIItem name="universal" type="boolean" optional>
    Whether to ensure the operation works universally across all nodes.
  </APIItem>
  <APIItem name="mode" type="QueryMode" optional>
    - `'all'`: Return all matching nodes
    - `'highest'`: Return highest-level matching nodes
    - `'lowest'`: Return lowest-level matching nodes
  </APIItem>
  <APIItem name="voids" type="boolean" optional>
    Whether to include void nodes in the search.
  </APIItem>
</APIOptions>

<APIReturns type="Generator<NodeEntry<DescendantIn<V>>, void, undefined>">
  A generator that yields tuples of [node, path] for each matching node.
</APIReturns>
</API>

### `parent`

Get the parent node of a location.

<API name="parent">
<APIParameters>
  <APIItem name="at" type="At" optional>
    The location to get the parent from.
  </APIItem>
  <APIItem name="options" type="EditorParentOptions" optional>
    Options for getting the parent node.
  </APIItem>
</APIParameters>
<APIOptions type="EditorParentOptions">
  <APIItem name="depth" type="number" optional>
    Number of levels to traverse up to find the parent.
  </APIItem>
  <APIItem name="edge" type="'start' | 'end'" optional>
    Which edge of the location to get the parent from.
  </APIItem>
</APIOptions>

<APIReturns type="NodeEntry<AncestorIn<V>> | undefined">
  A tuple containing the parent node and its path, or undefined if not found.
</APIReturns>
</API>

### `previous`

Get the matching node in the branch of the document before a location.

<API name="previous">
<APIOptions type="EditorPreviousOptions<V>">
  <APIItem name="...options" type="QueryOptions<V>" optional>
    Common query options for matching nodes.
  </APIItem>
  <APIItem name="at" type="At | Span" optional>
    The location to start searching from. Defaults to current selection.
  </APIItem>
  <APIItem name="mode" type="QueryMode" optional>
    Query mode for matching nodes.
  </APIItem>
  <APIItem name="voids" type="boolean" optional>
    Whether to include void nodes in the search.
  </APIItem>
  <APIItem name="sibling" type="boolean" optional>
    Whether to get the previous sibling node instead of any previous node.
  </APIItem>
  <APIItem name="from" type="'before' | 'parent'" optional>
    - `'before'`: Start from point before current location
    - `'parent'`: Start from parent of current location
  </APIItem>
</APIOptions>

<APIReturns type="NodeEntry<DescendantIn<V>> | undefined">
  A tuple containing the previous matching node and its path, or undefined if not found.
</APIReturns>
</API>

### `prop`

Get a property value from a list of nodes. Returns `undefined` if the property value is not consistent across all nodes.

<API name="prop">
<APIOptions type="EditorPropOptions<V>">
  <APIItem name="nodes" type="TElement[]">
    The list of nodes to get the property value from.
  </APIItem>
  <APIItem name="key" type="string" optional>
    The property key to get from the nodes.
  </APIItem>
  <APIItem name="defaultValue" type="string" optional>
    Default value to return if property is not found.
  </APIItem>
  <APIItem name="getProp" type="(node: DescendantIn<V>) => any" optional>
    Custom function to extract property value from a node.
  </APIItem>
  <APIItem name="mode" type="'all' | 'block' | 'text'" optional>
    - `'all'`: Get property from all nodes
    - `'block'`: Get property from the first block node
    - `'text'`: Get property from the first text node
  </APIItem>
</APIOptions>

<APIReturns type="string | undefined">
  The consistent property value across all nodes, or `undefined` if values differ.
</APIReturns>
</API>

### `string`

Get the text string content of a location.

<API name="string">
<APIParameters>
  <APIItem name="at" type="At" optional>
    The location to get text content from. Defaults to current selection.
  </APIItem>
  <APIItem name="options" type="EditorStringOptions" optional>
    Options for getting text content.
  </APIItem>
</APIParameters>
<APIOptions type="EditorStringOptions">
  <APIItem name="voids" type="boolean" optional>
    Whether to include text content from void nodes.
  </APIItem>
</APIOptions>

<APIReturns type="string">
  The text content at the specified location.
</APIReturns>
</API>

### `void`

Match a void node in the current branch of the editor.

<API name="void">
<APIOptions type="EditorVoidOptions">
  <APIItem name="at" type="At" optional>
    The location to search from. Defaults to current selection.
  </APIItem>
  <APIItem name="mode" type="QueryMode" optional>
    Query mode for matching nodes.
  </APIItem>
  <APIItem name="voids" type="boolean" optional>
    Whether to include void nodes in the search.
  </APIItem>
</APIOptions>

<APIReturns type="NodeEntry<ElementIn<V>> | undefined">
  A tuple containing the void node and its path, or undefined if not found.
</APIReturns>
</API>

## Location

### `findPath`

Find the path of a Plate node in the editor.

<API name="findPath">
<APIParameters>
  <APIItem name="node" type="TNode">
    The node to find the path for in the editor tree.
  </APIItem>
  <APIItem name="options" type="EditorFindPathOptions" optional>
    Options for finding the node's path.
  </APIItem>
</APIParameters>
<APIOptions type="EditorFindPathOptions">
  <APIItem name="...options" type="QueryOptions<Value>" optional>
    Common query options for finding nodes.
  </APIItem>
  <APIItem name="ignoreNonSelectable" type="boolean" optional>
    Whether to ignore non-selectable nodes during traversal.
  </APIItem>
  <APIItem name="reverse" type="boolean" optional>
    Whether to traverse in reverse order.
  </APIItem>
  <APIItem name="universal" type="boolean" optional>
    Whether to ensure the operation works universally across all nodes.
  </APIItem>
  <APIItem name="mode" type="QueryMode" optional>
    Query mode for finding nodes.
  </APIItem>
  <APIItem name="voids" type="boolean" optional>
    Whether to include void nodes in the search.
  </APIItem>
</APIOptions>

<APIReturns type="Path | undefined">
  The path of the node if found, undefined otherwise.
</APIReturns>
</API>

### `path`

Get the path of a location.

<API name="path">
<APIParameters>
  <APIItem name="at" type="At" optional>
    The location to get the path from. Defaults to current selection.
  </APIItem>
</APIParameters>

<APIReturns type="Path">
  The path of the location.
</APIReturns>
</API>

### `point`

Get the `start` or `end` (default is `start`) point of a location.

<API name="point">
<APIParameters>
  <APIItem name="at" type="At" optional>
    The location to get the point from. Defaults to current selection.
  </APIItem>
  <APIItem name="options" type="EditorPointOptions" optional>
    Options for getting the point.
  </APIItem>
</APIParameters>
<APIOptions type="EditorPointOptions">
  <APIItem name="edge" type="'start' | 'end'" optional>
    Which edge of the location to get the point from.
  </APIItem>
</APIOptions>

<APIReturns type="Point">
  The point at the specified location and edge.
</APIReturns>
</API>

### `positions`

Iterate through all possible point positions in the document.

<API name="positions">
<APIOptions type="EditorPositionsOptions">
  <APIItem name="at" type="At" optional>
    Where to start iterating. Defaults to editor selection.
  </APIItem>
  <APIItem name="unit" type="TextUnitAdjustment" optional>
    - `'offset'`: Moves to the next offset Point
    - `'character'`: Moves to the next character
    - `'word'`: Moves to the position after the next word
    - `'line'` | 'block': Moves between block boundaries
  </APIItem>
  <APIItem name="reverse" type="boolean" optional>
    When true returns positions in reverse order.
  </APIItem>
  <APIItem name="voids" type="boolean" optional>
    Whether to include positions inside void nodes.
  </APIItem>
  <APIItem name="ignoreNonSelectable" type="boolean" optional>
    Whether to skip positions in non-selectable nodes.
  </APIItem>
</APIOptions>

<APIReturns type="Generator<Point, void, undefined>">
  A generator that yields each valid point position in the document.
</APIReturns>
</API>

### `nodesRange`

Returns the range spanning the given node entries.

<API name="nodesRange">
<APIParameters>
  <APIItem name="nodes" type="NodeEntry[]">
    The node entries to get the range for.
  </APIItem>
</APIParameters>

<APIReturns type="TRange | undefined">
  The range spanning the nodes, or undefined if no valid range can be created.
</APIReturns>
</API>

### `range`

Create a range between two locations.

<API name="range">
<APIOptions type="EditorRangeOptions">
  <APIItem name="at" type="At" optional>
    The location to create the range at. Defaults to current selection.
  </APIItem>
  <APIItem name="focus" type="Point" optional>
    The focus (end) point of the range.
  </APIItem>
  <APIItem name="anchor" type="Point" optional>
    The anchor (start) point of the range.
  </APIItem>
</APIOptions>

<APIReturns type="TRange">
  A new range between the specified points.
</APIReturns>
</API>

### `start`

Get the start point of a location.

<API name="start">
<APIParameters>
  <APIItem name="at" type="At" optional>
    The location to get the start point from.
  </APIItem>
  <APIItem name="options" type="EditorStartOptions" optional>
    Options for getting the start point.
  </APIItem>
</APIParameters>
<APIOptions type="EditorStartOptions">
  <APIItem name="next" type="boolean" optional>
    Get the start point of the next node instead of the current one.
  </APIItem>
</APIOptions>

<APIReturns type="Point">
  The start point of the location.
</APIReturns>
</API>

### `unhangRange`

Convert a range into a non-hanging one.

A "hanging" range is one created by the browser's "triple-click" selection behavior. When triple-clicking a block, the browser selects from the start of that block to the start of the _next_ block. The range thus "hangs over" into the next block. If `unhangRange` is given such a range, it moves the end backwards until it's in a non-empty text node that precedes the hanging block.

Note that `unhangRange` is designed for the specific purpose of fixing triple-clicked blocks, and therefore currently has a number of caveats:

- It does not modify the start of the range; only the end. For example, it does not "unhang" a selection that starts at the end of a previous block.
- It only does anything if the start block is fully selected. For example, it does not handle ranges created by double-clicking the end of a paragraph (which browsers treat by selecting from the end of that paragraph to the start of the next).

<API name="unhangRange">
<APIParameters>
  <APIItem name="range" type="TRange">
    The range to unhang.
  </APIItem>
  <APIItem name="options" type="EditorUnhangRangeOptions" optional>
    Options for un-hanging the range.
  </APIItem>
</APIParameters>
<APIOptions type="EditorUnhangRangeOptions">
  <APIItem name="voids" type="boolean" optional>
    Allow placing the end of the selection in a void node.
  </APIItem>
</APIOptions>

<APIReturns type="TRange">
  A new range with the end point moved backwards if it was hanging.
</APIReturns>
</API>

## Element

### `elementReadOnly`

Check if an element is read-only.

<API name="elementReadOnly">
<APIParameters>
  <APIItem name="element" type="ElementIn<V>">
    The element to check for read-only status.
  </APIItem>
</APIParameters>

<APIReturns type="boolean">
  True if the element is read-only, false otherwise.
</APIReturns>
</API>

### `isBlock`

Check if a value is a block `Element` object.

<API name="isBlock">
<APIParameters>
  <APIItem name="value" type="any">
    The value to check.
  </APIItem>
</APIParameters>

<APIReturns type="boolean">
  True if the value is a block element, false otherwise.
</APIReturns>
</API>

### `isInline`

Check if a value is an inline `Element` object.

<API name="isInline">
<APIParameters>
  <APIItem name="element" type="DescendantIn<V>">
    The element to check.
  </APIItem>
</APIParameters>

<APIReturns type="boolean">
  True if the element is inline, false otherwise.
</APIReturns>
</API>

### `isSelectable`

Check if a value is a selectable `Element` object.

<API name="isSelectable">
<APIParameters>
  <APIItem name="element" type="ElementIn<V>">
    The element to check.
  </APIItem>
</APIParameters>

<APIReturns type="boolean">
  True if the element is selectable, false otherwise.
</APIReturns>
</API>

### `isVoid`

Check if an element is void.

<API name="isVoid">
<APIParameters>
  <APIItem name="element" type="ElementIn<V>">
    The element to check for void status.
  </APIItem>
</APIParameters>

<APIReturns type="boolean">
  True if the element is void, false otherwise.
</APIReturns>
</API>

### `markableVoid`

Check if an element is a markable void element.

<API name="markableVoid">
<APIParameters>
  <APIItem name="element" type="ElementIn<V>">
    The element to check for markable void status.
  </APIItem>
</APIParameters>

<APIReturns type="boolean">
  True if the element is a markable void element, false otherwise.
</APIReturns>
</API>

## Ref

### `pathRef`

Create a mutable ref for a `Path`.

<API name="pathRef">
<APIParameters>
  <APIItem name="path" type="Path">
    The path to reference.
  </APIItem>
  <APIItem name="options" type="EditorPathRefOptions" optional>
    Options for the path reference.
  </APIItem>
</APIParameters>
<APIOptions type="EditorPathRefOptions">
  <APIItem name="affinity" type="TextDirection | null" optional>
    The direction to resolve the ref when ambiguous:
    - `'forward'`: Resolve to the next valid position
    - `'backward'`: Resolve to the previous valid position
    - `null`: Do not resolve to any position
  </APIItem>
</APIOptions>

<APIReturns type="PathRef">
  A mutable reference that updates its path as operations are applied to the editor.
</APIReturns>
</API>

### `pathRefs`

Get the set of currently tracked path refs of the editor.

<API name="pathRefs">
<APIReturns type="Set<PathRef>">
  The set of tracked path refs.
</APIReturns>
</API>

### `pointRef`

Create a mutable ref for a `Point`.

<API name="pointRef">
<APIParameters>
  <APIItem name="point" type="Point">
    The point to reference.
  </APIItem>
  <APIItem name="options" type="EditorPointRefOptions" optional>
    Options for the point reference.
  </APIItem>
</APIParameters>
<APIOptions type="EditorPointRefOptions">
  <APIItem name="affinity" type="TextDirection | null" optional>
    The direction to resolve the ref when ambiguous:
    - `'forward'`: Resolve to the next valid position
    - `'backward'`: Resolve to the previous valid position
    - `null`: Do not resolve to any position
  </APIItem>
</APIOptions>

<APIReturns type="PointRef">
  A mutable reference that updates its point as operations are applied to the editor.
</APIReturns>
</API>

### `pointRefs`

Get the set of currently tracked point refs of the editor.

<API name="pointRefs">
<APIReturns type="Set<PointRef>">
  The set of tracked point refs.
</APIReturns>
</API>

### `rangeRef`

Create a mutable ref for a `Range`.

<API name="rangeRef">
<APIParameters>
  <APIItem name="range" type="TRange">
    The range to reference.
  </APIItem>
  <APIItem name="options" type="EditorRangeRefOptions" optional>
    Options for the range reference.
  </APIItem>
</APIParameters>
<APIOptions type="EditorRangeRefOptions">
  <APIItem name="affinity" type="RangeDirection | null" optional>
    The direction to resolve the ref when ambiguous:
    - `'forward'`: Resolve both points forward
    - `'backward'`: Resolve both points backward
    - `'outward'`: Resolve start backward and end forward
    - `'inward'`: Resolve start forward and end backward
    - `null`: Do not resolve to any position
  </APIItem>
</APIOptions>

<APIReturns type="RangeRef">
  A mutable reference that updates its range as operations are applied to the editor.
</APIReturns>
</API>

### `rangeRefs`

Get the set of currently tracked range refs of the editor.

<API name="rangeRefs">
<APIReturns type="Set<RangeRef>">
  The set of tracked range refs.
</APIReturns>
</API>

## DOM

### `findDocumentOrShadowRoot`

Find the document or shadow root from the editor.

<API name="findDocumentOrShadowRoot">
<APIReturns type="Document | ShadowRoot">
  The document or shadow root containing the editor.
</APIReturns>
</API>

### `findEventRange`

Get the target range from a DOM event.

<API name="findEventRange">
<APIParameters>
  <APIItem name="event" type="Event">
    The DOM event to get the range from.
  </APIItem>
</APIParameters>

<APIReturns type="TRange | null">
  The range at the event target, or null if no valid range found.
</APIReturns>
</API>

### `findKey`

Find a key for a Plate node. Returns an instance of `Key` which looks like `{ id: string }`.

<API name="findKey">
<APIParameters>
  <APIItem name="node" type="TNode">
    The node to find the key for.
  </APIItem>
</APIParameters>

<APIReturns type="Key">
  The key associated with the node.
</APIReturns>
</API>

### `getWindow`

Get the window object from the editor.

<API name="getWindow">
<APIReturns type="Window">
  The window object associated with the editor.
</APIReturns>
</API>

### `hasDOMNode`

Check if a DOM node is within the editor.

<API name="hasDOMNode">
<APIParameters>
  <APIItem name="target" type="Node">
    The DOM node to check.
  </APIItem>
  <APIItem name="options" type="object" optional>
    Options for checking the DOM node.
  </APIItem>
</APIParameters>
<APIOptions type="object">
  <APIItem name="editable" type="boolean" optional>
    Whether to check if the node is in an editable element.
  </APIItem>
</APIOptions>

<APIReturns type="boolean">
  True if the DOM node is within the editor, false otherwise.
</APIReturns>
</API>

### `hasEditableTarget`

Check if a DOM target is editable.

<API name="hasEditableTarget">
<APIParameters>
  <APIItem name="target" type="EventTarget | null">
    The DOM target to check.
  </APIItem>
</APIParameters>

<APIReturns type="target is Node">
  True if the target is editable, false otherwise.
</APIReturns>
</API>

### `hasRange`

Check if the editor has a range.

<API name="hasRange">
<APIParameters>
  <APIItem name="range" type="TRange">
    The range to check.
  </APIItem>
</APIParameters>

<APIReturns type="boolean">
  True if the editor has the specified range, false otherwise.
</APIReturns>
</API>

### `hasSelectableTarget`

Check if a DOM target is selectable.

<API name="hasSelectableTarget">
<APIParameters>
  <APIItem name="target" type="EventTarget | null">
    The DOM target to check.
  </APIItem>
</APIParameters>

<APIReturns type="target is Node">
  True if the target is selectable, false otherwise.
</APIReturns>
</API>

### `hasTarget`

Check if a DOM target exists.

<API name="hasTarget">
<APIParameters>
  <APIItem name="target" type="EventTarget | null">
    The DOM target to check.
  </APIItem>
</APIParameters>

<APIReturns type="target is Node">
  True if the target exists, false otherwise.
</APIReturns>
</API>

### `isComposing`

Check if the user is currently composing inside the editor.

<API name="isComposing">
<APIReturns type="boolean">
  True if the user is currently composing text, false otherwise.
</APIReturns>
</API>

### `isFocused`

Check if the editor is focused.

<API name="isFocused">
<APIReturns type="boolean">
  True if the editor has focus, false otherwise.
</APIReturns>
</API>

### `isReadOnly`

Check if the editor is in read-only mode.

<API name="isReadOnly">
<APIReturns type="boolean">
  True if the editor is read-only, false otherwise.
</APIReturns>
</API>

### `toDOMNode`

Find the native DOM element from a Plate node.

<API name="toDOMNode">
<APIOptions type="TNode">
  <APIItem name="node" type="TNode">
    The Plate node to convert to a DOM element.
  </APIItem>
</APIOptions>

<APIReturns type="HTMLElement">
  The corresponding DOM element for the Plate node.
</APIReturns>
</API>

### `toDOMPoint`

Find a native DOM selection point from a Plate point.

<API name="toDOMPoint">
<APIOptions type="Point">
  <APIItem name="point" type="Point">
    The Plate point to convert to a DOM point.
  </APIItem>
</APIOptions>

<APIReturns type="DOMPoint">
  A tuple of [node, offset] representing the DOM point.
</APIReturns>
</API>

### `toDOMRange`

Find a native DOM range from a Plate range.

<API name="toDOMRange">
<APIOptions type="TRange">
  <APIItem name="range" type="TRange">
    The Plate range to convert to a DOM range.
  </APIItem>
</APIOptions>

<APIReturns type="DOMRange">
  The corresponding DOM range for the Plate range.
</APIReturns>
</API>

### `toSlateNode`

Find a Plate node from a native DOM element.

<API name="toSlateNode">
<APIOptions type="DOMNode">
  <APIItem name="domNode" type="DOMNode">
    The DOM node to convert to a Plate node.
  </APIItem>
</APIOptions>

<APIReturns type="TNode | undefined">
  The corresponding Plate node if found, undefined otherwise.
</APIReturns>
</API>

### `toSlatePoint`

Find a Plate point from a DOM selection point.

<API name="toSlatePoint">
<APIOptions type="DOMPoint">
  <APIItem name="domPoint" type="DOMPoint">
    The DOM point to convert to a Plate point.
  </APIItem>
</APIOptions>

<APIReturns type="Point | undefined">
  The corresponding Plate point if found, undefined otherwise.
</APIReturns>
</API>

### `toSlateRange`

Find a Plate range from a DOM range.

<API name="toSlateRange">
<APIOptions type="DOMRange">
  <APIItem name="domRange" type="DOMRange">
    The DOM range to convert to a Plate range.
  </APIItem>
</APIOptions>

<APIReturns type="TRange | undefined">
  The corresponding Plate range if found, undefined otherwise.
</APIReturns>
</API>

## Callback

### `onChange`

Called when there is a change in the editor.

<API name="onChange">
<APIOptions type="object">
  <APIItem name="operation" type="Operation" optional>
    The operation that triggered the change.
  </APIItem>
</APIOptions>
</API>

## Core

### `getDirtyPaths`

Get the paths that need to be normalized after an operation.

<API name="getDirtyPaths">
<APIParameters>
  <APIItem name="operation" type="Operation<N extends DescendantIn<V>>">
    The operation that triggered normalization.
  </APIItem>
</APIParameters>

<APIReturns type="Path[]">
  An array of paths that need to be normalized after the operation.
</APIReturns>
</API>

### `shouldMergeNodes`

Decide whether two adjacent node entries should merge. Plate calls this before
`editor.tf.mergeNodes()` applies a merge operation.

<API name="shouldMergeNodes">
<APIParameters>
  <APIItem name="prevNodeEntry" type="NodeEntry">
    Previous node entry at the merge boundary.
  </APIItem>
  <APIItem name="nextNodeEntry" type="NodeEntry">
    Next node entry at the merge boundary.
  </APIItem>
  <APIItem name="options" type="{ reverse?: boolean }" optional>
    Merge direction metadata.
  </APIItem>
</APIParameters>

<APIReturns type="boolean">
  True when the nodes should merge, false when the merge should stop.
</APIReturns>
</API>

### `shouldNormalizeNode`

Override this method to prevent normalizing a specific node. Defaults to returning `true`.

<API name="shouldNormalizeNode">
<APIParameters>
  <APIItem name="entry" type="NodeEntry">
    The node entry (node and path) to check.
  </APIItem>
</APIParameters>

<APIReturns type="boolean">
  True if the node should be normalized, false otherwise.
</APIReturns>
</API>

### `setNormalizing`

Manually control the editor's normalizing state.

<API name="setNormalizing">
<APIOptions type="boolean">
  <APIItem name="isNormalizing" type="boolean">
    Whether the editor should normalize after each operation.
  </APIItem>
</APIOptions>
</API>

### `shouldNormalize`

Controls whether the editor should normalize after an operation. Override this method to prevent normalizing in certain situations.

<API name="shouldNormalize">
<APIOptions type="object">
  <APIItem name="dirtyPaths" type="Path[]">
    The paths that need to be normalized.
  </APIItem>
  <APIItem name="initialDirtyPathsLength" type="number">
    The initial number of dirty paths before normalization started.
  </APIItem>
  <APIItem name="iteration" type="number">
    The current normalization iteration count.
  </APIItem>
  <APIItem name="operation" type="Operation" optional>
    The operation that triggered the normalization.
  </APIItem>
</APIOptions>

<APIReturns type="boolean">
  True if the editor should normalize, false otherwise.
</APIReturns>
</API>

## History

### `isMerging`

Get the merge flag's current value.

<API name="isMerging">
<APIReturns type="boolean">
  True if the editor is currently merging operations, false otherwise.
</APIReturns>
</API>

### `isSaving`

Get the saving flag's current value.

<API name="isSaving">
<APIReturns type="boolean">
  True if the editor is currently saving, false otherwise.
</APIReturns>
</API>

### `isSplittingOnce`

Get the splitting flag's current value.

<API name="isSplittingOnce">
<APIReturns type="boolean">
  True if the editor is currently performing a single split operation, false otherwise.
</APIReturns>
</API>

## Utils

### `create.block`

Default block factory for creating new block elements.

<API name="create.block">
<APIParameters>
  <APIItem name="node" type="Partial<TElement>" optional>
    Partial element properties to merge into the new block.
  </APIItem>
  <APIItem name="path" type="Path" optional>
    Path for the new block.
  </APIItem>
</APIParameters>

<APIReturns type="TElement">
  A new block element.
</APIReturns>
</API>

### `create.value`

Default value factory for creating new editor values.

<API name="create.value">
<APIReturns type="Value">
  A new editor value.
</APIReturns>
</API>


# Editor Transforms

Source: https://platejs.org/docs/api/slate/editor-transforms

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Editor Transforms
description: API reference for editor transformation operations in Plate.
---

Transforms are helper functions that manipulate a Plate document.

## Node Operations

### `duplicateNodes`

Duplicates nodes at a location and inserts them after that location.

<API name="duplicateNodes">
<APIOptions type="DuplicateNodesOptions">
  <APIItem name="...options" type="InsertNodesOptions" optional>
    `insertNodes` options.
  </APIItem>
  <APIItem name="at" type="At" optional>
    Location to duplicate from and insert after. Defaults to selection.
  </APIItem>
  <APIItem name="block" type="boolean" optional>
    If true, duplicates blocks above location. Ignored if `nodes` provided.
  </APIItem>
  <APIItem name="nodes" type="NodeEntry[]" optional>
    Specific nodes to duplicate. Takes precedence over `block`.
  </APIItem>
</APIOptions>
</API>

### `insertFragment`

Insert a fragment of nodes at a location.

<API name="insertFragment">
<APIParameters>
  <APIItem name="fragment" type="N[]">
    Fragment of nodes to insert.
  </APIItem>
  <APIItem name="options" type="InsertFragmentOptions" optional />
</APIParameters>

<APIOptions type="InsertFragmentOptions">
  <APIItem name="at" type="At" optional>
    Location to insert at. Defaults to selection.
  </APIItem>
  <APIItem name="hanging" type="boolean" optional>
    Whether range is hanging.
  </APIItem>
  <APIItem name="voids" type="boolean" optional>
    Allow insertion in void nodes.
  </APIItem>
</APIOptions>
</API>

### `insertNode`

Insert a single node atomically.

<API name="insertNode">
<APIParameters>
  <APIItem name="node" type="N">
    Node to insert.
  </APIItem>
  <APIItem name="options" type="InsertNodesOptions" optional />
</APIParameters>
</API>

### `insertNodes`

Insert one or more nodes atomically.

<API name="insertNodes">
<APIParameters>
  <APIItem name="nodes" type="N | N[]">
    Node(s) to insert.
  </APIItem>
  <APIItem name="options" type="InsertNodesOptions" optional />
</APIParameters>

<APIOptions type="InsertNodesOptions">
  <APIItem name="...options" type="QueryOptions" optional>
    Common query options.
  </APIItem>
  <APIItem name="batchDirty" type="boolean" optional />
  <APIItem name="hanging" type="boolean" optional />
  <APIItem name="nextBlock" type="boolean" optional>
    Insert after the current block if `removeEmpty` caused it to be removed.
  </APIItem>
  <APIItem name="removeEmpty" type="QueryNodeOptions | boolean" optional>
    Remove the current block if empty. Defaults to removing an empty paragraph, but can be customized.
  </APIItem>
  <APIItem name="select" type="boolean" optional>
    Select inserted nodes.
  </APIItem>
  <APIItem name="voids" type="boolean" optional>
    Allow insertion in void nodes.
  </APIItem>
</APIOptions>
</API>

### `liftNodes`

Lift nodes at the specified location upwards in the document tree. If necessary, the parent node is split.

<API name="liftNodes">
<APIOptions type="LiftNodesOptions">
  <APIItem name="...options" type="QueryOptions" optional />
  <APIItem name="mode" type="'highest' | 'lowest'" optional />
  <APIItem name="voids" type="boolean" optional />
</APIOptions>
</API>

### `mergeNodes`

Merge a node at the specified location with the previous node at the same depth. Resulting empty container nodes are removed.

<API name="mergeNodes">
<APIOptions type="MergeNodesOptions">
  <APIItem name="...options" type="QueryOptions" optional />
  <APIItem name="hanging" type="boolean" optional />
</APIOptions>
</API>

### `moveNodes`

Move the nodes from an origin to a destination.

<API name="moveNodes">
<APIOptions type="MoveNodesOptions">
  <APIItem name="...options" type="QueryOptions" optional />
  <APIItem name="to" type="Path">
    Destination path.
  </APIItem>
  <APIItem name="children" type="boolean" optional>
    Move only children of the node at the location.
  </APIItem>
  <APIItem name="fromIndex" type="number" optional>
    Start index of the children to move. Default is 0.
  </APIItem>
  <APIItem name="mode" type="'highest' | 'lowest'" optional />
  <APIItem name="voids" type="boolean" optional />
</APIOptions>
</API>

### `removeNodes`

Remove nodes at a location.

<API name="removeNodes">
<APIOptions type="RemoveNodesOptions">
  <APIItem name="...options" type="QueryOptions" optional />
  <APIItem name="children" type="boolean" optional>
    When true, remove all children of the node at the specified location.
  </APIItem>
  <APIItem name="hanging" type="boolean" optional />
  <APIItem name="previousEmptyBlock" type="boolean" optional>
    Remove the previous empty block if it exists.
  </APIItem>
  <APIItem name="mode" type="'highest' | 'lowest'" optional />
  <APIItem name="voids" type="boolean" optional />
</APIOptions>
</API>

### `replaceNodes`

Replace nodes at a location with new nodes.

<API name="replaceNodes">
<APIParameters>
  <APIItem name="nodes" type="N | N[]">
    The new node(s) to insert.
  </APIItem>
  <APIItem name="options" type="ReplaceNodesOptions" optional />
</APIParameters>

<APIOptions type="ReplaceNodesOptions">
  <APIItem name="...options" type="InsertNodesOptions" optional>
    `insertNodes` options.
  </APIItem>
  <APIItem name="children" type="boolean" optional>
    Replace all children of the node at the specified location instead of the node itself.
  </APIItem>
  <APIItem name="removeNodes" type="Omit<RemoveNodesOptions, 'at'>" optional>
    Options for removing nodes before the replacement.
  </APIItem>
</APIOptions>
</API>

### `reset`

Reset the editor state including history, selection and children.

<API name="reset">
<APIOptions type="ResetOptions">
  <APIItem name="...options" type="ReplaceNodesOptions" optional>
    `replaceNodes` options.
  </APIItem>
  <APIItem name="children" type="boolean" optional>
    When true, only reset the children without clearing history/operations.
  </APIItem>
</APIOptions>
</API>

### `setNodes`

Set properties on nodes.

<API name="setNodes">
<APIParameters>
  <APIItem name="props" type="Partial<NodeProps<N>>">
    Properties to set. Use `undefined` to unset.
  </APIItem>
  <APIItem name="options" type="SetNodesOptions" optional />
</APIParameters>

<APIOptions type="SetNodesOptions">
  <APIItem name="...options" type="QueryOptions" optional />
  <APIItem name="compare" type="(prop: Partial<Descendant>, node: Partial<Descendant>) => boolean" optional />
  <APIItem name="hanging" type="boolean" optional />
  <APIItem name="marks" type="boolean" optional>
    When true, only apply to text nodes in non-void or markable void nodes.
  </APIItem>
  <APIItem name="merge" type="(prop: Partial<Descendant>, node: Partial<Descendant>) => object" optional />
  <APIItem name="mode" type="'highest' | 'lowest'" optional />
  <APIItem name="split" type="boolean" optional />
  <APIItem name="voids" type="boolean" optional />
</APIOptions>
</API>

### `splitNodes`

Split nodes at a location.

<API name="splitNodes">
<APIOptions type="SplitNodesOptions">
  <APIItem name="...options" type="QueryOptions" optional />
  <APIItem name="always" type="boolean" optional />
  <APIItem name="height" type="number" optional />
  <APIItem name="mode" type="'highest' | 'lowest'" optional />
  <APIItem name="voids" type="boolean" optional />
</APIOptions>
</API>

### `toggleBlock`

Toggle the block type at a location.

<API name="toggleBlock">
<APIParameters>
  <APIItem name="type" type="string">
    The block type to toggle.
  </APIItem>
  <APIItem name="options" type="ToggleBlockOptions" optional />
</APIParameters>

<APIOptions type="ToggleBlockOptions">
  <APIItem name="...options" type="SetNodesOptions" optional>
    Options to pass to `setNodes`.
  </APIItem>
  <APIItem name="defaultType" type="string" optional>
    The default block type when untoggling. Defaults to paragraph.
  </APIItem>
  <APIItem name="someOptions" type="EditorNodesOptions" optional>
    Options for determining if the block is active.
  </APIItem>
  <APIItem name="wrap" type="boolean" optional>
    If true, toggles wrapping with `type`. Otherwise, sets the block type directly.
  </APIItem>
</APIOptions>
</API>

### `unsetNodes`

Remove properties from nodes.

<API name="unsetNodes">
<APIParameters>
  <APIItem name="props" type="string | string[]">
    Property key(s) to remove.
  </APIItem>
  <APIItem name="options" type="UnsetNodesOptions" optional />
</APIParameters>

<APIOptions type="UnsetNodesOptions">
  <APIItem name="...options" type="QueryOptions" optional />
  <APIItem name="hanging" type="boolean" optional />
  <APIItem name="mode" type="'highest' | 'lowest'" optional />
  <APIItem name="split" type="boolean" optional />
  <APIItem name="voids" type="boolean" optional />
</APIOptions>
</API>

### `unwrapNodes`

Unwrap a node at a location. If necessary, the parent node is split.

<API name="unwrapNodes">
<APIOptions type="UnwrapNodesOptions">
  <APIItem name="...options" type="QueryOptions" optional />
  <APIItem name="hanging" type="boolean" optional />
  <APIItem name="split" type="boolean" optional />
  <APIItem name="mode" type="'highest' | 'lowest'" optional />
  <APIItem name="voids" type="boolean" optional />
</APIOptions>
</API>

### `wrapNodes`

Wrap nodes at a location in the `element` container.

<API name="wrapNodes">
<APIParameters>
  <APIItem name="element" type="N">
    The wrapper element.
  </APIItem>
  <APIItem name="options" type="WrapNodesOptions" optional />
</APIParameters>

<APIOptions type="WrapNodesOptions">
  <APIItem name="...options" type="QueryOptions" optional />
  <APIItem name="children" type="boolean" optional>
    When true, wrap all children into a single container element.
  </APIItem>
  <APIItem name="hanging" type="boolean" optional />
  <APIItem name="mode" type="'highest' | 'lowest'" optional />
  <APIItem name="split" type="boolean" optional />
  <APIItem name="voids" type="boolean" optional />
</APIOptions>
</API>

## Text Operations

### `delete`

Delete text at a location.

<API name="delete">
<APIOptions type="DeleteTextOptions">
  <APIItem name="at" type="At" optional />
  <APIItem name="distance" type="number" optional>
    Number of characters (or other unit) to delete. Default is 1.
  </APIItem>
  <APIItem name="hanging" type="boolean" optional />
  <APIItem name="reverse" type="boolean" optional>
    If true, delete backward.
  </APIItem>
  <APIItem name="unit" type="'character' | 'word' | 'line' | 'block'" optional>
    Unit to delete by.
  </APIItem>
  <APIItem name="voids" type="boolean" optional />
</APIOptions>
</API>

### `deleteBackward`

Delete text backward.

<API name="deleteBackward">
<APIParameters>
  <APIItem name="unit" type="'character' | 'word' | 'line' | 'block'" optional>
    Defaults to `'character'`.
  </APIItem>
</APIParameters>
</API>

### `deleteForward`

Delete text forward.

<API name="deleteForward">
<APIParameters>
  <APIItem name="unit" type="'character' | 'word' | 'line' | 'block'" optional>
    Defaults to `'character'`.
  </APIItem>
</APIParameters>
</API>

### `deleteFragment`

Delete a fragment of nodes.

<API name="deleteFragment">
<APIOptions type="EditorFragmentDeletionOptions">
  <APIItem name="direction" type="'forward' | 'backward'" optional>
    Direction to delete.
  </APIItem>
</APIOptions>
</API>

### `insertText`

Insert text at a location, optionally with marks. The behavior depends on the provided options:

1. If `at` is specified in options, inserts at that location regardless of selection
2. Otherwise, if there's a selection:
   - If `marks` is true (default) and editor has marks, inserts text with those marks
   - If no marks, inserts plain text
3. If neither `at` nor selection exists, no text is inserted

<API name="insertText">
<APIParameters>
  <APIItem name="text" type="string">
    Text to insert.
  </APIItem>
  <APIItem name="options" type="InsertTextOptions" optional />
</APIParameters>

<APIOptions type="InsertTextOptions">
  <APIItem name="at" type="TLocation" optional>
    Location to insert text at. Takes precedence over current selection.
  </APIItem>
  <APIItem name="voids" type="boolean" optional>
    Whether to allow insertion in void nodes.
  </APIItem>
  <APIItem name="marks" type="boolean" optional>
    - **Default:** `true`
    When true and editor has marks, the inserted text will include those marks.
    When false, inserts plain text without marks.
  </APIItem>
</APIOptions>
</API>

### `insertBreak`

Insert a block break at the current selection.

### `insertSoftBreak`

Insert a soft break at the current selection. A soft break is a new line in the current block.

### `deselect`

Unset the selection.

### `move`

Move the selection's point forward or backward.

<API name="move">
<APIOptions type="object">
  <APIItem name="distance" type="number" optional>
    How many units to move. Defaults to 1.
  </APIItem>
  <APIItem name="unit" type="'offset' | 'character' | 'word' | 'line'" optional>
    Defaults to `'character'`.
  </APIItem>
  <APIItem name="reverse" type="boolean" optional>
    Move backward if true.
  </APIItem>
  <APIItem name="edge" type="'anchor' | 'focus' | 'start' | 'end'" optional>
    Which edge to move.
  </APIItem>
</APIOptions>
</API>

## Mark Operations

### `addMark`

Add a custom property to the leaf text nodes within non-void nodes or void nodes that `editor.markableVoid()` allows in the current selection. If the selection is currently collapsed, the marks will be added to the `editor.marks` property instead, and applied when text is inserted next.

<API name="addMark">
<APIParameters>
  <APIItem name="key" type="string">
    Mark key to add.
  </APIItem>
  <APIItem name="value" type="any">
    Value for the mark.
  </APIItem>
</APIParameters>
</API>

### `addMarks`

Add multiple marks to the current selection.

```ts
editor.tf.addMarks({ bold: true, italic: true })
editor.tf.addMarks({ bold: subscript }, { remove: 'superscript' })
editor.tf.addMarks({ bold: true }, { remove: ['italic', 'underline'] })
```

<API name="addMarks">
<APIParameters>
  <APIItem name="marks" type="Record<string, any>">
    Key-value pairs of mark props.
  </APIItem>
  <APIItem name="options" type="AddMarksOptions" optional />
</APIParameters>

<APIOptions type="AddMarksOptions">
  <APIItem name="remove" type="string[] | string" optional>
    Mark keys to remove first. For mutually exclusive marks, e.g. subscript/superscript.
  </APIItem>
</APIOptions>
</API>

### `removeMark`

Remove a mark from text in the selection.

<API name="removeMark">
<APIParameters>
  <APIItem name="key" type="string">
    Mark key to remove.
  </APIItem>
</APIParameters>
</API>

### `removeMarks`

Remove marks from text nodes in the current selection or from `editor.marks`. The behavior depends on the selection state and options:

1. If selection is expanded or is in a markable void node:
   - Remove specified mark keys from text nodes
2. If selection is collapsed and no custom range provided:
   - Remove specified keys from `editor.marks`
   - If no keys specified, clear all marks from `editor.marks`
3. If custom range provided (`at` option):
   - Only remove marks from text nodes in that range

```ts
editor.tf.removeMarks()             // remove all marks
editor.tf.removeMarks('bold')       // remove the 'bold' mark
editor.tf.removeMarks(['bold','italic'])
editor.tf.removeMarks('bold', { at: range })
```

<API name="removeMarks">
<APIParameters>
  <APIItem name="keys" type="string | string[]" optional>
    Mark key(s) to remove. If not provided and selection is collapsed, clears all marks from `editor.marks`.
  </APIItem>
  <APIItem name="options" type="RemoveMarksOptions" optional />
</APIParameters>

<APIOptions type="RemoveMarksOptions">
  <APIItem name="...options" type="UnsetNodesOptions" optional />
  <APIItem name="at" type="TRange" optional>
    Custom range to remove marks from. Takes precedence over current selection.
  </APIItem>
  <APIItem name="shouldChange" type="boolean" optional>
    - **Default:** `true`
    Whether to trigger onChange when modifying editor.marks.
  </APIItem>
  <APIItem name="split" type="boolean" optional>
    Whether to split nodes when removing marks.
  </APIItem>
  <APIItem name="match" type="(node: Node, path: Path) => boolean" optional>
    Custom function to filter which nodes to remove marks from.
  </APIItem>
  <APIItem name="voids" type="boolean" optional>
    Whether to allow removing marks from void nodes.
  </APIItem>
</APIOptions>
</API>

### `toggleMark`

Toggle a mark on or off in the current selection. If the mark exists, removes it. If it doesn't exist:
1. Removes any specified marks in the `remove` option 
2. Adds the mark with value `true`

```ts
editor.tf.toggleMark('bold')                                // Toggle bold on/off
editor.tf.toggleMark('subscript', { remove: 'superscript'}) // Remove superscript before adding subscript
```

<API name="toggleMark">
<APIParameters>
  <APIItem name="key" type="string">
    The mark key to toggle.
  </APIItem>
  <APIItem name="options" type="ToggleMarkOptions" optional />
</APIParameters>

<APIOptions type="ToggleMarkOptions">
  <APIItem name="remove" type="string[] | string" optional>
    Mark key(s) to remove before adding the mark. Useful for mutually exclusive marks like subscript/superscript.
    The specified mark key is always removed in addition to these marks.
  </APIItem>
</APIOptions>
</API>

## Selection

### `collapse`

Collapse the selection to a point.

<API name="collapse">
<APIOptions type="object">
  <APIItem name="edge" type="'anchor' | 'focus' | 'start' | 'end'" optional>
    Edge to collapse to. Defaults to `'anchor'`.
  </APIItem>
</APIOptions>
</API>

### `deselect`

Unset the current selection.

### `move`

Move the selection's point.

<API name="move">
<APIOptions type="object">
  <APIItem name="distance" type="number" optional>
    Defaults to 1.
  </APIItem>
  <APIItem name="unit" type="'offset' | 'character' | 'word' | 'line'" optional>
    Defaults to `'character'`.
  </APIItem>
  <APIItem name="reverse" type="boolean" optional>
    If true, move backward.
  </APIItem>
  <APIItem name="edge" type="'anchor' | 'focus' | 'start' | 'end'" optional>
    Which edge to move.
  </APIItem>
</APIOptions>
</API>

### `select`

Set the selection to a new value specified by `at`. When a selection already exists, this method just calls `setSelection`.

```ts
editor.tf.select(at)
editor.tf.select(at, { edge: 'end' })
editor.tf.select(at, { edge: 'start' })
```

<API name="select">
<APIParameters>
  <APIItem name="at" type="At">
    Location to select.
  </APIItem>
  <APIItem name="options" type="SelectOptions" optional />
</APIParameters>

<APIOptions type="SelectOptions">
  <APIItem name="edge" type="'start' | 'end'" optional>
    Select the start or end edge above `at`.
  </APIItem>
  <APIItem name="focus" type="boolean" optional>
    Focus the editor before selecting.
  </APIItem>
  <APIItem name="next" type="boolean" optional>
    Select the start of the next sibling.
  </APIItem>
  <APIItem name="previous" type="boolean" optional>
    Select the end of the previous sibling.
  </APIItem>
</APIOptions>
</API>

### `setPoint`

Set new properties on one of the selection's points.

<API name="setPoint">
<APIParameters>
  <APIItem name="props" type="Partial<Point>">
    Point properties to update.
  </APIItem>
  <APIItem name="options" type="object" optional />
</APIParameters>

<APIOptions type="object">
  <APIItem name="edge" type="'anchor' | 'focus' | 'start' | 'end'" optional>
    Which edge of the selection to set.
  </APIItem>
</APIOptions>
</API>

### `setSelection`

Set new properties on an active selection. Since the value is a `Partial<Range>`, this method can only handle updates to an existing selection. If there is no active selection the operation will be void. Use `select` if you'd like to create a selection when there is none.

<API name="setSelection">
<APIParameters>
  <APIItem name="props" type="Partial<TRange>">
    A partial range to update existing selection properties.
  </APIItem>
</APIParameters>
</API>

## DOM Operations

### `blur`

Blur the editor.

### `deselectDOM`

Deselect the editor's DOM selection in addition to `deselect`.

### `focus`

Focus the editor.

```ts
editor.tf.focus()
editor.tf.focus({ edge: 'end' })
editor.tf.focus({ edge: 'endEditor' })
```

<API name="focus">
<APIOptions type="FocusOptions">
  <APIItem name="at" type="At" optional>
    Select this location before focusing.
  </APIItem>
  <APIItem name="edge" type="'start' | 'startEditor' | 'end' | 'endEditor'" optional>
    Focus at the edge of the location or the editor.
  </APIItem>
  <APIItem name="retries" type="number" optional>
    Number of attempts to refocus.
  </APIItem>
</APIOptions>
</API>

### `insertData`

Insert data from a `DataTransfer` into the editor. Calls:

1. `insertFragmentData(editor: ReactEditor, data: DataTransfer)`
2. `insertTextData(editor: ReactEditor, data: DataTransfer)`

<API name="insertData">
<APIParameters>
  <APIItem name="data" type="DataTransfer">
    Data to insert from clipboard or drag event.
  </APIItem>
</APIParameters>
</API>

### `insertFragmentData`

Insert fragment data from a `DataTransfer` into the editor.

<API name="insertFragmentData">
<APIParameters>
  <APIItem name="data" type="DataTransfer">
    Data to parse as fragment.
  </APIItem>
</APIParameters>

<APIReturns type="boolean" />
</API>

### `insertTextData`

Insert text data from a `DataTransfer` into the editor.

<API name="insertTextData">
<APIParameters>
  <APIItem name="data" type="DataTransfer">
    Text data to insert.
  </APIItem>
</APIParameters>

<APIReturns type="boolean" />
</API>

### `setFragmentData`

Sets data from the currently selected fragment on a `DataTransfer`.

<API name="setFragmentData">
<APIParameters>
  <APIItem name="data" type="DataTransfer">
    DataTransfer to store the fragment.
  </APIItem>
</APIParameters>
</API>

## History Operations

### `redo`

Redo to the next saved state.

### `undo`

Undo to the previous saved state.

### `setSplittingOnce`

<API name="setSplittingOnce">
<APIParameters>
  <APIItem name="value" type="boolean">
    Whether the next operation should split into a new batch in history.
  </APIItem>
</APIParameters>
</API>

### `withMerging`

Apply a series of changes inside a synchronous `fn`, These operations will
be merged into the previous history.

<API name="withMerging">
<APIParameters>
  <APIItem name="fn" type="() => void">
    Batched changes to merge into the previous history point.
  </APIItem>
</APIParameters>
</API>

### `withNewBatch`

Apply a series of changes inside a synchronous `fn`, ensuring that the first
operation starts a new batch in the history. Subsequent operations will be
merged as usual.

<API name="withNewBatch">
<APIParameters>
  <APIItem name="fn" type="() => void">
    Batched changes in a new history point.
  </APIItem>
</APIParameters>
</API>

### `withoutMerging`

Apply a series of changes inside a synchronous `fn`, without merging any of
the new operations into previous save point in the history.

<API name="withoutMerging">
<APIParameters>
  <APIItem name="fn" type="() => void">
    Changes not merged into any existing history point.
  </APIItem>
</APIParameters>
</API>

### `withoutSaving`

Apply a series of changes inside a synchronous `fn`, without saving any of
their operations into the history.

<API name="withoutSaving">
<APIParameters>
  <APIItem name="fn" type="() => void">
    Changes not saved into history at all.
  </APIItem>
</APIParameters>
</API>

## Core Operations

### `apply`

Apply an operation in the editor.

<API name="apply">
<APIParameters>
  <APIItem name="operation" type="Operation<N>">
    Operation to apply.
  </APIItem>
</APIParameters>
</API>

### `normalizeNode`

Normalize a node according to the editor's schema.

<API name="normalizeNode">
<APIParameters>
  <APIItem name="entry" type="NodeEntry<N>">
    The node entry to normalize.
  </APIItem>
  <APIItem name="options" type="{ operation?: Operation }" optional />
</APIParameters>

<APIOptions type="{ operation?: Operation }">
  <APIItem name="operation" type="Operation" optional>
    The triggering operation.
  </APIItem>
</APIOptions>
</API>

### `normalize`

Normalize dirty nodes in the editor.

<API name="normalize">
<APIOptions type="EditorNormalizeOptions">
  <APIItem name="force" type="boolean" optional>
    When true, forcibly re-normalize all nodes.
  </APIItem>
  <APIItem name="operation" type="Operation" optional />
</APIOptions>
</API>

### `withoutNormalizing`

Call a function, deferring normalization until after it completes.

<API name="withoutNormalizing">
<APIParameters>
  <APIItem name="fn" type="() => void">
    A synchronous function to execute without normalization in between operations.
  </APIItem>
</APIParameters>

<APIReturns type="boolean">
  True if normalization was performed afterwards.
</APIReturns>
</API>

## Keyboard Shortcuts

### `moveLine`

Handle `ArrowUp` and `ArrowDown` keyboard events.

<API name="moveLine">
<APIParameters>
  <APIItem name="options" type="{ reverse: boolean }">
    - `reverse: true` for `ArrowUp`
    - `reverse: false` for `ArrowDown`
  </APIItem>
</APIParameters>

<APIReturns type="boolean | void">
  Return `true` to prevent default browser behavior, `false` to allow it.
</APIReturns>
</API>

**Default behavior:** Returns `false` (allows Plate's default line movement).

**Usage:**
```ts
const plugin = createPlatePlugin({
  key: 'myPlugin',
}).overrideEditor(() => ({
  transforms: {
    moveLine: ({ reverse }) => {
      // Custom line movement logic
      if (reverse) {
        // Handle ArrowUp
      } else {
        // Handle ArrowDown  
      }
      return true; // Prevent default
    },
  },
}));
```

### `tab`

Handle `Tab` and `Shift+Tab` keyboard events.

<API name="tab">
<APIParameters>
  <APIItem name="options" type="{ reverse: boolean }">
    - `reverse: false` for `Tab`
    - `reverse: true` for `Shift+Tab`
  </APIItem>
</APIParameters>

<APIReturns type="boolean | void">
  Return `true` to prevent default browser behavior, `false` to allow it.
</APIReturns>
</API>

**Default behavior:** Returns `false` (allows default browser tab navigation).

**Usage:**
```ts
const plugin = createPlatePlugin({
  key: 'myPlugin',
}).overrideEditor(() => ({
  transforms: {
    tab: ({ reverse }) => {
      if (reverse) {
        // Handle Shift+Tab (usually outdent)
        editor.tf.outdent();
      } else {
        // Handle Tab (usually indent)
        editor.tf.indent();
      }
      return true; // Prevent default
    },
  },
}));
```

### `selectAll`

Handle `Cmd+A` / `Ctrl+A` keyboard events.

<API name="selectAll">
<APIReturns type="boolean | void">
  Return `true` to prevent default browser behavior, `false` to allow it.
</APIReturns>
</API>

**Default behavior:** Returns `false` (allows default browser select all).

**Usage:**
```ts
const plugin = createPlatePlugin({
  key: 'myPlugin',
}).overrideEditor(() => ({
  transforms: {
    selectAll: () => {
      // Custom select all logic
      const blockEntry = editor.api.block();
      if (blockEntry) {
        editor.tf.select(blockEntry[1]);
        return true; // Prevent default
      }
      return false; // Allow default
    },
  },
}));
```

### `escape`

Handle `Escape` keyboard events.

<API name="escape">
<APIReturns type="boolean | void">
  Return `true` to prevent default browser behavior, `false` to allow it.
</APIReturns>
</API>

**Default behavior:** Returns `false` (allows default browser escape handling).

**Usage:**
```ts
const plugin = createPlatePlugin({
  key: 'myPlugin',
}).overrideEditor(() => ({
  transforms: {
    escape: () => {
      // Custom escape logic (e.g., exit special mode)
      if (editor.api.inSpecialMode()) {
        editor.tf.exitSpecialMode();
        return true; // Prevent default
      }
      return false; // Allow default
    },
  },
}));
```


# Element

Source: https://platejs.org/docs/api/slate/element

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Element
description: API reference for elements in Slate.
---

`TElement` objects are a type of `Node` in a Plate document that contain other `TElement` nodes or `Text` nodes.

```typescript
interface TElement {
  children: Descendant[]
  type: string
  [key: string]: unknown
}
```

## Element Behavior

Elements can have different behaviors depending on the editor's configuration:

### Block vs Inline

Elements can be either "block" or "inline" as defined by plugin `node.isInline`:

- Block elements can only be siblings with other block elements
- Inline elements can be siblings with Text nodes or other inline elements

### Void vs Non-void

Elements can be either "void" or "non-void" as defined by plugin `node.isVoid`:

- Non-void elements: Slate handles rendering of children (e.g., paragraph with Text and Inline children)
- Void elements: Children are rendered by the Element's render code

### Markable Voids

Some void elements can support marks through plugin `node.markableVoid`. For example, a mention element might need to support bold or italic formatting.

## `ElementAPI`

### `isElementType`

Check if a value implements the `TElement` interface and has `elementKey` matching a specified value. Defaults to checking the `'type'` key.

<API name="isElementType">
<APIParameters>
  <APIItem name="value" type="any">
    The value to check.
  </APIItem>
  <APIItem name="elementVal" type="string">
    The value to match against.
  </APIItem>
  <APIItem name="elementKey" type="string" optional>
    The key to check. Defaults to `'type'`.
  </APIItem>
</APIParameters>

<APIReturns type="boolean">
  `true` if the value is an element with the specified key matching `elementVal`.
</APIReturns>
</API>

### `isAncestor`

Check if a value implements the `Ancestor` interface.

<API name="isAncestor">
<APIParameters>
  <APIItem name="value" type="any">
    The value to check.
  </APIItem>
</APIParameters>

<APIReturns type="boolean">
  `true` if the value is an ancestor node.
</APIReturns>
</API>

### `isElement`

Check if a value implements the `TElement` interface.

<API name="isElement">
<APIParameters>
  <APIItem name="value" type="any">
    The value to check.
  </APIItem>
</APIParameters>

<APIReturns type="boolean">
  `true` if the value is a Plate element.
</APIReturns>
</API>

### `isElementList`

Check if a value is an array of `TElement` objects.

<API name="isElementList">
<APIParameters>
  <APIItem name="value" type="any">
    The value to check.
  </APIItem>
</APIParameters>

<APIReturns type="boolean">
  `true` if the value is an array of elements.
</APIReturns>
</API>

### `isElementProps`

Check if a set of props is a partial of `TElement`.

<API name="isElementProps">
<APIParameters>
  <APIItem name="props" type="any">
    The props to check.
  </APIItem>
</APIParameters>

<APIReturns type="boolean">
  `true` if the props match element properties.
</APIReturns>
</API>

### `matches`

Check if an element matches a set of properties.

<API name="matches">
<APIParameters>
  <APIItem name="element" type="TElement">
    The element to check.
  </APIItem>
  <APIItem name="props" type="Partial<TElement>">
    The properties to match against.
  </APIItem>
</APIParameters>

<APIReturns type="boolean">
  `true` if the element matches all provided properties.
</APIReturns>
</API>

## Types

### `TElement`

`TElement` objects are a type of node in a Plate document that contain other element nodes or text nodes. They can be either "blocks" or "inlines" depending on the editor's configuration.

`Element` is a type alias for `TElement`.

<API name="TElement">
<APIAttributes>
  <APIItem name="children" type="Descendant[]">
    An array of child nodes that can be either elements or text nodes.
  </APIItem>
  <APIItem name="type" type="string">
    A string identifier that defines the element's type (e.g., 'paragraph', 'heading', etc.).
  </APIItem>
</APIAttributes>
</API>

### `ElementEntry`

Element entries represent an Element node and its path.

<API name="ElementEntry">
<APIAttributes>
  <APIItem name="0" type="Element">
    The Element node.
  </APIItem>
  <APIItem name="1" type="Path">
    The path to the element.
  </APIItem>
</APIAttributes>
</API>

### `ElementOrTextOf`

```ts
type ElementOrTextOf<E extends Editor> = ElementOf<E> | TextOf<E>;
```

The `ElementOrTextOf` type represents either an element or a text node from a specific editor type.

### `ElementOrTextIn`

```ts
type ElementOrTextIn<V extends Value> = ElementIn<V> | TextIn<V>;
```

The `ElementOrTextIn` type represents either an element or a text node from a specific value type.

### `ElementOf`

`ElementOf` is a utility type to get all the element node types from a given root node type.

### `ElementIn`

```ts
type ElementIn<V extends Value> = ElementOf<V[number]>;
```

`ElementIn` is a utility type to get an element type from a Plate `Value` type.
```

# Location Ref

Source: https://platejs.org/docs/api/slate/location-ref

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Location Ref
description: API reference for location references in Plate.
---

Location references are objects that keep specific locations (paths, points, or ranges) in a document synced over time as new operations are applied to the editor. You can access their `current` property at any time for the up-to-date location value. You can access their `current` property at any time for the up-to-date location value.

## Types

### `PathRef`

Path reference objects keep a specific path in a document synced over time. Created using `editor.api.pathRef`.

<API name="PathRef">
<APIAttributes>
  <APIItem name="current" type="Path | null">
    The current path value, updated as operations are applied.
  </APIItem>
  <APIItem name="affinity" type="'forward' | 'backward' | null">
    The direction to prefer when transforming the path:
    - `'forward'`: Prefer the position after inserted content
    - `'backward'`: Prefer the position before inserted content
    - `null`: No preference
  </APIItem>
  <APIItem name="unref()" type="() => Path | null">
    Call this when you no longer need to sync this path. Returns the final path value.
  </APIItem>
</APIAttributes>
</API>

### `PointRef`

Point reference objects keep a specific point in a document synced over time. Created using `editor.api.pointRef`.

<API name="PointRef">
<APIAttributes>
  <APIItem name="current" type="Point | null">
    The current point value, updated as operations are applied.
  </APIItem>
  <APIItem name="affinity" type="'forward' | 'backward' | null">
    The direction to prefer when transforming the point:
    - `'forward'`: Prefer the position after inserted content
    - `'backward'`: Prefer the position before inserted content
    - `null`: No preference
  </APIItem>
  <APIItem name="unref()" type="() => Point | null">
    Call this when you no longer need to sync this point. Returns the final point value.
  </APIItem>
</APIAttributes>
</API>

### `RangeRef`

Range reference objects keep a specific range in a document synced over time. Created using `editor.api.rangeRef`.

<API name="RangeRef">
<APIAttributes>
  <APIItem name="current" type="TRange | null">
    The current range value, updated as operations are applied.
  </APIItem>
  <APIItem name="affinity" type="'forward' | 'backward' | 'inward' | 'outward' | null">
    The direction to prefer when transforming the range:
    - `'forward'`: Both points prefer after inserted content
    - `'backward'`: Both points prefer before inserted content
    - `'inward'`: Range tends to stay same size when content is inserted at edges
    - `'outward'`: Range tends to grow when content is inserted at edges
    - `null`: No preference
  </APIItem>
  <APIItem name="unref()" type="() => TRange | null">
    Call this when you no longer need to sync this range. Returns the final range value.
  </APIItem>
</APIAttributes>
</API>

Example usage of a RangeRef:

```typescript
const selectionRef = editor.api.rangeRef(editor.selection, {
  affinity: 'inward',
})
// Operations that might change the selection
Transforms.unwrapNodes(editor)
// Restore the selection using the ref
Transforms.select(editor, selectionRef.unref())
```


## `PathRefApi`

### `transform`

Transform a path reference by an operation.

<API name="transform">
<APIParameters>
  <APIItem name="ref" type="PathRef">
    The path reference to transform.
  </APIItem>
  <APIItem name="op" type="Operation">
    The operation to apply. The editor calls this automatically as needed.
  </APIItem>
</APIParameters>
</API>

## `PointRefApi`

### `transform`

Transform a point reference by an operation.

<API name="transform">
<APIParameters>
  <APIItem name="ref" type="PointRef">
    The point reference to transform.
  </APIItem>
  <APIItem name="op" type="Operation">
    The operation to apply. The editor calls this automatically as needed.
  </APIItem>
</APIParameters>
</API>

## `RangeRefApi`

### `transform`

Transform a range reference by an operation.

<API name="transform">
<APIParameters>
  <APIItem name="ref" type="RangeRef">
    The range reference to transform.
  </APIItem>
  <APIItem name="op" type="Operation">
    The operation to apply. The editor calls this automatically as needed.
  </APIItem>
</APIParameters>
</API>


# Location

Source: https://platejs.org/docs/api/slate/location

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Location
description: API reference for locations in Plate.
---

A Location is either a Path, Point or Range. Methods will often accept a Location instead of requiring only a Path, Point or Range.

```typescript
type TLocation = Path | Point | TRange
```

- [Path](/docs/api/slate/path)
- [PathRef](/docs/api/slate/location-ref#pathref)
- [Point](/docs/api/slate/point)
- [PointRef](/docs/api/slate/location-ref#pointref)
- [Range](/docs/api/slate/range)
- [RangeRef](/docs/api/slate/location-ref#rangeref)

## `LocationApi`

### `isAt`

Check if a value implements the `At` interface.

<API name="isAt">
<APIParameters>
  <APIItem name="value" type="any">
    The value to check.
  </APIItem>
</APIParameters>

<APIReturns type="boolean">
  `true` if the value is either a location or a node.
</APIReturns>
</API>

### `isLocation`

Check if a value implements the `TLocation` interface.

<API name="isLocation">
<APIParameters>
  <APIItem name="value" type="any">
    The value to check.
  </APIItem>
</APIParameters>

<APIReturns type="boolean">
  `true` if the value is a `Path`, `Point`, or `TRange`.
</APIReturns>
</API>

### `isSpan`

Check if a value implements the `Span` interface.

<API name="isSpan">
<APIParameters>
  <APIItem name="value" type="any">
    The value to check.
  </APIItem>
</APIParameters>

<APIReturns type="boolean">
  `true` if the value is a valid `Span`.
</APIReturns>
</API>

## Types

### `TLocation`

`Location` is a type alias for `TLocation`.

<API name="TLocation">
<APIAttributes>
  <APIItem name="Path" type="Path">
    An array of numbers representing a node's position.
  </APIItem>
  <APIItem name="Point" type="Point">
    An object with `path` and `offset`.
  </APIItem>
  <APIItem name="TRange" type="TRange">
    An object with `anchor` and `focus`.
  </APIItem>
</APIAttributes>
</API>

### `Span`

<API name="Span">
<APIAttributes>
  <APIItem name="[0]" type="Path">
    The start path.
  </APIItem>
  <APIItem name="[1]" type="Path">
    The end path.
  </APIItem>
</APIAttributes>
</API>

# Node

Source: https://platejs.org/docs/api/slate/node

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Node
description: API reference for nodes in Plate.
---

Nodes are the building blocks of Plate documents. It can either be the Editor root node (highest), an Element node, or a Text node (lowest). This API provides utilities for interacting with nodes, including traversing, querying, and extracting data.

```ts
type TNode = Editor | TElement | TText;

type Descendant = Element | Text
type Ancestor = Editor | Element
```

- [Editor](/docs/api/slate/editor-api)
- [Element](/docs/api/slate/element)
- [Text](/docs/api/slate/text)

## `NodeAPI`

### `ancestor`

Get the node at a specific path, asserting that it's an ancestor node.

<API name="ancestor">
<APIParameters>
  <APIItem name="root" type="TNode">
    The root node to start from.
  </APIItem>
  <APIItem name="path" type="Path">
    The path to the ancestor node.
  </APIItem>
</APIParameters>

<APIReturns type="Ancestor | undefined">
  The ancestor node if found, or `undefined` if not found.
</APIReturns>
</API>

### `ancestors`

Return a generator of all the ancestor nodes above a specific path.

<API name="ancestors">
<APIParameters>
  <APIItem name="root" type="TNode">
    The root node to start from.
  </APIItem>
  <APIItem name="path" type="Path">
    The path to get ancestors for.
  </APIItem>
  <APIItem name="options" type="NodeAncestorsOptions" optional>
    Options for ancestor retrieval.
  </APIItem>
</APIParameters>

<APIOptions type="NodeAncestorsOptions">
  <APIItem name="reverse" type="boolean" optional>
    If true, returns ancestors top-down instead of bottom-up.
  </APIItem>
</APIOptions>

<APIReturns type="Generator<NodeEntry<Ancestor>, void, undefined>">
  A generator of ancestor node entries.
</APIReturns>
</API>

### `child`

Get the child of a node at a specific index.

<API name="child">
<APIParameters>
  <APIItem name="root" type="TNode">
    The parent node.
  </APIItem>
  <APIItem name="index" type="number">
    The index of the child.
  </APIItem>
</APIParameters>

<APIReturns type="TNode | undefined">
  The child node if found, or `undefined` otherwise.
</APIReturns>
</API>

### `children`

Iterate over the children of a node at a specific path.

<API name="children">
<APIParameters>
  <APIItem name="root" type="TNode">
    The root node.
  </APIItem>
  <APIItem name="path" type="Path">
    The path to the parent node.
  </APIItem>
  <APIItem name="options" type="NodeChildrenOptions" optional>
    Options for iterating over children.
  </APIItem>
</APIParameters>

<APIOptions type="NodeChildrenOptions">
  <APIItem name="reverse" type="boolean" optional>
    If true, iterates in reverse order.
  </APIItem>
  <APIItem name="from" type="number" optional>
    Start index (inclusive).
  </APIItem>
  <APIItem name="to" type="number" optional>
    End index (exclusive).
  </APIItem>
</APIOptions>

<APIReturns type="Generator<NodeEntry<TNode>, void, undefined>">
  A generator of child node entries.
</APIReturns>
</API>

### `common`

Get an entry for the common ancestor node of two paths.

<API name="common">
<APIParameters>
  <APIItem name="root" type="TNode">
    The root node.
  </APIItem>
  <APIItem name="path" type="Path">
    First path.
  </APIItem>
  <APIItem name="another" type="Path">
    Second path.
  </APIItem>
</APIParameters>

<APIReturns type="NodeEntry<N> | undefined">
  The common ancestor entry if found, or `undefined` otherwise.
</APIReturns>
</API>

### `descendant`

Get the node at a specific path, asserting that it's a descendant node.

<API name="descendant">
<APIParameters>
  <APIItem name="root" type="TNode">
    The root node.
  </APIItem>
  <APIItem name="path" type="Path">
    The path to the descendant.
  </APIItem>
</APIParameters>

<APIReturns type="Descendant | undefined">
  The descendant node if found, or `undefined` otherwise.
</APIReturns>
</API>

### `descendants`

Return a generator of all the descendant node entries inside a root node.

<API name="descendants">
<APIParameters>
  <APIItem name="root" type="TNode">
    The root node.
  </APIItem>
  <APIItem name="options" type="NodeDescendantsOptions" optional>
    Options for descendant retrieval.
  </APIItem>
</APIParameters>

<APIOptions type="NodeDescendantsOptions">
  <APIItem name="from" type="Path" optional>
    Starting path.
  </APIItem>
  <APIItem name="to" type="Path" optional>
    Ending path.
  </APIItem>
  <APIItem name="reverse" type="boolean" optional>
    If true, iterates in reverse order.
  </APIItem>
  <APIItem name="pass" type="(node: Descendant) => boolean" optional>
    A function to filter descendants.
  </APIItem>
</APIOptions>

<APIReturns type="Generator<NodeEntry<Descendant>, void, undefined>">
  A generator of descendant node entries.
</APIReturns>
</API>

### `elements`

Return a generator of all the element nodes inside a root node.

<API name="elements">
<APIParameters>
  <APIItem name="root" type="TNode">
    The root node.
  </APIItem>
  <APIItem name="options" type="NodeElementsOptions" optional>
    Options for element retrieval.
  </APIItem>
</APIParameters>

<APIOptions type="NodeElementsOptions">
  <APIItem name="pass" type="(node: Element) => boolean" optional>
    A function to filter elements.
  </APIItem>
  <APIItem name="reverse" type="boolean" optional>
    If true, iterates in reverse order.
  </APIItem>
  <APIItem name="from" type="Path" optional>
    Starting path.
  </APIItem>
  <APIItem name="to" type="Path" optional>
    Ending path.
  </APIItem>
</APIOptions>

<APIReturns type="Generator<NodeEntry<Element>, void, undefined>">
  A generator of element entries.
</APIReturns>
</API>

### `first`

Get the first node entry in a root node from a path.

<API name="first">
<APIParameters>
  <APIItem name="root" type="TNode">
    The root node.
  </APIItem>
  <APIItem name="path" type="Path">
    The path to the node.
  </APIItem>
</APIParameters>

<APIReturns type="NodeEntry<N> | undefined">
  The first node entry if found, or `undefined` otherwise.
</APIReturns>
</API>

### `firstChild`

Get the first child node entry of a node.

<API name="firstChild">
<APIParameters>
  <APIItem name="root" type="TNode">
    The parent node.
  </APIItem>
  <APIItem name="path" type="Path">
    The path to the parent node.
  </APIItem>
</APIParameters>

<APIReturns type="NodeEntry<N> | undefined">
  The first child node entry if found, or `undefined` otherwise.
</APIReturns>
</API>

### `firstText`

Get the first text node entry of a node.

<API name="firstText">
<APIParameters>
  <APIItem name="root" type="TNode">
    The parent node.
  </APIItem>
  <APIItem name="path" type="Path">
    The path to the parent node.
  </APIItem>
</APIParameters>

<APIReturns type="NodeEntry<N> | undefined">
  The first text node entry if found, or `undefined` otherwise.
</APIReturns>
</API>

### `fragment`

Get the sliced fragment represented by a range inside a root node.

<API name="fragment">
<APIParameters>
  <APIItem name="root" type="TNode">
    The root node.
  </APIItem>
  <APIItem name="range" type="TRange">
    The range to slice.
  </APIItem>
</APIParameters>

<APIReturns type="N[]">
  The sliced fragment.
</APIReturns>
</API>

### `get`

Get the descendant node referred to by a specific path.

<API name="get">
<APIParameters>
  <APIItem name="root" type="TNode">
    The root node.
  </APIItem>
  <APIItem name="path" type="Path">
    The path to the node.
  </APIItem>
</APIParameters>

<APIReturns type="TNode | undefined">
  The node if found, or `undefined` otherwise.
</APIReturns>
</API>

### `last`

Get the last node entry in a root node from a path.

<API name="last">
<APIParameters>
  <APIItem name="root" type="TNode">
    The root node.
  </APIItem>
  <APIItem name="path" type="Path">
    The path to the node.
  </APIItem>
</APIParameters>

<APIReturns type="NodeEntry<N> | undefined">
  The last node entry if found, or `undefined` otherwise.
</APIReturns>
</API>

### `lastChild`

Get the last child node entry of a node.

<API name="lastChild">
<APIParameters>
  <APIItem name="root" type="TNode">
    The parent node.
  </APIItem>
  <APIItem name="path" type="Path">
    The path to the parent node.
  </APIItem>
</APIParameters>

<APIReturns type="NodeEntry<N> | undefined">
  The last child node entry if found, or `undefined` otherwise.
</APIReturns>
</API>

### `leaf`

Get the node at a specific path, ensuring it's a leaf text node.

<API name="leaf">
<APIParameters>
  <APIItem name="root" type="TNode">
    The root node.
  </APIItem>
  <APIItem name="path" type="Path">
    The path to the node.
  </APIItem>
</APIParameters>

<APIReturns type="N | undefined">
  The leaf node if found, or `undefined` otherwise.
</APIReturns>
</API>

### `levels`

Return a generator of the in a branch of the tree, from a specific path.

<API name="levels">
<APIParameters>
  <APIItem name="root" type="TNode">
    The root node.
  </APIItem>
  <APIItem name="path" type="Path">
    The path to the node.
  </APIItem>
</APIParameters>

<APIReturns type="Generator<NodeEntry<N>, void, undefined>">
  A generator of node entries in a branch of the tree from a specific path.
</APIReturns>
</API>

### `nodes`

Return a generator of all the node entries of a root node.

<API name="nodes">
<APIParameters>
  <APIItem name="root" type="TNode">
    The root node.
  </APIItem>
  <APIItem name="options" type="NodeTextsOptions" optional>
    Similar options to `descendants`.
  </APIItem>
</APIParameters>

<APIReturns type="Generator<NodeEntry<N>, void, undefined>">
  A generator of node entries.
</APIReturns>
</API>

### `parent`

Get the parent of a node at a specific path.

<API name="parent">
<APIParameters>
  <APIItem name="root" type="TNode">
    The root node.
  </APIItem>
  <APIItem name="path" type="Path">
    The path to the node.
  </APIItem>
</APIParameters>

<APIReturns type="Ancestor | undefined">
  The parent node if found, or `undefined` otherwise.
</APIReturns>
</API>

### `texts`

Return a generator of all leaf text nodes in a root node.

<API name="texts">
<APIParameters>
  <APIItem name="root" type="TNode">
    The root node.
  </APIItem>
  <APIItem name="options" type="NodeTextsOptions" optional>
    Options for text node retrieval.
  </APIItem>
</APIParameters>

<APIReturns type="Generator<NodeEntry<Text>, void, undefined>">
  A generator of text node entries.
</APIReturns>
</API>

### `extractProps`

Get the props of a node.

<API name="extractProps">
<APIParameters>
  <APIItem name="node" type="TNode">
    The node to extract props from.
  </APIItem>
</APIParameters>

<APIReturns type="NodeProps<N>">
  The props of the node.
</APIReturns>
</API>

### `has`

Check if a descendant node exists at a specific path.

<API name="has">
<APIParameters>
  <APIItem name="root" type="TNode">
    The root node.
  </APIItem>
  <APIItem name="path" type="Path">
    The path to check.
  </APIItem>
</APIParameters>

<APIReturns type="boolean">
  `true` if a node exists at the specified path, `false` otherwise.
</APIReturns>
</API>

### `hasSingleChild`

Check if a node has a single child.

<API name="hasSingleChild">
<APIParameters>
  <APIItem name="node" type="TNode">
    The node to check.
  </APIItem>
</APIParameters>

<APIReturns type="boolean">
  `true` if the node has a single child.
</APIReturns>
</API>

### `isAncestor`

Check if a value implements the `Ancestor` interface.

<API name="isAncestor">
<APIParameters>
  <APIItem name="value" type="any">
    The value to check.
  </APIItem>
</APIParameters>

<APIReturns type="boolean">
  `true` if the value implements the `Ancestor` interface.
</APIReturns>
</API>

### `isDescendant`

Check if a value implements the `Descendant` interface.

<API name="isDescendant">
<APIParameters>
  <APIItem name="value" type="any">
    The value to check.
  </APIItem>
</APIParameters>

<APIReturns type="boolean">
  `true` if the value implements the `Descendant` interface.
</APIReturns>
</API>

### `isLastChild`

Check if a node is the last child of its parent.

<API name="isLastChild">
<APIParameters>
  <APIItem name="root" type="TNode">
    The root node.
  </APIItem>
  <APIItem name="path" type="Path">
    The path to the node.
  </APIItem>
</APIParameters>

<APIReturns type="boolean">
  `true` if the node is the last child of its parent.
</APIReturns>
</API>

### `isNode`

Check if a value implements the `TNode` interface.

<API name="isNode">
<APIParameters>
  <APIItem name="value" type="any">
    The value to check.
  </APIItem>
</APIParameters>

<APIReturns type="boolean">
  `true` if the value implements the `TNode` interface.
</APIReturns>
</API>

### `isNodeList`

Check if a value is a list of `Descendant` objects.

<API name="isNodeList">
<APIParameters>
  <APIItem name="value" type="any">
    The value to check.
  </APIItem>
</APIParameters>

<APIReturns type="boolean">
  `true` if the value is a list of `Descendant` objects.
</APIReturns>
</API>

### `matches`

Check if a node matches a set of props.

<API name="matches">
<APIParameters>
  <APIItem name="node" type="Descendant">
    The node to check.
  </APIItem>
  <APIItem name="props" type="Partial<Descendant>">
    The properties to match against.
  </APIItem>
</APIParameters>

<APIReturns type="boolean">
  `true` if the node matches the provided properties.
</APIReturns>
</API>

### `string`

Get the concatenated text string of a node's content.

<API name="string">
<APIParameters>
  <APIItem name="node" type="TNode">
    The node to get text from.
  </APIItem>
</APIParameters>

<APIReturns type="string">
  The concatenated text content.
</APIReturns>
</API>

## Types

### `TNode`

`Node` is a type alias for `TNode`.

```ts
type TNode = Editor | TElement | TText;
```

### `NodeEntry`

`NodeEntry` objects are returned when iterating over the nodes in a Plate document tree. They consist of an array with two elements: the `TNode` and its `Path` relative to the root node in the document.

<API name="NodeEntry">
<APIAttributes>
  <APIItem name="0" type="TNode">
    The node itself.
  </APIItem>
  <APIItem name="1" type="Path">
    The path to the node.
  </APIItem>
</APIAttributes>
</API>

### `Descendant`

The `Descendant` union type represents nodes that are descendants in the tree.

```ts
type Descendant = TElement | TText;
```


### `Ancestor`

The `Ancestor` union type represents nodes that are ancestors in the tree.

```ts
type Ancestor = Editor | TElement;
```

### `NodeOf<N>`

<API name="NodeOf">
<APIParameters>
  <APIItem name="node" type="TNode">
    The node to get the type of.
  </APIItem>
</APIParameters>

<APIReturns type="N">
  The node type.
</APIReturns>
</API>

### `NodeIn<V>`

<API name="NodeIn">
<APIParameters>
  <APIItem name="value" type="Value">
    The value to get node types from.
  </APIItem>
</APIParameters>

<APIReturns type="NodeOf<V[number]>">
  All possible node types from the specified value.
</APIReturns>
</API>

### `TNodeMatch<N>`

<API name="TNodeMatch">
<APIParameters>
  <APIItem name="node" type="N">
    The node to match.
  </APIItem>
</APIParameters>

<APIReturns type="boolean">
  `true` if the node matches the predicate.
</APIReturns>
</API>

### `DescendantOf<N>`

<API name="DescendantOf">
<APIParameters>
  <APIItem name="node" type="N">
    The node to get descendant types from.
  </APIItem>
</APIParameters>

<APIReturns type="DescendantOf<N>">
  All possible descendant node types from the specified root node.
</APIReturns>
</API>

### `DescendantIn<V>`

<API name="DescendantIn">
<APIParameters>
  <APIItem name="value" type="Value">
    The value to get descendant types from.
  </APIItem>
</APIParameters>

<APIReturns type="DescendantIn<V>">
  All possible descendant node types from the specified value.
</APIReturns>
</API>

### `ChildOf<N>`

<API name="ChildOf">
<APIParameters>
  <APIItem name="node" type="N">
    The node to get the child type from.
  </APIItem>
</APIParameters>

<APIReturns type="ChildOf<N>">
  The child node type.
</APIReturns>
</API>

### `AncestorOf<N>`

<API name="AncestorOf">
<APIParameters>
  <APIItem name="node" type="N">
    The node to get ancestor types from.
  </APIItem>
</APIParameters>

<APIReturns type="AncestorOf<N>">
  All possible ancestor node types from the specified root node.
</APIReturns>
</API>

### `AncestorIn<V>`

<API name="AncestorIn">
<APIParameters>
  <APIItem name="value" type="Value">
    The value to get ancestor types from.
  </APIItem>
</APIParameters>

<APIReturns type="AncestorIn<V>">
  All possible ancestor node types from the specified value.
</APIReturns>
</API>

### `AncestorEntry`

Ancestor entries represent an ancestor node (Editor or Element) and its path.

<API name="AncestorEntry">
<APIAttributes>
  <APIItem name="0" type="Ancestor">
    The Editor or Element node.
  </APIItem>
  <APIItem name="1" type="Path">
    The path to the ancestor.
  </APIItem>
</APIAttributes>
</API>

### `DescendantEntry`

Descendant entries represent a descendant node (Element or Text) and its path.

<API name="DescendantEntry">
<APIAttributes>
  <APIItem name="0" type="Descendant">
    The Element or Text node.
  </APIItem>
  <APIItem name="1" type="Path">
    The path to the descendant.
  </APIItem>
</APIAttributes>
</API>

### `NodeChildEntry`

Node child entries represent a child node and its path relative to its parent.

<API name="NodeChildEntry">
<APIAttributes>
  <APIItem name="0" type="TNode">
    The child node.
  </APIItem>
  <APIItem name="1" type="Path">
    The path to the child.
  </APIItem>
</APIAttributes>
</API>

# Operation

Source: https://platejs.org/docs/api/slate/operation

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Operation
description: API reference for operations in Plate.
---

An Operation is the lowest-level instructions that Plate editors use to apply changes to their internal state. Representing all changes as operations is what allows Plate editors to easily implement history, collaboration, and other features.

```typescript
export type Operation<N extends Descendant = Descendant> =
  | NodeOperation<N>
  | SelectionOperation
  | TextOperation;
```

## `OperationApi`

### `isNodeOperation`

Check if a value is a `NodeOperation` object.

<API name="isNodeOperation">
<APIParameters>
  <APIItem name="value" type="any">
    The value to check.
  </APIItem>
</APIParameters>

<APIReturns type="boolean">
  `true` if the value is a node operation.
</APIReturns>
</API>

### `inverse`

Invert an operation, returning a new operation that will exactly undo the original when applied.

<API name="inverse">
<APIParameters>
  <APIItem name="op" type="Operation">
    The operation to invert.
  </APIItem>
</APIParameters>

<APIReturns type="Operation">
  A new operation that undoes the original operation.
</APIReturns>
</API>

### `isOperation`

Check if a value is an `Operation` object.

<API name="isOperation">
<APIParameters>
  <APIItem name="value" type="any">
    The value to check.
  </APIItem>
</APIParameters>

<APIReturns type="boolean">
  `true` if the value is an operation.
</APIReturns>
</API>

### `isOperationList`

Check if a value is a list of `Operation` objects.

<API name="isOperationList">
<APIParameters>
  <APIItem name="value" type="any">
    The value to check.
  </APIItem>
</APIParameters>

<APIReturns type="boolean">
  `true` if the value is an array of operations.
</APIReturns>
</API>

### `isSelectionOperation`

Check if a value is a `SelectionOperation` object.

<API name="isSelectionOperation">
<APIParameters>
  <APIItem name="value" type="any">
    The value to check.
  </APIItem>
</APIParameters>

<APIReturns type="boolean">
  `true` if the value is a selection operation.
</APIReturns>
</API>

### `isTextOperation`

Check if a value is a `TextOperation` object.

<API name="isTextOperation">
<APIParameters>
  <APIItem name="value" type="any">
    The value to check.
  </APIItem>
</APIParameters>

<APIReturns type="boolean">
  `true` if the value is a text operation.
</APIReturns>
</API>

## Types

### `Operation`

```ts
export type Operation<N extends Descendant = Descendant> =
  | NodeOperation<N>
  | SelectionOperation
  | TextOperation;
```

### `NodeOperation`

A node operation modifies a node.

```ts
export type NodeOperation<N extends Descendant = Descendant> =
  | InsertNodeOperation<N>
  | MergeNodeOperation<N>
  | MoveNodeOperation
  | RemoveNodeOperation<N>
  | SetNodeOperation<N>
  | SplitNodeOperation<N>;
```

### `SelectionOperation`

A selection operation modifies the selection.

```ts
export type SelectionOperation = SetSelectionOperation;
```

### `TextOperation`

A text operation modifies text content.

```ts
export type TextOperation = InsertTextOperation | RemoveTextOperation;
```

### `InsertNodeOperation`

<API name="InsertNodeOperation">
<APIAttributes>
  <APIItem name="node" type="N">
    The node to insert.
  </APIItem>
  <APIItem name="path" type="Path">
    The path to insert at.
  </APIItem>
  <APIItem name="type" type="'insert_node'">
    The operation type.
  </APIItem>
</APIAttributes>
</API>

### `MergeNodeOperation`

<API name="MergeNodeOperation">
<APIAttributes>
  <APIItem name="path" type="Path">
    The path of the node to merge.
  </APIItem>
  <APIItem name="position" type="number">
    The position to merge at.
  </APIItem>
  <APIItem name="properties" type="Partial<NodeProps<N>>">
    The properties of the merged node.
  </APIItem>
  <APIItem name="type" type="'merge_node'">
    The operation type.
  </APIItem>
</APIAttributes>
</API>

### `MoveNodeOperation`

<API name="MoveNodeOperation">
<APIAttributes>
  <APIItem name="newPath" type="Path">
    The new path to move to.
  </APIItem>
  <APIItem name="path" type="Path">
    The path of the node to move.
  </APIItem>
  <APIItem name="type" type="'move_node'">
    The operation type.
  </APIItem>
</APIAttributes>
</API>

### `RemoveNodeOperation`

<API name="RemoveNodeOperation">
<APIAttributes>
  <APIItem name="node" type="N">
    The node to remove.
  </APIItem>
  <APIItem name="path" type="Path">
    The path of the node.
  </APIItem>
  <APIItem name="type" type="'remove_node'">
    The operation type.
  </APIItem>
</APIAttributes>
</API>

### `SetNodeOperation`

<API name="SetNodeOperation">
<APIAttributes>
  <APIItem name="newProperties" type="Partial<NodeProps<N1>>">
    The new properties to set.
  </APIItem>
  <APIItem name="path" type="Path">
    The path of the node.
  </APIItem>
  <APIItem name="properties" type="Partial<NodeProps<N2>>">
    The old properties.
  </APIItem>
  <APIItem name="type" type="'set_node'">
    The operation type.
  </APIItem>
</APIAttributes>
</API>

### `SplitNodeOperation`

<API name="SplitNodeOperation">
<APIAttributes>
  <APIItem name="path" type="Path">
    The path of the node to split.
  </APIItem>
  <APIItem name="position" type="number">
    The position to split at.
  </APIItem>
  <APIItem name="properties" type="Partial<NodeProps<N>>">
    The properties of the new split node.
  </APIItem>
  <APIItem name="type" type="'split_node'">
    The operation type.
  </APIItem>
</APIAttributes>
</API>

### `SetSelectionOperation`

<API name="SetSelectionOperation">
<APIAttributes>
  <APIItem name="newProperties" type="Partial<TRange> | TRange | null">
    The new selection properties.
  </APIItem>
  <APIItem name="properties" type="Partial<TRange> | TRange | null">
    The old selection properties.
  </APIItem>
  <APIItem name="type" type="'set_selection'">
    The operation type.
  </APIItem>
</APIAttributes>
</API>

### `InsertTextOperation`

<API name="InsertTextOperation">
<APIAttributes>
  <APIItem name="offset" type="number">
    The offset to insert at.
  </APIItem>
  <APIItem name="path" type="Path">
    The path of the text node.
  </APIItem>
  <APIItem name="text" type="string">
    The text to insert.
  </APIItem>
  <APIItem name="type" type="'insert_text'">
    The operation type.
  </APIItem>
</APIAttributes>
</API>

### `RemoveTextOperation`

<API name="RemoveTextOperation">
<APIAttributes>
  <APIItem name="offset" type="number">
    The offset to remove from.
  </APIItem>
  <APIItem name="path" type="Path">
    The path of the text node.
  </APIItem>
  <APIItem name="text" type="string">
    The text being removed.
  </APIItem>
  <APIItem name="type" type="'remove_text'">
    The operation type.
  </APIItem>
</APIAttributes>
</API>



# Path

Source: https://platejs.org/docs/api/slate/path

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Path
description: API reference for paths in Plate.
---

A Path is a list of indexes that describe a node's exact position in a Plate node tree. Although they are usually relative to the root `Editor` object, they can be relative to any `Node` object.

```ts
type Path = number[];
```

## `PathApi`

### `operationCanTransformPath`

Check if an operation can affect paths (used as an optimization for dirty-path updates during normalization).

<API name="operationCanTransformPath">
<APIParameters>
  <APIItem name="operation" type="Operation<N>">
    The operation to check.
  </APIItem>
</APIParameters>

<APIReturns type="boolean">
  `true` if the operation is an insert, merge, move, remove, or split operation.
</APIReturns>
</API>

### `transform`

Transform a path by an operation.

<API name="transform">
<APIParameters>
  <APIItem name="path" type="Path">
    The path to transform.
  </APIItem>
  <APIItem name="operation" type="Operation">
    The operation to apply.
  </APIItem>
  <APIItem name="options" type="PathTransformOptions" optional>
    Options for transforming a path.
  </APIItem>
</APIParameters>

<APIOptions type="PathTransformOptions">
  <APIItem name="affinity" type="TextDirection | null" optional>
    The affinity of the transform.
  </APIItem>
</APIOptions>

<APIReturns type="Path | null">
  The transformed path, or `null` if the path was deleted.
</APIReturns>
</API>

### `ancestors`

Get a list of ancestor paths for a given path.

<API name="ancestors">
<APIParameters>
  <APIItem name="path" type="Path">
    The path to get ancestors for.
  </APIItem>
  <APIItem name="options" type="PathAncestorsOptions" optional>
    Options for ancestor retrieval.
  </APIItem>
</APIParameters>

<APIOptions type="PathAncestorsOptions">
  <APIItem name="reverse" type="boolean" optional>
    If true, returns paths in reverse (deepest to shallowest).
  </APIItem>
</APIOptions>

<APIReturns type="Path[]">
  An array of paths sorted from shallowest to deepest ancestor (unless reversed).
</APIReturns>
</API>

### `child`

Get a path to a child at the given index.

<API name="child">
<APIParameters>
  <APIItem name="path" type="Path">
    The parent path.
  </APIItem>
  <APIItem name="index" type="number">
    The child index.
  </APIItem>
</APIParameters>

<APIReturns type="Path">
  The path to the child node.
</APIReturns>
</API>

### `common`

Get the common ancestor path of two paths.

<API name="common">
<APIParameters>
  <APIItem name="path" type="Path">
    The first path.
  </APIItem>
  <APIItem name="another" type="Path">
    The second path.
  </APIItem>
</APIParameters>

<APIReturns type="Path">
  The common ancestor path.
</APIReturns>
</API>

### `compare`

Compare a path to another, returning an integer indicating whether the path was before, at, or after the other.

<API name="compare">
<APIParameters>
  <APIItem name="path" type="Path">
    The first path to compare.
  </APIItem>
  <APIItem name="another" type="Path">
    The second path to compare.
  </APIItem>
</APIParameters>

<APIReturns type="-1 | 0 | 1">
  `-1` if before, `0` if at the same location, `1` if after.
</APIReturns>
</API>

### `endsAfter`

Check if a path ends after one of the indexes in another.

<API name="endsAfter">
<APIParameters>
  <APIItem name="path" type="Path">
    The path to check.
  </APIItem>
  <APIItem name="another" type="Path">
    The path to compare against.
  </APIItem>
</APIParameters>

<APIReturns type="boolean">
  `true` if `path` ends after `another`.
</APIReturns>
</API>

### `endsAt`

Check if a path ends at one of the indexes in another.

<API name="endsAt">
<APIParameters>
  <APIItem name="path" type="Path">
    The path to check.
  </APIItem>
  <APIItem name="another" type="Path">
    The path to compare against.
  </APIItem>
</APIParameters>

<APIReturns type="boolean">
  `true` if `path` ends at the same index as `another`.
</APIReturns>
</API>

### `endsBefore`

Check if a path ends before one of the indexes in another.

<API name="endsBefore">
<APIParameters>
  <APIItem name="path" type="Path">
    The path to check.
  </APIItem>
  <APIItem name="another" type="Path">
    The path to compare against.
  </APIItem>
</APIParameters>

<APIReturns type="boolean">
  `true` if `path` ends before `another`.
</APIReturns>
</API>

### `equals`

Check if a path is exactly equal to another.

<API name="equals">
<APIParameters>
  <APIItem name="path" type="Path">
    The first path.
  </APIItem>
  <APIItem name="another" type="Path">
    The second path.
  </APIItem>
</APIParameters>

<APIReturns type="boolean">
  `true` if the paths are exactly equal.
</APIReturns>
</API>

### `firstChild`

Get a path to the first child of a path.

<API name="firstChild">
<APIParameters>
  <APIItem name="path" type="Path">
    The parent path.
  </APIItem>
</APIParameters>

<APIReturns type="Path">
  The path to the first child node.
</APIReturns>
</API>

### `hasPrevious`

Check if the path of a previous sibling node exists.

<API name="hasPrevious">
<APIParameters>
  <APIItem name="path" type="Path">
    The path to check.
  </APIItem>
</APIParameters>

<APIReturns type="boolean">
  `true` if a previous sibling exists.
</APIReturns>
</API>

### `isAfter`

Check if a path is after another.

<API name="isAfter">
<APIParameters>
  <APIItem name="path" type="Path">
    The path to check.
  </APIItem>
  <APIItem name="another" type="Path">
    The path to compare against.
  </APIItem>
</APIParameters>

<APIReturns type="boolean">
  `true` if the first path is after the second.
</APIReturns>
</API>

### `isAncestor`

Check if a path is an ancestor of another.

<API name="isAncestor">
<APIParameters>
  <APIItem name="path" type="Path">
    The potential ancestor path.
  </APIItem>
  <APIItem name="another" type="Path">
    The potential descendant path.
  </APIItem>
</APIParameters>

<APIReturns type="boolean">
  `true` if `path` is an ancestor of `another`.
</APIReturns>
</API>

### `isBefore`

Check if a path is before another.

<API name="isBefore">
<APIParameters>
  <APIItem name="path" type="Path">
    The path to check.
  </APIItem>
  <APIItem name="another" type="Path">
    The path to compare against.
  </APIItem>
</APIParameters>

<APIReturns type="boolean">
  `true` if the first path is before the second.
</APIReturns>
</API>

### `isChild`

Check if a path is a child of another.

<API name="isChild">
<APIParameters>
  <APIItem name="path" type="Path">
    The potential child path.
  </APIItem>
  <APIItem name="another" type="Path">
    The potential parent path.
  </APIItem>
</APIParameters>

<APIReturns type="boolean">
  `true` if `path` is a child of `another`.
</APIReturns>
</API>

### `isCommon`

Check if a path is equal to or an ancestor of another.

<API name="isCommon">
<APIParameters>
  <APIItem name="path" type="Path">
    The path to check.
  </APIItem>
  <APIItem name="another" type="Path">
    The path to compare against.
  </APIItem>
</APIParameters>

<APIReturns type="boolean">
  `true` if `path` is equal to or an ancestor of `another`.
</APIReturns>
</API>

### `isDescendant`

Check if a path is a descendant of another.

<API name="isDescendant">
<APIParameters>
  <APIItem name="path" type="Path">
    The potential descendant path.
  </APIItem>
  <APIItem name="another" type="Path">
    The potential ancestor path.
  </APIItem>
</APIParameters>

<APIReturns type="boolean">
  `true` if `path` is a descendant of `another`.
</APIReturns>
</API>

### `isParent`

Check if a path is the parent of another.

<API name="isParent">
<APIParameters>
  <APIItem name="path" type="Path">
    The potential parent path.
  </APIItem>
  <APIItem name="another" type="Path">
    The potential child path.
  </APIItem>
</APIParameters>

<APIReturns type="boolean">
  `true` if `path` is the parent of `another`.
</APIReturns>
</API>

### `isPath`

Check if a value implements the `Path` interface.

<API name="isPath">
<APIParameters>
  <APIItem name="value" type="any">
    The value to check.
  </APIItem>
</APIParameters>

<APIReturns type="boolean">
  `true` if the value is a path.
</APIReturns>
</API>

### `isSibling`

Check if a path is a sibling of another.

<API name="isSibling">
<APIParameters>
  <APIItem name="path" type="Path">
    The path to check.
  </APIItem>
  <APIItem name="another" type="Path">
    The path to compare against.
  </APIItem>
</APIParameters>

<APIReturns type="boolean">
  `true` if the paths share the same parent.
</APIReturns>
</API>

### `lastIndex`

Get the last index of a path.

<API name="lastIndex">
<APIParameters>
  <APIItem name="path" type="Path">
    The path to check.
  </APIItem>
</APIParameters>

<APIReturns type="number">
  The last index, or -1 if the path is empty.
</APIReturns>
</API>

### `levels`

Get a list of paths at every level down to a path.

<API name="levels">
<APIParameters>
  <APIItem name="path" type="Path">
    The path to get levels for.
  </APIItem>
  <APIItem name="options" type="PathLevelsOptions" optional>
    Options for levels retrieval.
  </APIItem>
</APIParameters>

<APIOptions type="PathLevelsOptions">
  <APIItem name="reverse" type="boolean" optional>
    If true, returns paths in reverse (deepest to shallowest).
  </APIItem>
</APIOptions>

<APIReturns type="Path[]">
  An array of paths including the path itself and all its ancestors.
</APIReturns>
</API>

### `next`

Get the path to the next sibling node.

<API name="next">
<APIParameters>
  <APIItem name="path" type="Path">
    The current path.
  </APIItem>
</APIParameters>

<APIReturns type="Path">
  The path to the next sibling.
</APIReturns>
</API>

### `parent`

Get the path to the parent node.

<API name="parent">
<APIParameters>
  <APIItem name="path" type="Path">
    The current path.
  </APIItem>
</APIParameters>

<APIReturns type="Path">
  The path to the parent node.
</APIReturns>
</API>

### `previous`

Get the path to the previous sibling node.

<API name="previous">
<APIParameters>
  <APIItem name="path" type="Path">
    The current path.
  </APIItem>
</APIParameters>

<APIReturns type="Path | undefined">
  The path to the previous sibling, or `undefined` if there is none.
</APIReturns>
</API>

### `relative`

Get a path relative to an ancestor.

<API name="relative">
<APIParameters>
  <APIItem name="path" type="Path">
    The path to make relative.
  </APIItem>
  <APIItem name="ancestor" type="Path">
    The ancestor path.
  </APIItem>
</APIParameters>

<APIReturns type="Path">
  The relative path.
</APIReturns>
</API>

## Types

### `Path`

An array of numbers representing the indexes to traverse to reach a specific node in the document tree.

# Point

Source: https://platejs.org/docs/api/slate/point

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Point
description: API reference for points in Plate.
---

A Point represents a specific location in a Plate document. It consists of a path to a text node and an offset within that text node's content.

```typescript
type Point = {
  path: Path
  offset: number
}
```

- [Path](/docs/api/slate/path)

## `PointAPI`

### `get`

Get a point from a location.

<API name="get">
<APIParameters>
  <APIItem name="at" type="At | null" optional>
    The location to get the point from. Can be a `TRange`, `Point`, or `Path`.
  </APIItem>
  <APIItem name="options" type="object" optional>
    Additional options for point retrieval.
  </APIItem>
</APIParameters>

<APIOptions type="object">
  <APIItem name="focus" type="boolean" optional>
    If true and the location is a range, returns the focus point instead of the anchor point.
  </APIItem>
</APIOptions>

<APIReturns type="Point | undefined">
  The point at the specified location, or `undefined` if not found.
</APIReturns>
</API>

### `transform`

Transform a point by an operation.

<API name="transform">
<APIParameters>
  <APIItem name="point" type="Point">
    The point to transform.
  </APIItem>
  <APIItem name="op" type="Operation">
    The operation to apply.
  </APIItem>
  <APIItem name="options" type="PointTransformOptions" optional>
    Options for transforming the point.
  </APIItem>
</APIParameters>

<APIOptions type="PointTransformOptions">
  <APIItem name="affinity" type="TextDirection | null" optional>
    The direction to prefer when transforming the point.
  </APIItem>
</APIOptions>

<APIReturns type="Point | null">
  The transformed point, or `null` if the point was deleted.
</APIReturns>
</API>

### `compare`

Compare a point to another.

<API name="compare">
<APIParameters>
  <APIItem name="point" type="Point">
    The first point to compare.
  </APIItem>
  <APIItem name="another" type="Point">
    The second point to compare.
  </APIItem>
</APIParameters>

<APIReturns type="-1 | 0 | 1">
  `-1` if before, `0` if at the same location, `1` if after.
</APIReturns>
</API>

### `equals`

Check if two points are exactly equal.

<API name="equals">
<APIParameters>
  <APIItem name="point" type="Point">
    The first point to compare.
  </APIItem>
  <APIItem name="another" type="Point">
    The second point to compare.
  </APIItem>
</APIParameters>

<APIReturns type="boolean">
  `true` if the points are equal, `false` otherwise.
</APIReturns>
</API>

### `isAfter`

Check if a point is after another.

<API name="isAfter">
<APIParameters>
  <APIItem name="point" type="Point">
    The point to check.
  </APIItem>
  <APIItem name="another" type="Point">
    The point to compare against.
  </APIItem>
</APIParameters>

<APIReturns type="boolean">
  `true` if the first point is after the second.
</APIReturns>
</API>

### `isBefore`

Check if a point is before another.

<API name="isBefore">
<APIParameters>
  <APIItem name="point" type="Point">
    The point to check.
  </APIItem>
  <APIItem name="another" type="Point">
    The point to compare against.
  </APIItem>
</APIParameters>

<APIReturns type="boolean">
  `true` if the first point is before the second.
</APIReturns>
</API>

### `isPoint`

Check if a value implements the `Point` interface.

<API name="isPoint">
<APIParameters>
  <APIItem name="value" type="any">
    The value to check.
  </APIItem>
</APIParameters>

<APIReturns type="boolean">
  `true` if the value is a point.
</APIReturns>
</API>

## Types

### `Point`

A point represents a specific location in a Plate document.

<API name="Point">
<APIAttributes>
  <APIItem name="offset" type="number">
    The index of the character in the text node.
  </APIItem>
  <APIItem name="path" type="Path">
    The path to the text node.
  </APIItem>
</APIAttributes>
</API>
### `PointEntry`

A point entry is returned when iterating over `Point` objects that belong to a range.

<API name="PointEntry">
<APIAttributes>
  <APIItem name="[0]" type="Point">
    The point location.
  </APIItem>
  <APIItem name="[1]" type="'anchor' | 'focus'">
    Indicates whether this point is the anchor or focus of a range.
  </APIItem>
</APIAttributes>
</API>

# Range

Source: https://platejs.org/docs/api/slate/range

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Range
description: API reference for ranges in Plate.
---

A Range is a set of points that refer to a specific span of a Plate document. They can define a span inside a single node or span across multiple nodes. A range consists of two points: an anchor (start) and a focus (end).

```typescript
type TRange = {
  anchor: Point
  focus: Point
}
```

- [Point](/docs/api/slate/point)

## `RangeAPI`

### `transform`

Transform a range by an operation.

<API name="transform">
<APIParameters>
  <APIItem name="range" type="TRange">
    The range to transform.
  </APIItem>
  <APIItem name="op" type="Operation">
    The operation to apply to the range.
  </APIItem>
  <APIItem name="options" type="RangeTransformOptions" optional>
    Options for transforming the range.
  </APIItem>
</APIParameters>

<APIOptions type="RangeTransformOptions">
  <APIItem name="affinity" type="RangeDirection | null" optional>
    The direction to prefer when transforming the range.
  </APIItem>
</APIOptions>

<APIReturns type="TRange | null">
  The transformed range, or `null` if the range was deleted.
</APIReturns>
</API>

### `edges`

Get the start and end points of a range.

<API name="edges">
<APIParameters>
  <APIItem name="range" type="TRange">
    The range to get edges from.
  </APIItem>
  <APIItem name="options" type="RangeEdgesOptions" optional>
    Options for retrieving edges.
  </APIItem>
</APIParameters>

<APIOptions type="RangeEdgesOptions">
  <APIItem name="reverse" type="boolean" optional>
    If true, returns points in reverse order.
  </APIItem>
</APIOptions>

<APIReturns type="[Point, Point]">
  A tuple of points representing the start and end points.
</APIReturns>
</API>

### `end`

Get the end point of a range.

<API name="end">
<APIParameters>
  <APIItem name="range" type="TRange">
    The range to get the end point from.
  </APIItem>
</APIParameters>

<APIReturns type="Point">
  The end point of the range.
</APIReturns>
</API>

### `equals`

Check if two ranges are exactly equal.

<API name="equals">
<APIParameters>
  <APIItem name="range" type="TRange">
    The first range to compare.
  </APIItem>
  <APIItem name="another" type="TRange">
    The second range to compare.
  </APIItem>
</APIParameters>

<APIReturns type="boolean">
  `true` if the ranges are exactly equal.
</APIReturns>
</API>

### `includes`

Check if a range includes a path, point, or part of another range.

<API name="includes">
<APIParameters>
  <APIItem name="range" type="TRange">
    The range to check.
  </APIItem>
  <APIItem name="target" type="Path | Point | TRange">
    The target to check for inclusion.
  </APIItem>
</APIParameters>

<APIReturns type="boolean">
  `true` if the range includes the target.
</APIReturns>
</API>

### `intersection`

Get the intersection of two ranges.

<API name="intersection">
<APIParameters>
  <APIItem name="range" type="TRange">
    The first range.
  </APIItem>
  <APIItem name="another" type="TRange">
    The second range.
  </APIItem>
</APIParameters>

<APIReturns type="TRange | null">
  The intersecting range, or `null` if there is no intersection.
</APIReturns>
</API>

### `isBackward`

Check if a range is backward (anchor point appears after focus point).

<API name="isBackward">
<APIParameters>
  <APIItem name="range" type="TRange">
    The range to check.
  </APIItem>
</APIParameters>

<APIReturns type="boolean">
  `true` if the range is backward.
</APIReturns>
</API>

### `isCollapsed`

Check if a range is collapsed (both points refer to the same position).

<API name="isCollapsed">
<APIParameters>
  <APIItem name="range" type="TRange | null" optional>
    The range to check.
  </APIItem>
</APIParameters>

<APIReturns type="boolean">
  `true` if the range exists and is collapsed.
</APIReturns>
</API>

### `isExpanded`

Check if a range is expanded (not collapsed).

<API name="isExpanded">
<APIParameters>
  <APIItem name="range" type="TRange | null" optional>
    The range to check.
  </APIItem>
</APIParameters>

<APIReturns type="boolean">
  `true` if the range exists and is expanded.
</APIReturns>
</API>

### `isForward`

Check if a range is forward (anchor point appears before focus point).

<API name="isForward">
<APIParameters>
  <APIItem name="range" type="TRange">
    The range to check.
  </APIItem>
</APIParameters>

<APIReturns type="boolean">
  `true` if the range is forward.
</APIReturns>
</API>

### `isRange`

Check if a value implements the `TRange` interface.

<API name="isRange">
<APIParameters>
  <APIItem name="value" type="any">
    The value to check.
  </APIItem>
</APIParameters>

<APIReturns type="boolean">
  `true` if the value is a range.
</APIReturns>
</API>

### `points`

Iterate through all point entries in a range.

<API name="points">
<APIParameters>
  <APIItem name="range" type="TRange">
    The range to iterate through.
  </APIItem>
</APIParameters>

<APIReturns type="Generator<PointEntry, void, undefined>">
  A generator that yields point entries.
</APIReturns>
</API>

### `start`

Get the start point of a range.

<API name="start">
<APIParameters>
  <APIItem name="range" type="TRange">
    The range to get the start point from.
  </APIItem>
</APIParameters>

<APIReturns type="Point">
  The start point of the range.
</APIReturns>
</API>

### `surrounds`

Check if a range completely surrounds another range.

<API name="surrounds">
<APIParameters>
  <APIItem name="range" type="TRange">
    The range that might surround the target.
  </APIItem>
  <APIItem name="target" type="TRange">
    The target range that might be surrounded.
  </APIItem>
</APIParameters>

<APIReturns type="boolean">
  `true` if the range surrounds the target.
</APIReturns>
</API>

## Types

### `TRange`

`TRange` objects are a set of points that refer to a specific span of a Plate document. They can define a span inside a 
single node or span across multiple nodes.

`Range` is a type alias for `TRange`.

<API name="TRange">
<APIAttributes>
  <APIItem name="anchor" type="Point">
    The start point of the range.
  </APIItem>
  <APIItem name="focus" type="Point">
    The end point of the range.
  </APIItem>
</APIAttributes>
</API>


# Text

Source: https://platejs.org/docs/api/slate/text

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Text
description: API reference for text nodes in Plate.
---

A Text node contains the actual text content of a Plate document along with any formatting properties. They are always leaf nodes in the document tree as they cannot contain any children.

```ts
type TText = {
  text: string
  [key: string]: unknown
}
```

## `TextApi`

### `decorations`

<API name="decorations">
<APIParameters>
  <APIItem name="node" type="TText">
    The text node to get leaves from.
  </APIItem>
  <APIItem name="decorations" type="DecoratedRange[]">
    The array of decorated ranges to apply.
  </APIItem>
</APIParameters>

<APIReturns type="{ leaf: TText, position?: LeafPosition }[]">
  An array of leaves and their positions. The position is undefined if there is a single leaf.
</APIReturns>
</API>

### `equals`

<API name="equals">
<APIParameters>
  <APIItem name="text" type="TText">
    The first text node to compare.
  </APIItem>
  <APIItem name="another" type="TText">
    The second text node to compare.
  </APIItem>
  <APIItem name="options" type="TextEqualsOptions" optional>
    Additional comparison options.
  </APIItem>
</APIParameters>

<APIOptions type="TextEqualsOptions">
  <APIItem name="loose" type="boolean" optional>
    If `true`, the text content is not compared. This is used to check
    whether sibling text nodes can be merged based only on their
    formatting properties.
  </APIItem>
</APIOptions>

<APIReturns type="boolean">
  `true` if the text nodes are equal according to the comparison rules.
</APIReturns>
</API>

### `isText`

<API name="isText">
<APIParameters>
  <APIItem name="value" type="any">
    The value to check.
  </APIItem>
</APIParameters>

<APIReturns type="boolean">
  `true` if the value is a valid text node.
</APIReturns>
</API>

### `isTextList`

<API name="isTextList">
<APIParameters>
  <APIItem name="value" type="any">
    The value to check.
  </APIItem>
</APIParameters>

<APIReturns type="boolean">
  `true` if the value is an array of text nodes.
</APIReturns>
</API>

### `isTextProps`

<API name="isTextProps">
<APIParameters>
  <APIItem name="props" type="any">
    The props to check.
  </APIItem>
</APIParameters>

<APIReturns type="boolean">
  `true` if the props match a partial text node structure.
</APIReturns>
</API>

### `matches`

<API name="matches">
<APIParameters>
  <APIItem name="text" type="TText">
    The text node to check.
  </APIItem>
  <APIItem name="props" type="Partial<TText>">
    The properties to match against.
  </APIItem>
</APIParameters>

<APIReturns type="boolean">
  `true` if the text node matches the properties.
</APIReturns>
</API>

## Types

### `TText`

`Text` is a type alias for `TText`.

<API name="TText">
<APIAttributes>
  <APIItem name="text" type="string">
    The text content of the node.
  </APIItem>
  <APIItem name="[key: string]" type="unknown">
    Additional formatting properties that can be added to the text node.
  </APIItem>
</APIAttributes>
</API>

### `TextEntry` 

Text entries represent a Text node and its path.

<API name="TextEntry">
<APIAttributes>
  <APIItem name="0" type="TText">
    The Text node.
  </APIItem>
  <APIItem name="1" type="Path">
    The path to the text node.
  </APIItem>
</APIAttributes>
</API>

### `DecoratedRange`

A range object that includes decoration information. Used to apply formatting or styling to specific ranges of text within a document.

### `TextOf<N>`

A utility type that extracts all possible text node types from a root node type.

<API name="TextOf">
<APIParameters>
  <APIItem name="N" type="TNode">
    The root node type to extract text types from.
  </APIItem>
</APIParameters>
</API>

### `TextIn<V>`

A utility type that extracts all text node types from a `Value` type.

<API name="TextIn">
<APIParameters>
  <APIItem name="V" type="Value">
    The `Value` type to extract text types from.
  </APIItem>
</APIParameters>
</API>

### `MarksOf<N>`

A utility type that extracts all possible mark types from a root node type. Marks are the formatting properties that can be applied to text nodes.

<API name="MarksOf">
<APIParameters>
  <APIItem name="N" type="TNode">
    The root node type to extract mark types from.
  </APIItem>
</APIParameters>
</API>

### `MarksIn<V>`

A utility type that extracts all mark types from a `Value` type. Similar to `MarksOf` but works specifically with editor `Value` types.

<API name="MarksIn">
<APIParameters>
  <APIItem name="V" type="Value">
    The `Value` type to extract mark types from.
  </APIItem>
</APIParameters>
</API>

### `MarkKeysOf<N>`

A utility type that extracts all possible mark property keys from a node type.

<API name="MarkKeysOf">
<APIParameters>
  <APIItem name="N" type="TNode">
    The node type to extract mark keys from.
  </APIItem>
</APIParameters>
</API>

# Combobox

Source: https://platejs.org/docs/combobox

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Combobox
docs:
  - route: /docs/components/inline-combobox
    title: Inline Combobox
---

<Cards>

<Card icon="mention" title="Mention" href="/docs/mention">
Insert mentions for users, pages, or any reference with `@`
</Card>

<Card icon="slash-command" title="Slash Command" href="/docs/slash-command">
Quick access to editor commands and blocks with `/`
</Card>

<Card icon="emoji" title="Emoji" href="/docs/emoji">
Insert emojis with autocomplete using `:`
</Card>

</Cards>

<PackageInfo>

## Features

- Utilities for creating trigger-based combobox functionality
- Configurable trigger characters and patterns
- Keyboard navigation and selection handling

</PackageInfo>

## Create a Combobox Plugin

<Steps>

### Installation

```bash
npm install @platejs/combobox
```

### Create Input Plugin

First, create an input plugin that will be inserted when the trigger is activated:

```tsx
import { createSlatePlugin } from 'platejs';

const TagInputPlugin = createSlatePlugin({
  key: 'tag_input',
  editOnly: true,
  node: {
    isElement: true,
    isInline: true,
    isVoid: true,
  },
});
```

### Create Main Plugin

Create your main plugin using `withTriggerCombobox`:

```tsx
import { createTSlatePlugin, type PluginConfig } from 'platejs';
import { 
  type TriggerComboboxPluginOptions, 
  withTriggerCombobox 
} from '@platejs/combobox';

type TagConfig = PluginConfig<'tag', TriggerComboboxPluginOptions>;

export const TagPlugin = createTSlatePlugin<TagConfig>({
  key: 'tag',
  node: { isElement: true, isInline: true, isVoid: true },
  options: {
    trigger: '#',
    triggerPreviousCharPattern: /^\s?$/,
    createComboboxInput: () => ({
      children: [{ text: '' }],
      type: 'tag_input',
    }),
  },
  plugins: [TagInputPlugin],
}).overrideEditor(withTriggerCombobox);
```

- `node.isElement`: Defines this as an element node (not text)
- `node.isInline`: Makes the tag element inline (not block)
- `node.isVoid`: Prevents editing inside the tag element
- `options.trigger`: Character that triggers the combobox (in this case `#`)
- `options.triggerPreviousCharPattern`: RegExp pattern that must match the character before the trigger. `/^\s?$/` allows the trigger at the start of a line or after whitespace
- `options.createComboboxInput`: Function that creates the input element node when the trigger is activated

### Create Component

Create the input element component using `InlineCombobox`:

```tsx
import { PlateElement, useFocused, useReadOnly, useSelected } from 'platejs/react';
import {
  InlineCombobox,
  InlineComboboxContent,
  InlineComboboxEmpty,
  InlineComboboxInput,
  InlineComboboxItem,
} from '@/components/ui/inline-combobox';
import { cn } from '@/lib/utils';

const tags = [
  { id: 'frontend', name: 'Frontend', color: 'blue' },
  { id: 'backend', name: 'Backend', color: 'green' },
  { id: 'design', name: 'Design', color: 'purple' },
  { id: 'urgent', name: 'Urgent', color: 'red' },
];

export function TagInputElement({ element, ...props }) {
  return (
    <PlateElement as="span" {...props}>
      <InlineCombobox element={element} trigger="#">
        <InlineComboboxInput />
        
        <InlineComboboxContent>
          <InlineComboboxEmpty>No tags found</InlineComboboxEmpty>
          
          {tags.map((tag) => (
            <InlineComboboxItem
              key={tag.id}
              value={tag.name}
              onClick={() => {
                // Insert actual tag element
                editor.tf.insertNodes({
                  type: 'tag',
                  tagId: tag.id,
                  children: [{ text: tag.name }],
                });
              }}
            >
              <span 
                className={`w-3 h-3 rounded-full bg-${tag.color}-500 mr-2`}
              />
              #{tag.name}
            </InlineComboboxItem>
          ))}
        </InlineComboboxContent>
      </InlineCombobox>
      
      {props.children}
    </PlateElement>
  );
}

export function TagElement({ element, ...props }) {
  const selected = useSelected();
  const focused = useFocused();
  const readOnly = useReadOnly();

  return (
    <PlateElement
      {...props}
      className={cn(
        'inline-block rounded-md bg-primary/10 px-1.5 py-0.5 align-baseline text-sm font-medium text-primary',
        !readOnly && 'cursor-pointer',
        selected && focused && 'ring-2 ring-ring'
      )}
      attributes={{
        ...props.attributes,
        contentEditable: false,
        'data-slate-value': element.value,
      }}
    >
      #{element.value}
      {props.children}
    </PlateElement>
  );
}
```

### Add to Editor

```tsx
import { createPlateEditor } from 'platejs/react';
import { TagPlugin, TagInputPlugin } from './tag-plugin';
import { TagElement, TagInputElement } from './tag-components';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    TagPlugin.configure({
      options: {
        triggerQuery: (editor) => {
          // Disable in code blocks
          return !editor.api.some({ match: { type: 'code_block' } });
        },
      },
    }).withComponent(TagElement),
    TagInputPlugin.withComponent(TagInputElement),
  ],
});
```

- `options.triggerQuery`: Optional function to conditionally enable/disable the trigger based on editor state

</Steps>

## Examples

[mention-demo registry content](https://platejs.org/r/mention-demo)
[slash-command-demo registry content](https://platejs.org/r/slash-command-demo)
[emoji-demo registry content](https://platejs.org/r/emoji-demo)

## Options

### TriggerComboboxPluginOptions

Configuration options for trigger-based combobox plugins.

<API name="TriggerComboboxPluginOptions">
<APIOptions>
  <APIItem name="createComboboxInput" type="(trigger: string) => TElement">
    Function to create the input node when trigger is activated.
  </APIItem>
  <APIItem name="trigger" type="RegExp | string[] | string">
    Character(s) that trigger the combobox. Can be:
    - A single character (e.g. '@')
    - An array of characters
    - A regular expression
  </APIItem>
  <APIItem name="triggerPreviousCharPattern" type="RegExp" optional>
    Pattern to match the character before trigger.
    - **Example:** `/^\s?$/` matches start of line or space
  </APIItem>
  <APIItem name="triggerQuery" type="(editor: SlateEditor) => boolean" optional>
    Custom query function to control when trigger is active.
  </APIItem>
</APIOptions>
</API>

## Hooks

### useComboboxInput

Hook for managing combobox input behavior and keyboard interactions.

<API name="useComboboxInput">
<APIOptions>
  <APIItem name="ref" type="RefObject<HTMLElement>">
    Reference to the input element.
  </APIItem>
  <APIItem name="autoFocus" type="boolean" optional>
    Auto focus the input when mounted.
    - **Default:** `true`
  </APIItem>
  <APIItem name="cancelInputOnArrowLeftRight" type="boolean" optional>
    Cancel on arrow keys.
    - **Default:** `true`
  </APIItem>
  <APIItem name="cancelInputOnBackspace" type="boolean" optional>
    Cancel on backspace at start.
    - **Default:** `true`
  </APIItem>
  <APIItem name="cancelInputOnBlur" type="boolean" optional>
    Cancel on blur.
    - **Default:** `true`
  </APIItem>
  <APIItem name="cancelInputOnDeselect" type="boolean" optional>
    Cancel when deselected.
    - **Default:** `true`
  </APIItem>
  <APIItem name="cancelInputOnEscape" type="boolean" optional>
    Cancel on escape key.
    - **Default:** `true`
  </APIItem>
  <APIItem name="cursorState" type="ComboboxInputCursorState" optional>
    Current cursor position state.
  </APIItem>
  <APIItem name="forwardUndoRedoToEditor" type="boolean" optional>
    Forward undo/redo to editor.
    - **Default:** `true`
  </APIItem>
  <APIItem name="onCancelInput" type="(cause: CancelComboboxInputCause) => void" optional>
    Callback when input is cancelled.
  </APIItem>
</APIOptions>

<APIReturns>
  <APIItem name="cancelInput" type="(cause?: CancelComboboxInputCause, focusEditor?: boolean) => void">
    Function to cancel the input.
  </APIItem>
  <APIItem name="props" type="object">
    Props for the input element.
  </APIItem>
  <APIItem name="removeInput" type="(focusEditor?: boolean) => void">
    Function to remove the input node.
  </APIItem>
</APIReturns>
</API>

### useHTMLInputCursorState

Hook for tracking cursor position in an HTML input element.

<API name="useHTMLInputCursorState">
<APIParameters>
  <APIItem name="ref" type="RefObject<HTMLInputElement>">
    Reference to the input element to track.
  </APIItem>
</APIParameters>

<APIReturns>
  <APIItem name="atStart" type="boolean">
    Whether cursor is at the start of input.
  </APIItem>
  <APIItem name="atEnd" type="boolean">
    Whether cursor is at the end of input.
  </APIItem>
</APIReturns>
</API>

# Emoji

Source: https://platejs.org/docs/emoji

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Emoji
description: Inline emoji search and toolbar emoji picking.
docs:
  - route: /docs/combobox
    title: Combobox
  - route: /docs/components/emoji-node
    title: Emoji Input Element
  - route: /docs/components/emoji-toolbar-button
    title: Emoji Toolbar Button
---

Emoji adds two insertion paths: a `:` trigger that opens an inline combobox, and a toolbar popover for browsing categories. The package owns emoji data, trigger behavior, index search, picker state, frequent emoji storage, and insertion. The registry owns the inline input element and toolbar picker UI.

[emoji-demo registry content](https://platejs.org/r/emoji-demo)

<PackageInfo>

## Features

- `:` trigger powered by `@platejs/combobox`.
- Edit-only inline void `emoji_input` node.
- Emoji search from `@emoji-mart/data`.
- Default insertion as Unicode text.
- Custom inserted node support through `createEmojiNode`.
- Toolbar popover with categories, search, preview, and frequent emoji tracking.
- Markdown shortcode deserialization to Unicode text.

</PackageInfo>

## Fast Path

<Steps>

### Add The Kit

`EmojiKit` installs `EmojiPlugin` with `@emoji-mart/data` and renders `EmojiInputPlugin` with the registry inline combobox.

[emoji-kit registry content](https://platejs.org/r/emoji-kit)

```tsx
import { createPlateEditor } from 'platejs/react';

import { EmojiKit } from '@/components/editor/plugins/emoji-kit';

export const editor = createPlateEditor({
  plugins: EmojiKit,
});
```

### Render The Inline Input

`emoji-node` debounces the search text, queries `EmojiInlineIndexSearch`, and inserts the selected emoji.

[emoji-node registry content](https://platejs.org/r/emoji-node)

### Add Toolbar Picking

`emoji-toolbar-button` renders the Radix popover picker backed by `useEmojiDropdownMenuState`.

[emoji-toolbar-button registry content](https://platejs.org/r/emoji-toolbar-button)

</Steps>

## Ownership

| Layer | Owner | What It Does |
|-------|-------|--------------|
| `@platejs/emoji` | Package | Exports `BaseEmojiPlugin`, `BaseEmojiInputPlugin`, `insertEmoji`, emoji search libraries, settings, categories, and types. |
| `@platejs/emoji/react` | Package | Exports `EmojiPlugin`, `EmojiInputPlugin`, picker hooks, and frequent emoji storage. |
| `@platejs/combobox` | Package | Provides trigger detection and transient input cleanup for the `:` flow. |
| `@emoji-mart/data` | Dependency | Provides the emoji dataset used by the registry kit. |
| `emoji-kit` | Registry | Adds `EmojiPlugin` with emoji-mart data and `EmojiInputPlugin.withComponent(EmojiInputElement)`. |
| `emoji-node` | Registry UI | Renders inline emoji search with `InlineCombobox`. |
| `emoji-toolbar-button` | Registry UI | Renders the toolbar popover, category grid, search bar, and preview. |
| `inline-combobox` | Registry UI | Renders the inline trigger input and popover primitives. |
| `@platejs/markdown` | Package | Deserializes emoji shortcodes such as `:fire:` to Unicode text. |

The emoji plugin is edit-only. It inserts text or your custom node, then the transient `emoji_input` disappears.

## Manual Setup

<Steps>

### Install Packages

```bash
npm install @platejs/emoji @emoji-mart/data
```

### Add Plugins

Use `@emoji-mart/data` when you want the full emoji dataset instead of the package default library.

```tsx
import emojiMartData from '@emoji-mart/data';
import { EmojiInputPlugin, EmojiPlugin } from '@platejs/emoji/react';
import { createPlateEditor } from 'platejs/react';

import { EmojiInputElement } from '@/components/ui/emoji-node';

export const editor = createPlateEditor({
  plugins: [
    EmojiPlugin.configure({
      options: {
        data: emojiMartData as any,
      },
    }),
    EmojiInputPlugin.withComponent(EmojiInputElement),
  ],
});
```

### Add A Toolbar Button

Render `EmojiToolbarButton` in your toolbar when users should browse emoji without typing `:`.

```tsx
import { EmojiToolbarButton } from '@/components/ui/emoji-toolbar-button';

export function FixedToolbarButtons() {
  return <EmojiToolbarButton />;
}
```

</Steps>

## Inline Flow

The inline path is a combobox flow.

| Step | Source |
|------|--------|
| Type `:` | `BaseEmojiPlugin` trigger. |
| Previous character must match `/^\s?$/` | Start of block or whitespace by default. |
| Insert transient input | `createComboboxInput` creates `{ type: KEYS.emojiInput, children: [{ text: '' }] }`. |
| Search emoji data | `EmojiInputElement` calls `EmojiInlineIndexSearch.getInstance(data).search(query).get()`. |
| Select a result | `InlineComboboxItem` removes the input and calls `insertEmoji(editor, emoji)`. |
| Insert final content | `insertEmoji` calls `createEmojiNode(emoji)` and inserts that node. |

`EmojiInputElement` sets `filter={false}` because emoji search already returns filtered results. It also uses `hideWhenNoValue`, so the popover stays closed until the user types a search value after `:`.

## Inserted Value

By default, selecting an emoji inserts the first native skin as text.

```tsx
EmojiPlugin.configure({
  options: {
    createEmojiNode: ({ skins }) => ({ text: skins[0].native }),
  },
});
```

Use `createEmojiNode` when your app stores emoji as structured inline nodes instead of text.

```tsx
EmojiPlugin.configure({
  options: {
    createEmojiNode: (emoji) => ({
      children: [{ text: emoji.id }],
      emojiId: emoji.id,
      type: 'emoji-chip',
    }),
  },
});
```

## Toolbar Picker

`EmojiToolbarButton` calls `useEmojiDropdownMenuState`, then passes the picker state into `EmojiPicker`.

| Option | Default | Use |
|--------|---------|-----|
| `closeOnSelect` | `true` | Close the toolbar popover after insertion. |
| `settings` | `EmojiSettings` | Configure categories, per-line count, button size, and frequent emoji behavior. |
| `settings.showFrequent.limit` | Package setting | Limits the frequent emoji category. |

Frequent emoji counts are stored in `window.localStorage` through `FrequentEmojiStorage`. On the server, the storage class returns the default frequent set.

## Markdown

`@platejs/markdown` deserializes emoji shortcodes to Unicode text.

```md
Launch :fire: soon
```

Serializing the resulting value writes the Unicode emoji:

```md
Launch 🔥 soon
```

## API Reference

| API | Package | Use |
|-----|---------|-----|
| `BaseEmojiPlugin` | `@platejs/emoji` | Edit-only trigger plugin with default `:`, emoji data, input creation, and text insertion. |
| `BaseEmojiInputPlugin` | `@platejs/emoji` | Edit-only inline void `emoji_input` plugin. |
| `EmojiPlugin` | `@platejs/emoji/react` | React emoji plugin with nested `EmojiInputPlugin`. |
| `EmojiInputPlugin` | `@platejs/emoji/react` | React input plugin for `EmojiInputElement`. |
| `insertEmoji(editor, emoji)` | `@platejs/emoji` | Inserts `createEmojiNode(emoji)`. |
| `EmojiInlineIndexSearch` | `@platejs/emoji` | Inline search index used by `emoji-node`. |
| `useEmojiDropdownMenuState(options?)` | `@platejs/emoji/react` | Builds toolbar popover state and picker state. |
| `useEmojiPicker(options)` | `@platejs/emoji/react` | Handles search, category focus, preview, selection, and frequent emoji updates. |
| `FrequentEmojiStorage` | `@platejs/emoji/react` | Reads and writes frequent emoji counts through localStorage. |


# Slash Command

Source: https://platejs.org/docs/slash-command

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Slash Command
docs:
  - route: https://pro.platejs.org/docs/examples/slash-command
    title: Plus
  - route: /docs/combobox
    title: Combobox
  - route: /docs/components/slash-node
    title: Slash Nodes
---

[slash-command-demo registry content](https://platejs.org/r/slash-command-demo)

<PackageInfo>

## Features

- Quick access to various editor commands
- Triggered by `/` character
- Keyboard navigation and filtering
- Customizable command groups and options

</PackageInfo>

## Kit Usage

<Steps>

### Installation

The fastest way to add slash command functionality is with the `SlashKit`, which includes pre-configured `SlashPlugin` and `SlashInputPlugin` along with their [Plate UI](/docs/installation/plate-ui) components.

[slash-kit registry content](https://platejs.org/r/slash-kit)

- [`SlashInputElement`](/docs/components/slash-node): Renders the slash command combobox with predefined options

### Add Kit

```tsx
import { createPlateEditor } from 'platejs/react';
import { SlashKit } from '@/components/editor/plugins/slash-kit';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    ...SlashKit,
  ],
});
```

</Steps>

## Manual Usage

<Steps>

### Installation

```bash
npm install @platejs/slash-command
```

### Add Plugins

```tsx
import { SlashPlugin, SlashInputPlugin } from '@platejs/slash-command/react';
import { createPlateEditor } from 'platejs/react';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    SlashPlugin,
    SlashInputPlugin,
  ],
});
```

### Configure Plugins

```tsx
import { SlashPlugin, SlashInputPlugin } from '@platejs/slash-command/react';
import { createPlateEditor } from 'platejs/react';
import { SlashInputElement } from '@/components/ui/slash-node';
import { KEYS } from 'platejs';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    SlashPlugin.configure({
      options: {
        trigger: '/',
        triggerPreviousCharPattern: /^\s?$/,
        triggerQuery: (editor) =>
          !editor.api.some({
            match: { type: editor.getType(KEYS.codeBlock) },
          }),
      },
    }),
    SlashInputPlugin.withComponent(SlashInputElement),
  ],
});
```

- `options.trigger`: Character that triggers the slash command combobox (default: `/`)
- `options.triggerPreviousCharPattern`: RegExp pattern for character before trigger
- `options.triggerQuery`: Function to determine when slash commands should be enabled
- `withComponent`: Assigns the UI component for the slash command interface

</Steps>

## Usage

How to use slash commands:

1. Type `/` anywhere in your document to open the slash menu
2. Start typing to filter options or use arrow keys to navigate
3. Press Enter or click to select an option
4. Press Escape to close the menu without selecting

Available options include:
- Text blocks (paragraphs, headings)
- Lists (bulleted, numbered, to-do)
- Advanced blocks (tables, code blocks, callouts)
- Inline elements (dates, equations)

<Callout type="info">
  Use keywords to quickly find options. For example, type '/ul' for Bulleted List or '/h1' for Heading 1.
</Callout>

## Plate Plus

[slash-command-pro registry content](https://platejs.org/r/slash-command-pro)

## Plugins

### SlashPlugin

Plugin for slash command functionality. Extends [TriggerComboboxPluginOptions](/docs/combobox#triggercomboboxpluginoptions).

<API name="SlashPlugin">
<APIOptions>
  <APIItem name="trigger" type="string" optional>
    Character that triggers slash command combobox.
    - **Default:** `'/'`
  </APIItem>
  <APIItem name="triggerPreviousCharPattern" type="RegExp" optional>
    RegExp to match character before trigger.
    - **Default:** `/^\s?$/`
  </APIItem>
  <APIItem name="createComboboxInput" type="() => TComboboxInputElement" optional>
    Function to create combobox input element.
    - **Default:** 
    ```tsx
    () => ({
      children: [{ text: '' }],
      type: KEYS.slashInput,
    });
    ```
  </APIItem>
  <APIItem name="triggerQuery" type="(editor: PlateEditor) => boolean" optional>
    Function to determine when slash commands should be enabled. Useful for disabling in certain contexts like code blocks.
  </APIItem>
</APIOptions>
</API>

### SlashInputPlugin

Handles the input behavior for slash command insertion.


# Exit Break

Source: https://platejs.org/docs/exit-break

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Exit Break
---

[exit-break-demo registry content](https://platejs.org/r/exit-break-demo)

<PackageInfo>

## Features

- Exit from nested block structures (like code blocks, tables, columns) using keyboard shortcuts.
- Automatically determines the appropriate exit point based on block hierarchy.

</PackageInfo>

## Kit Usage

<Steps>

### Installation

The fastest way to add exit break functionality is with the `ExitBreakKit`, which includes pre-configured `ExitBreakPlugin` with keyboard shortcuts.

[exit-break-kit registry content](https://platejs.org/r/exit-break-kit)

### Add Kit

```tsx
import { createPlateEditor } from 'platejs/react';
import { ExitBreakKit } from '@/components/editor/plugins/exit-break-kit';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    ...ExitBreakKit,
  ],
});
```

</Steps>

## Manual Usage

<Steps>

### Add Plugin

```tsx
import { ExitBreakPlugin } from 'platejs';
import { createPlateEditor } from 'platejs/react';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    ExitBreakPlugin,
  ],
});
```

### Configure Plugin

```tsx
import { ExitBreakPlugin } from 'platejs';
import { createPlateEditor } from 'platejs/react';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    ExitBreakPlugin.configure({
      shortcuts: {
        insert: { keys: 'mod+enter' },
        insertBefore: { keys: 'mod+shift+enter' },
      },
    }),
  ],
});
```

- `shortcuts.insert`: Defines a keyboard [shortcut](/docs/plugin-shortcuts) to exit and insert block after.
- `shortcuts.insertBefore`: Defines a keyboard [shortcut](/docs/plugin-shortcuts) to exit and insert block before.

</Steps>

## Keyboard Shortcuts

<KeyTable>
  <KeyTableItem hotkey="Cmd + Enter">
    Exit the current block structure and insert a new block after.
  </KeyTableItem>
  <KeyTableItem hotkey="Cmd + Shift + Enter">
    Exit the current block structure and insert a new block before.
  </KeyTableItem>
</KeyTable>

## Plugins

### `ExitBreakPlugin`

Provides transforms to exit nested block structures automatically. The plugin determines the appropriate exit point by finding the first ancestor that allows standard block siblings.

<API name="ExitBreakPlugin">
<APIOptions>
  <APIItem name="shortcuts" type="object" optional>
    Keyboard shortcuts configuration.
    <APISubList>
      <APISubListItem parent="shortcuts" name="insert" type="Shortcut" optional>
        Shortcut to exit and insert block after.
        - **Example:** `{ keys: 'mod+enter' }`
      </APISubListItem>
      <APISubListItem parent="shortcuts" name="insertBefore" type="Shortcut" optional>
        Shortcut to exit and insert block before.
        - **Example:** `{ keys: 'mod+shift+enter' }`
      </APISubListItem>
    </APISubList>
  </APIItem>
</APIOptions>
</API>

## How Exit Break Works

Exit break uses the [`isStrictSiblings`](/docs/api/core/plate-plugin#isstrictsiblings) property to determine where to insert new blocks when exiting nested structures.

### Exit Point Determination

When you trigger exit break:

1. Starts from the current text block (e.g., paragraph inside a table cell)
2. Traverses up the document tree looking at each ancestor
3. Finds the first ancestor with `isStrictSiblings: false`
4. Inserts a new paragraph as a sibling to that ancestor

### Examples

**Code Block:**
```tsx
<codeblock>                              // ← Exit point (top-level block)
  <codeline>code|</codeline>             // ← Starting position
</codeblock>
<p>|</p>                                 // ← New paragraph inserted here
```

**Table in Column (exits at table level):**
```tsx
// First exit
<column_group>                           
  <column>                               
    <table>                              // ← Exit point (isStrictSiblings: false)
      <tr>                               // isStrictSiblings: true
        <td>                             // isStrictSiblings: true
          <p>content|</p>                // ← Starting position
        </td>
      </tr>
    </table>
    <p>|</p>                             // ← New paragraph inserted here
  </column>
</column_group>

// Second exit
<column_group>                           // ← Exit point (isStrictSiblings: false)
  <column>                               // isStrictSiblings: true
    <table>                              
      <tr>                               
        <td>                             
          <p>content</p>
        </td>
      </tr>
    </table>
    <p>|</p>                             // ← Starting position
  </column>
</column_group>
<p>|</p>                                 // ← New paragraph inserted here
```

### Custom Plugin Configuration

Configure [`isStrictSiblings`](/docs/api/core/plate-plugin#isstrictsiblings) for custom plugins:

```tsx
// Table structure
const CustomTablePlugin = createSlatePlugin({
  key: 'table',
  node: {
    isElement: true,
    // isStrictSiblings: false (default) - allows paragraph siblings
  },
});

const CustomTableRowPlugin = createSlatePlugin({
  key: 'tr',
  node: {
    isElement: true,
    isStrictSiblings: true, // Only allows tr siblings
  },
});

const CustomTableCellPlugin = createSlatePlugin({
  key: 'td',
  node: {
    isElement: true,
    isStrictSiblings: true, // Only allows td/th siblings
  },
});


# Forced Layout

Source: https://platejs.org/docs/forced-layout

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Forced Layout
description: Path-based normalization for required document structure.
docs:
  - route: /docs/trailing-block
    title: Trailing Block
  - route: /docs/single-block
    title: Single Block
  - route: /docs/plugin-rules
    title: Plugin Rules
---

Forced Layout is the `NormalizeTypesPlugin` pattern for pinning document positions to required node types. Use it for fixed slots such as "the first block is an H1." Use [Trailing Block](/docs/trailing-block) when the requirement is "the document always ends with a paragraph."

<PackageInfo>

## Features

- Path-indexed normalization rules.
- `strictType` for rewriting an existing node to a required type.
- `type` for inserting a missing node without rewriting an existing node.
- Root-only normalization pass.
- Automatic block creation through `editor.api.create.block`.
- `onError` callback when insertion fails.
- Conditional enabling through normal plugin `enabled` configuration.

</PackageInfo>

## Fast Path

Add `NormalizeTypesPlugin` when specific paths must exist or hold a specific block type.

```tsx
import { KEYS, NormalizeTypesPlugin } from 'platejs';
import { createPlateEditor } from 'platejs/react';

export const editor = createPlateEditor({
  plugins: [
    NormalizeTypesPlugin.configure({
      options: {
        rules: [
          { path: [0], strictType: KEYS.h1 },
          { path: [1], type: KEYS.p },
        ],
      },
    }),
  ],
});
```

This keeps the first block as an H1 and inserts a paragraph at path `[1]` when that node is missing.

## Ownership

| Layer | Owner | What It Does |
|-------|-------|--------------|
| `NormalizeTypesPlugin` | `platejs` / `@platejs/utils` | Stores `rules` and `onError`, then overrides normalization. |
| `withNormalizeTypes` | `@platejs/utils` | Runs the path rules during root normalization. |
| `NodeApi.get(editor, path)` | `@platejs/slate` | Reads the node at the configured path. |
| `editor.api.create.block` | Core editor API | Creates inserted or replacement block props. |
| Playground demo | Registry example | Enables a first-block H1 rule when the playground id is `forced-layout`. |

There is no `ForcedLayoutPlugin` and no `forced-layout-kit`. The public plugin is `NormalizeTypesPlugin`.

## Rule Semantics

`NormalizeTypesPlugin` runs only when the root editor node normalizes. It checks rules in order and stops the current normalization pass after the first rule that changes the document.

| Rule Shape | Existing Node | Missing Node |
|------------|---------------|--------------|
| `{ path, strictType }` | If the node is an element with a different type, Plate sets its block props to `strictType` and preserves children. | Plate inserts `editor.api.create.block({ type: strictType })`. |
| `{ path, type }` | Plate leaves the node alone. | Plate inserts `editor.api.create.block({ type })`. |

Use `strictType` for required slots. Use `type` for optional slots that should be filled only when empty.

## Error Handling

If inserting a missing node fails, `withNormalizeTypes` calls `onError(error)` and falls through to the editor's normal `normalizeNode`.

```tsx
import { NormalizeTypesPlugin } from 'platejs';

export const requiredTitle = NormalizeTypesPlugin.configure({
  options: {
    onError: (error) => {
      console.error(error);
    },
    rules: [{ path: [0], strictType: 'h1' }],
  },
});
```

Keep `onError` small. A normalization callback should report or collect the failure, not mutate the same path again.

## Choosing The Right Utility

| Need | Use |
|------|-----|
| First block must be a title | `NormalizeTypesPlugin` with `strictType`. |
| A missing slot should be inserted | `NormalizeTypesPlugin` with `type`. |
| Editor may only contain one root block | [Single Block](/docs/single-block). |
| Editor must end with a paragraph | [Trailing Block](/docs/trailing-block). |
| Pressing Enter should exit or reset a block | [Plugin Rules](/docs/plugin-rules). |

Forced layout is for absolute paths. It is not a schema engine for every possible nested node shape.

## Playground Toggle

The registry playground demonstrates this pattern by enabling the plugin only for the `forced-layout` example id.

```tsx
NormalizeTypesPlugin.configure({
  enabled: id === 'forced-layout',
  options: {
    rules: [{ path: [0], strictType: 'h1' }],
  },
});
```

That example keeps the first playground block as an H1 while leaving the rest of the editor to normal Plate behavior.

## API Reference

| API | Package | Use |
|-----|---------|-----|
| `NormalizeTypesPlugin` | `platejs` / `@platejs/utils` | Path-based type normalization plugin. |
| `NormalizeTypesConfig.options.rules` | `@platejs/utils` | Ordered list of path rules. Defaults to `[]`. |
| `Rule.path` | `@platejs/utils` | Slate `Path` where the rule applies. |
| `Rule.strictType` | `@platejs/utils` | Required type for an existing or missing node. |
| `Rule.type` | `@platejs/utils` | Type for a missing node only. |
| `NormalizeTypesConfig.options.onError` | `@platejs/utils` | Called when inserting a missing node throws. |


# Single Block

Source: https://platejs.org/docs/single-block

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Single Block
description: Restrict an editor to one root block or one line of text.
docs:
  - route: /docs/examples/single-block
    title: Demo
  - route: /docs/trailing-block
    title: Trailing Block
---

Single Block provides two input constraints: one root block with soft breaks, or one line with no breaks. Both plugins disable `TrailingBlockPlugin` while enabled and collapse extra root blocks during normalization.

[single-block-demo registry content](https://platejs.org/r/single-block-demo)

<PackageInfo>

## Features

- `SingleBlockPlugin` keeps one root block and converts Enter to a soft break.
- `SingleLinePlugin` keeps one root block and removes all line break characters.
- Root normalization merges extra blocks into the first block.
- Both plugins disable `TrailingBlockPlugin`.
- Demo toggle for switching between single-block and single-line behavior.

</PackageInfo>

## Fast Path

Use `SingleBlockPlugin` when the field may contain line breaks.

```tsx
import { SingleBlockPlugin } from 'platejs';
import { createPlateEditor } from 'platejs/react';

export const editor = createPlateEditor({
  plugins: [SingleBlockPlugin],
});
```

Use `SingleLinePlugin` when the field must be plain one-line text.

```tsx
import { SingleLinePlugin } from 'platejs';
import { createPlateEditor } from 'platejs/react';

export const editor = createPlateEditor({
  plugins: [SingleLinePlugin],
});
```

## Ownership

| Layer | Owner | What It Does |
|-------|-------|--------------|
| `SingleBlockPlugin` | `platejs` / `@platejs/utils` | Keeps one root block and preserves line breaks as text. |
| `SingleLinePlugin` | `platejs` / `@platejs/utils` | Keeps one root block and strips line break characters. |
| `TrailingBlockPlugin` | `@platejs/utils` | Disabled by both plugins through `override.enabled`. |
| `single-block-demo` | Registry example | Lets users toggle between single-block and single-line mode. |

These plugins are editor constraints, not schema validation. They rewrite editor content during normalization.

## Behavior

| Plugin | Enter | Soft Break | Extra Root Blocks | Existing Text Breaks |
|--------|-------|------------|-------------------|----------------------|
| `SingleBlockPlugin` | Calls `editor.tf.insertSoftBreak()`. | Preserved as `\n`. | Merged into the first block with `\n` separators. | Preserved. |
| `SingleLinePlugin` | No-op. | No-op. | Merged into the first block with no separator. | Removes `\r`, `\n`, `\r\n`, `\u2028`, and `\u2029`. |

Use single-block mode for descriptions, comments, or titles that may wrap across lines. Use single-line mode for labels, slugs, short titles, and command inputs.

## Normalization

Both plugins override `normalizeNode`.

| Case | Result |
|------|--------|
| Root has one block | Leaves the value alone. |
| Root has multiple blocks with `SingleBlockPlugin` | Inserts `\n` at the start of each next block, then merges it into the first block. |
| Root has multiple blocks with `SingleLinePlugin` | Merges each next block into the first block without a separator. |
| Text node contains line separators with `SingleLinePlugin` | Replaces the text with the filtered one-line string. |

The merge happens inside `editor.tf.withoutNormalizing`, so the root collapse finishes as one normalization pass.

## Demo Toggle

The registry example switches plugins from a checkbox.

```tsx
import { SingleBlockPlugin, SingleLinePlugin } from 'platejs';

const plugins = [
  isSingleBlock ? SingleBlockPlugin : SingleLinePlugin,
];
```

`Single Block Mode` keeps pasted lines as `\n`. Turning it off switches to single-line mode and removes line breaks.

## API Reference

| API | Package | Use |
|-----|---------|-----|
| `SingleBlockPlugin` | `platejs` / `@platejs/utils` | One root block with soft breaks preserved. |
| `SingleLinePlugin` | `platejs` / `@platejs/utils` | One root block with all line breaks removed. |
| `KEYS.singleBlock` | `platejs` / `@platejs/utils` | Plugin key for `SingleBlockPlugin`. |
| `KEYS.singleLine` | `platejs` / `@platejs/utils` | Plugin key for `SingleLinePlugin`. |
| `override.enabled.trailingBlock` | Plugin override | Set to `false` by both plugins. |


# Trailing Block

Source: https://platejs.org/docs/trailing-block

## Registry URLs

- Components index: https://platejs.org/r/registry.json
- Docs index: https://platejs.org/r/registry-docs.json
- Component content: https://platejs.org/r/{name}

Any `<ComponentSource name="..." />` or `<ComponentPreview name="..." />` in this page can be resolved at `https://platejs.org/r/{name}`.

---

---
title: Trailing Block
description: Keep a required block at the end of an editor or nested level.
docs:
  - route: /docs/single-block
    title: Single Block
  - route: /docs/forced-layout
    title: Forced Layout
---

Trailing Block inserts a required block when the last node at a target level is missing or has the wrong type. `EditorKit` includes `TrailingBlockPlugin` so full Plate editors always end with a paragraph. Single-block and single-line editors disable it because they intentionally keep one root block.

<PackageInfo>

## Features

- Default trailing type from the editor paragraph plugin.
- Empty-editor protection.
- Root or nested target level.
- `allow`, `exclude`, `filter`, and `maxLevel` query filters.
- Custom insertion wrapper through `options.insert`.
- Built into `EditorKit`.

</PackageInfo>

## Fast Path

Add `TrailingBlockPlugin` when users need a safe place to continue typing after blocks such as headings, tables, media, or columns.

```tsx
import { TrailingBlockPlugin } from 'platejs';
import { createPlateEditor } from 'platejs/react';

export const editor = createPlateEditor({
  plugins: [TrailingBlockPlugin],
});
```

`TrailingBlockPlugin` defaults to the editor's paragraph type.

## Ownership

| Layer | Owner | What It Does |
|-------|-------|--------------|
| `TrailingBlockPlugin` | `platejs` / `@platejs/utils` | Stores trailing block options and overrides normalization. |
| `withTrailingBlock` | `@platejs/utils` | Checks the last node and inserts the trailing block when needed. |
| `editor.api.last([], { level })` | Core editor API | Finds the last node at the configured depth. |
| `queryNode(lastChild, query)` | `@platejs/slate` | Applies `allow`, `exclude`, `filter`, and `maxLevel`. |
| `EditorKit` | Registry | Adds `TrailingBlockPlugin` after editing plugins. |
| `SuggestionKit` | Registry | Wraps trailing block insertion in `suggestion.withoutSuggestions`. |

There is no dedicated trailing-block UI. The plugin is a normalizer.

## Configure The Type

Use `type` when the trailing block should be something other than the default paragraph.

```tsx
import { KEYS, TrailingBlockPlugin } from 'platejs';

export const trailingBlockPlugin = TrailingBlockPlugin.configure({
  options: {
    type: KEYS.p,
  },
});
```

The default is already `editor.getType(KEYS.p)`, so most editors can use the plugin directly.

## Query Filters

The plugin inserts only when there is no last node, or when the last node type differs from `type` and passes the query filters.

```tsx
import { KEYS, TrailingBlockPlugin } from 'platejs';

export const trailingBlockPlugin = TrailingBlockPlugin.configure({
  options: {
    exclude: [KEYS.h1],
    type: KEYS.p,
  },
});
```

With that configuration, a trailing paragraph is not inserted after an H1. Use `allow` for the inverse rule, `filter` for a custom node-entry predicate, and `maxLevel` to limit which paths pass the query.

## Nested Level

`level` changes where the plugin looks for the last node.

| `level` | Target |
|---------|--------|
| `0` | Last root block. |
| `1` | Last child inside the last root-level container. |

```tsx
TrailingBlockPlugin.configure({
  options: {
    level: 1,
    type: 'p',
  },
});
```

Use nested levels when a constrained container must always end with a text block.

## Custom Insert

`options.insert` lets another plugin wrap the generated insertion. The registry suggestion kit uses it so normalization-generated paragraphs do not create suggestion marks.

```tsx
import { SuggestionPlugin } from '@platejs/suggestion/react';
import { TrailingBlockPlugin } from 'platejs';

TrailingBlockPlugin.configure({
  options: {
    insert: (editor, { insert }) => {
      editor.getApi(SuggestionPlugin).suggestion.withoutSuggestions(insert);
    },
  },
});
```

The callback receives the editor, insertion path, target type, and an `insert()` function. Call `insert()` exactly once unless you are intentionally replacing the default insertion.

## Behavior

| Case | Result |
|------|--------|
| Empty editor | Inserts a block at `[0]`. |
| Last node already matches `type` | Falls through to the base `normalizeNode`. |
| Last node has another type and passes query filters | Inserts the trailing block at `PathApi.next(lastChildPath)`. |
| Last node is excluded by query filters | Does not insert. |

The inserted node comes from `editor.api.create.block({ type: trailingType }, at)`.

## API Reference

| API | Package | Use |
|-----|---------|-----|
| `TrailingBlockPlugin` | `platejs` / `@platejs/utils` | Normalizer that ensures a trailing block exists. |
| `TrailingBlockConfig.options.type` | `@platejs/utils` | Block type to insert. Defaults to the editor paragraph type. |
| `TrailingBlockConfig.options.level` | `@platejs/utils` | Depth used by `editor.api.last`. Defaults to `0`. |
| `TrailingBlockConfig.options.insert` | `@platejs/utils` | Custom wrapper around the generated insertion. |
| `TrailingBlockConfig.options.allow` | `@platejs/slate` query | Only insert after matching types. |
| `TrailingBlockConfig.options.exclude` | `@platejs/slate` query | Skip insertion after matching types. |
| `TrailingBlockConfig.options.filter` | `@platejs/slate` query | Custom predicate for the last node entry. |
| `TrailingBlockConfig.options.maxLevel` | `@platejs/slate` query | Skip entries deeper than this path length. |