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.
Create Project
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.
To begin with Vite, create a new project and select the React + TypeScript template:
pnpm 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.
pnpm add 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:
// tsconfig.json
{
"compilerOptions": {
// ... other options
"module": "esnext", // or commonjs if your setup requires it and handles ESM interop
"moduleResolution": "bundler",
// ... other options
},
}
If you cannot use "moduleResolution": "bundler"
or are on an older TypeScript version, please see our full TypeScript guide for alternative configurations using path aliases.
Create Your First Editor
Start by creating a basic editor component. This example sets up a simple editor.
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>
);
}
usePlateEditor
creates a memoized editor instance, ensuring stability across re-renders. For a non-memoized version, use createPlateEditor
from platejs/react
.
'use client';
import { Plate, usePlateEditor } from 'platejs/react';
import { Editor, EditorContainer } from '@/components/ui/editor';
export default function MyEditorPage() {
const editor = usePlateEditor();
return (
<Plate editor={editor}>
<EditorContainer>
<Editor placeholder="Type your amazing content here..." />
</EditorContainer>
</Plate>
);
}
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.
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>
);
}
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.
'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';
// import { Bold, Italic, Underline } from 'lucide-react'; // Example icons
const initialValue: Value = [
{
children: [
{ text: 'Hello! Try out the ' },
{ bold: true, text: 'bold' },
{ text: ', ' },
{ italic: true, text: 'italic' },
{ text: ', and ' },
{ text: 'underline', underline: true },
{ text: ' formatting.' },
],
type: 'p',
},
];
export default function MyEditorPage() {
const editor = usePlateEditor({
plugins: [BoldPlugin, ItalicPlugin, UnderlinePlugin],
value: initialValue,
});
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>
);
}
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.
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: [{ text: 'This is a quote.' }],
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>
);
}
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.
'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: [{ text: 'This is a quote.' }],
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">
<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>
</FixedToolbar>
<EditorContainer>
<Editor placeholder="Type your amazing content here..." />
</EditorContainer>
</Plate>
);
}
Handling Editor Value
To make the editor's content persistent, let's integrate state management to save and load the editor's value.
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: [{ text: 'This is a quote.' }],
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>
);
}
Value Management
The example above demonstrates a basic pattern for managing editor value:
- Initial value is set through the
value
option inusePlateEditor
- 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
'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: [{ text: 'This is a quote.' }],
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(
`nextjs-plate-value-demo-${new Date().toISOString().split('T')[0]}`
);
return savedValue ? JSON.parse(savedValue) : initialValue;
},
});
return (
<Plate
onChange={({ value }) => {
localStorage.setItem(
`nextjs-plate-value-demo-${new Date().toISOString().split('T')[0]}`,
JSON.stringify(value)
);
}}
editor={editor}
>
<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>
);
}
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
- Or continue styling manually using CSS, CSS-in-JS libraries, or your preferred styling solution
- Add 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 yourplugins
array. - Build a Toolbar: Create React components for toolbar buttons that use the Editor 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. - Learn More: