> The official editor for editing Portable Text – the JSON based rich text specification for modern content editing platforms.

Get started with the Portable Text Editor

This library provides you with the building blocks to create a completely custom editor experience built on top of Portable Text. We recommend checking out the official documentation. The following guide includes the basics to get your started.

In order to set up an editor you'll need to:

- Create a schema that defines the rich text and block content elements.
- Create a toolbar to toggle and insert these elements.
- Write render functions to style and display each element type in the editor.
- Render the editor.

Check out the Portable Text Playground for a comprehensive example of the editor in action.

$3

``sh


npm

`

Next, in your app or the component you're building, import EditorProvider, PortableTextEditable, defineSchema, EventListenerPlugin, and the types in the code below.

`tsx
// App.tsx
import {
defineSchema,
EditorProvider,
PortableTextEditable,
} from '@portabletext/editor'
import type {
PortableTextBlock,
RenderDecoratorFunction,
RenderStyleFunction,
} from '@portabletext/editor'
import {EventListenerPlugin} from '@portabletext/editor/plugins'
`

$3

Before you can render the editor, you need a schema. The editor schema configures the types of content rendered by the editor.

We'll start with a schema that includes some common rich text elements.

> [!NOTE]
> This guide includes a limited set of schema types, or rich text elements, to get you started. See the rendering guide for additional examples.

`tsx
// App.tsx
// ...
const schemaDefinition = defineSchema({
// Decorators are simple marks that don't hold any data
decorators: [{name: 'strong'}, {name: 'em'}, {name: 'underline'}],
// Styles apply to entire text blocks
// There's always a 'normal' style that can be considered the paragraph style
styles: [
{name: 'normal'},
{name: 'h1'},
{name: 'h2'},
{name: 'h3'},
{name: 'blockquote'},
],

// The types below are left empty for this example.
// See the rendering guide to learn more about each type.

// Annotations are more complex marks that can hold data (for example, hyperlinks).
annotations: [],
// Lists apply to entire text blocks as well (for example, bullet, numbered).
lists: [],
// Inline objects hold arbitrary data that can be inserted into the text (for example, custom emoji).
inlineObjects: [],
// Block objects hold arbitrary data that live side-by-side with text blocks (for example, images, code blocks, and tables).
blockObjects: [],
})
`

Learn more about the different types that exist in schema in the Portable Text Overview.

$3

With a schema defined, you have enough to render the editor. It won't do much yet, but you can confirm your progress.

Add useState from React, then scaffold out a basic application component. For example:

`tsx
// app.tsx
import {
defineSchema,
EditorProvider,
PortableTextEditable,
} from '@portabletext/editor'
import type {
PortableTextBlock,
RenderDecoratorFunction,
RenderStyleFunction,
} from '@portabletext/editor'
import {EventListenerPlugin} from '@portabletext/editor/plugins'
import {useState} from 'react'

const schemaDefinition = defineSchema({
/ your schema from the previous step /
})

function App() {
// Set up the initial state getter and setter. Leave the starting value as undefined for now.
const [value, setValue] = useState | undefined>(
undefined,
)

return (
<>
initialConfig={{
schemaDefinition,
initialValue: value,
}}
>
on={(event) => {
if (event.type === 'mutation') {
setValue(event.value)
}
}}
/>
// Add an optional style to see it more easily on the page
style={{border: '1px solid black', padding: '0.5em'}}
/>


)
}

export default App
`

Include the App component in your application and run it. You should see an outlined editor that accepts text, but doesn't do much else.

$3

At this point the PTE only has a schema, but it doesn't know how to render anything. Fix that by creating render functions for each property in the schema.

Start by creating a render function for styles.

`tsx
const renderStyle: RenderStyleFunction = (props) => {
if (props.schemaType.value === 'h1') {
return

{props.children}

- They take in props and return JSX elements.
- They use the schema to make decisions.
- They return JSX and pass children as a fallback.

With this in mind, continue for the remaining schema types.

Create a render function for decorators.

`tsx
const renderDecorator: RenderDecoratorFunction = (props) => {
if (props.value === 'strong') {
return {props.children}
}
if (props.value === 'em') {
return {props.children}
}
if (props.value === 'underline') {
return {props.children}
}
return <>{props.children}
}
`

> [!NOTE]
> By default, text is rendered as an inline span element in the editor. While most render functions return a fragment (<>) as the fallback, make sure block level elements return blocks, like

  {JSON.stringify(value, null, 2)}