Plate
PlateEditorsTemplates
GitHub16kGitHub
DiscordDiscord
    • Overview
    • Why This Fork
    • Examples
    • Installing Plite
    • Adding Event Handlers
    • Defining Custom Elements
    • Applying Custom Formatting
    • Executing Commands
    • Saving to a Database
    • Canonical Change Substrate
    • Improving Performance
    • Interfaces
    • Nodes
    • Locations
    • Transforms
    • Document Changes
    • Commands
    • Editor
    • Plugins
    • Rendering
    • Serializing
    • Normalizing
    • Using TypeScript
    • Roots
    • Document State
    • Editing Behavior
    • Selection And DOM
    • Clipboard And Paste
    • Decorations, annotations, and widgets
    • Schema
    • Anchor API
    • Location API
    • Path API
    • PointEntry API
    • Point API
    • Range API
    • Selection API
    • Location Types APIs
    • Span API
    • Editor
    • Element API
    • NodeEntry API
    • Node API
    • Node Types APIs
    • Text API
    • Debug Value Scrubbing
    • Transforms API
    • Plite DOM
    • History Editor API
    • History Plugin Setup
    • History
    • Plite History
    • Plite Hyperscript
    • Plite PaginationExperimental
    • Annotations
    • DOM Coverage Boundaries
    • Editable Component
    • External Text Views
    • Plite React Event Handling
    • Virtualized Rendering
    • Plite React Hooks
    • React Editor Setup
    • React Editor
    • Plite React
    • Plite Component
    • Plite Yjs
    • Plite
    • Migration
    • Contributing
    • FAQ
    • Resources

Using TypeScript

PreviousNext

Type custom Plite values, elements, text nodes, and React editors with value generics.

Plite types custom document models through editor value generics. Define the element and text shapes for your editor, create a Value from the element union, then pass that value to createEditor<Value>() or useEditor<Value>() when React owns the editor lifetime.

Defining element and text types

import { type ElementOf, type TextOf, type ValueOf } from "plitejs";
import { useEditor, type Editor } from "plitejs/react";
 
type CustomText = {
NormalizingRoots

On This Page

Defining element and text typesAnnotating initial valuesWorking with nodesMultiple document models
Build your editor
Production-ready AI template and reusable components.
Get all-access
text
:
string
;
bold
?:
true
};
type ParagraphElement = {
type: "paragraph";
children: CustomText[];
};
type HeadingElement = {
type: "heading";
level: number;
children: CustomText[];
};
type CustomValue = (ParagraphElement | HeadingElement)[];
type CustomEditor = Editor<CustomValue>;
const useCustomEditor = () => {
const editor = useEditor<CustomValue>();
type CustomElement = ElementOf<typeof editor>;
type EditorText = TextOf<typeof editor>;
type EditorValue = ValueOf<typeof editor>;
return editor;
};
import { type ElementOf, type TextOf, type ValueOf } from "plitejs";
import { useEditor, type Editor } from "plitejs/react";
 
type CustomText = { text: string; bold?: true };
 
type ParagraphElement = {
  type: "paragraph";
  children: CustomText[];
};
 
type HeadingElement = {
  type: "heading";
  level: number;
  children: CustomText[];
};
 
type CustomValue = (ParagraphElement | HeadingElement)[];
type CustomEditor = Editor<CustomValue>;
 
const useCustomEditor = () => {
  const editor = useEditor<CustomValue>();
 
  type CustomElement = ElementOf<typeof editor>;
  type EditorText = TextOf<typeof editor>;
  type EditorValue = ValueOf<typeof editor>;
 
  return editor;
};

Annotating initial values

Annotate the editor's initial value with your value type.

import { Editable, EditorRoot, useEditor } from "plitejs/react";
 
type CustomText = { text: string; bold?: true };
type ParagraphElement = { type: "paragraph"; children: CustomText[] };
type CustomValue = ParagraphElement[];
 
const initialValue: CustomValue = [
  {
    type: "paragraph",
    children: [{ text: "A line of text in a paragraph." }],
  },
];
 
const App = () => {
  const editor = useEditor<CustomValue>({ initialValue });
 
  return (
    <EditorRoot editor={editor}>
      <Editable />
    </EditorRoot>
  );
};
import { Editable, EditorRoot, useEditor } from "plitejs/react";
 
type CustomText = { text: string; bold?: true };
type ParagraphElement = { type: "paragraph"; children: CustomText[] };
type CustomValue = ParagraphElement[];
 
const initialValue: CustomValue = [
  {
    type: "paragraph",
    children: [{ text: "A line of text in a paragraph." }],
  },
];
 
const App = () => {

Working with nodes

Use exported helper types to derive the document types from an editor instead of duplicating unions at every call site.

import type { ElementOf, TextOf, ValueOf } from "plitejs";
 
type CustomElement = ElementOf<typeof editor>;
type CustomText = TextOf<typeof editor>;
type CustomValue = ValueOf<typeof editor>;
import type { ElementOf, TextOf, ValueOf } from "plitejs";
 
type CustomElement = ElementOf<typeof editor>;
type CustomText = TextOf<typeof editor>;
type CustomValue = ValueOf<typeof editor>;

When reading a generic Node, narrow it before accessing element-specific properties.

import { ElementApi, type Node } from "plitejs";
 
const isParagraph = (node: Node) =>
  ElementApi.isElement(node) && node.type === "paragraph";
import { ElementApi, type Node } from "plitejs";
 
const isParagraph = (node: Node) =>
  ElementApi.isElement(node) && node.type === "paragraph";

Multiple document models

Use a different Value type for each editor model.

import { createEditor } from "plitejs";
 
type ArticleValue = {
  type: "paragraph" | "heading";
  children: { text: string; bold?: true }[];
}[];
type CommentValue = {
  type: "paragraph";
  children: { text: string }[];
}[];
 
const articleEditor = createEditor<ArticleValue>();
const commentEditor = createEditor<CommentValue>();
import { createEditor } from "plitejs";
 
type ArticleValue = {
  type: "paragraph" | "heading";
  children: { text: string; bold?: true }[];
}[];
type CommentValue = {
  type: "paragraph";
  children: { text: string }[];
}[];
 
const articleEditor = createEditor<ArticleValue>();
const commentEditor = createEditor<CommentValue>();

Each editor carries its value through ValueOf<typeof editor>, ElementOf<typeof editor>, and TextOf<typeof editor>.

const
editor
=
useEditor
<
CustomValue
>({ initialValue });
return (
<EditorRoot editor={editor}>
<Editable />
</EditorRoot>
);
};