` as a normal block with code marks. To convert fenced code blocks into a custom `code` block type:

```ts
const codeBlockRule = {
  deserialize(el, next, createBlock) {
    if (el.tagName?.toLowerCase() !== 'pre') return undefined
    const code = el.querySelector('code')
    return createBlock({
      _type: 'code',
      text: (code ?? el).textContent ?? '',
      language: code?.className?.replace('language-', '') ?? undefined,
    }).block
  },
}

const blocks = htmlToPortableText(html, {
  rules: [codeBlockRule],
})
```

### Example: callout blocks

Convert `
` elements into a custom block type:

```ts
const calloutRule = {
  deserialize(el, next, createBlock) {
    if (
      el.tagName?.toLowerCase() !== 'div' ||
      !el.classList?.contains('callout')
    ) {
      return undefined
    }
    const tone = el.classList.contains('warning') ? 'warning' : 'info'
    const children = next(el.childNodes)
    return createBlock({
      _type: 'callout',
      tone,
      content: Array.isArray(children) ? children : children ? [children] : [],
    }).block
  },
}
```

Custom rules are checked before the built-in rules. Return `undefined` from your rule to fall through to the default handling.

## Paste source support

The converter automatically detects and preprocesses content pasted from common applications. No configuration needed.

| Source         | How it's detected                      | What's handled                                                      |
| -------------- | -------------------------------------- | ------------------------------------------------------------------- |
| Google Docs    | `id` containing `"docs-internal-guid"` | Inline styles converted to semantic marks, checklist images removed |
| Microsoft Word | `class="Mso..."` or `mso-` styles      | CSS classes remapped to semantic HTML, list numbering extracted     |
| Word Online    | Specific paragraph markers             | Paragraph styles converted to headings and blockquotes              |
| Notion         | Inline style patterns                  | `font-weight:700` converted to strong, `font-style:italic` to em    |

:::tip
For Google Docs content, use `whitespaceMode: 'normalize'` to collapse extra whitespace that Google Docs adds:

```ts
const blocks = htmlToPortableText(html, {
  whitespaceMode: 'normalize',
})
```

:::

CSS-based formatting (like `style="font-weight: bold"`) is **not** converted in general HTML. Only the paste source preprocessors handle inline styles, and only for their specific source formats.

## Edge cases

- **`deserialize` is synchronous.** You can't do async work (like image uploads) inside rules. Use the two-phase pattern described above.
- **CSS formatting is ignored.** Only semantic HTML tags (``, ``, etc.) are converted. A `` in plain HTML produces no marks.
- **Schema marks are filtered silently.** No warnings when decorators or annotations are dropped because they're not in the schema. Check your schema if formatting disappears.
- **`createFlattenTableRule` is beta.** The API may change. For production table handling, consider a custom rule.
- **Page builder HTML is difficult.** Content from WordPress page builders (Elementor, Divi) uses non-semantic markup that doesn't map cleanly to Portable Text. Manual cleanup or custom rules may be needed.

## Other conversion paths

| Source format   | Tool                                                                                                                           |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| Markdown → PT   | [`@portabletext/markdown`](/conversion/markdown-to-portable-text/)                                                             |
| Gutenberg → PT  | [`@emdash-cms/gutenberg-to-portable-text`](https://github.com/emdash-cms/emdash) (30+ block types)                             |
| Contentful → PT | [`@portabletext/contentful-rich-text-to-portable-text`](https://github.com/portabletext/contentful-rich-text-to-portable-text) |
| C# HTML → PT    | [`portable-text-dotnet`](https://github.com/portabletext/dotnet-portable-text)                                                 |

## Further reading

- [`@portabletext/html` source](https://github.com/portabletext/editor/tree/main/packages/html)
- [`@portabletext/block-tools` source](https://github.com/portabletext/editor/tree/main/packages/block-tools)
- [`@portabletext/schema` (defineSchema, compileSchema)](https://github.com/portabletext/editor/tree/main/packages/schema)

# Markdown to Portable Text

> Convert Markdown strings into Portable Text blocks using @portabletext/markdown.

import {PackageManagers} from 'starlight-package-managers'

:::note[Prerequisites]
This guide covers `@portabletext/markdown` **v1.x** ([changelog](https://github.com/portabletext/editor/releases)). No framework dependencies. Works in Node.js, Deno, edge runtimes, and browsers.
:::

Convert Markdown strings into Portable Text blocks. Use this for importing content from Markdown-based systems (static site generators, GitHub READMEs, AI-generated content), processing user input, or migrating from Markdown-first CMSes.

Looking to render Portable Text as Markdown? See the [Markdown rendering guide](/rendering/markdown/).

## Install



## Basic usage

`markdownToPortableText` takes a Markdown string and returns an array of Portable Text blocks.

```ts
import {markdownToPortableText} from '@portabletext/markdown'

const blocks = markdownToPortableText('# Hello **world**')
```

Standard Markdown elements (headings, paragraphs, bold, italic, links, lists, blockquotes, inline code) are handled automatically using the default schema.

## Schema configuration

The conversion is schema-driven. The library only outputs types that exist in the schema, so the output always matches your content model.

The default schema includes:

| Type            | Values                                                         |
| --------------- | -------------------------------------------------------------- |
| `styles`        | `normal`, `h1`-`h6`, `blockquote`                              |
| `lists`         | `bullet`, `number`                                             |
| `decorators`    | `strong`, `em`, `code`, `strike-through`                       |
| `annotations`   | `link` (fields: `href`, `title`)                               |
| `blockObjects`  | `code`, `image`, `horizontal-rule`, `html`, `table`, `callout` |
| `inlineObjects` | `image`                                                        |

To use a custom schema, import `compileSchema` and `defineSchema` from `@portabletext/schema`:

```ts
import {compileSchema, defineSchema} from '@portabletext/schema'

markdownToPortableText(markdown, {
  schema: compileSchema(
    defineSchema({
      styles: [{name: 'normal'}, {name: 'heading 1'}],
    }),
  ),
})
```

If you are using a Sanity schema, use `@portabletext/sanity-bridge` to convert it first:

```ts
import {sanitySchemaToPortableTextSchema} from '@portabletext/sanity-bridge'

const schema = sanitySchemaToPortableTextSchema(sanityBlockArraySchema)
markdownToPortableText(markdown, {schema})
```

## Matchers

Matchers control how Markdown elements map to schema types. The library includes defaults for all standard elements. You can override individual matchers when your schema uses different type names.

| Group      | Matcher          | Markdown              | Maps to             |
| ---------- | ---------------- | --------------------- | ------------------- |
| `block`    | `normal`         | Paragraphs            | `'normal'`          |
|            | `h1`-`h6`        | `#`-`######` headings | `'h1'`-`'h6'`       |
|            | `blockquote`     | `>` blockquotes       | `'blockquote'`      |
| `listItem` | `bullet`         | `- ` or `* ` lists    | `'bullet'`          |
|            | `number`         | `1. ` ordered lists   | `'number'`          |
| `marks`    | `strong`         | `**bold**`            | `'strong'`          |
|            | `em`             | `*italic*`            | `'em'`              |
|            | `code`           | `` `inline code` ``   | `'code'`            |
|            | `strikeThrough`  | `~~strikethrough~~`   | `'strike-through'`  |
|            | `link`           | `[text](url "title")` | `'link'`            |
| `types`    | `code`           | Fenced code blocks    | `'code'`            |
|            | `horizontalRule` | `---`                 | `'horizontal-rule'` |
|            | `image`          | `![alt](src)`         | `'image'`           |
|            | `html`           | HTML blocks           | `'html'`            |
|            | `callout`        | `> [!NOTE]`, etc.     | `'callout'`         |

Override a matcher when your schema uses a different name for a type. For example, if your schema uses `'heading 1'` instead of `'h1'`:

```ts
markdownToPortableText(markdown, {
  schema: compileSchema(
    defineSchema({
      /* your schema */
    }),
  ),
  block: {
    h1: ({context}) => {
      const style = context.schema.styles.find((s) => s.name === 'heading 1')
      return style?.name
    },
  },
})
```

Returning `undefined` from a matcher skips the element gracefully. This is useful when a type may or may not exist in the schema depending on the content model.

## Supported features

| Feature          | Markdown to PT |
| ---------------- | :------------: |
| Headings (h1-h6) |       ✅       |
| Paragraphs       |       ✅       |
| Bold             |       ✅       |
| Italic           |       ✅       |
| Inline code      |       ✅       |
| Strikethrough    |       ✅       |
| Links            |       ✅       |
| Blockquotes      |       ✅       |
| Ordered lists    |       ✅       |
| Unordered lists  |       ✅       |
| Nested lists     |       ✅       |
| Code blocks      |       ✅       |
| Horizontal rules |       ✅       |
| Images           |       ✅       |
| Tables           |      ✅\*      |
| HTML blocks      |       ✅       |
| Callouts         |      ✅\*      |

\* Requires custom schema configuration (see above).

:::note
This package uses markdown-it as its Markdown parser. Remark and unified plugins are not compatible.
:::

## Other conversion paths

| Source format   | Tool                                                                                                                           |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| HTML → PT       | [`@portabletext/html`](/conversion/html-to-portable-text/)                                                                     |
| Gutenberg → PT  | [`@emdash-cms/gutenberg-to-portable-text`](https://github.com/emdash-cms/emdash) (30+ block types)                             |
| Contentful → PT | [`@portabletext/contentful-rich-text-to-portable-text`](https://github.com/portabletext/contentful-rich-text-to-portable-text) |

## Further reading

- [Markdown rendering guide](/rendering/markdown/) for converting PT blocks to Markdown strings
- [`@portabletext/markdown` on GitHub](https://github.com/portabletext/editor/tree/main/packages/markdown) for full API documentation and changelog

# All packages

> Every Portable Text package — serializers, converters, editor plugins, and utilities.

import {Badge} from '@astrojs/starlight/components'

The Portable Text ecosystem: official packages from the [`portabletext`](https://github.com/portabletext/) organization and community-maintained libraries. Packages marked with  are maintained outside the official organization.

## Render Portable Text

Serializers convert Portable Text JSON into your target output.

### JavaScript

| Package                                                                                                                         | Target       | Install                            |
| ------------------------------------------------------------------------------------------------------------------------------- | ------------ | ---------------------------------- |
| [`@portabletext/react`](https://github.com/portabletext/react-portabletext/)                                                    | React        | `npm i @portabletext/react`        |
| [`@portabletext/to-html`](https://github.com/portabletext/to-html/)                                                             | HTML string  | `npm i @portabletext/to-html`      |
| [`@portabletext/vue`](https://github.com/portabletext/vue-portabletext/)                                                        | Vue          | `npm i @portabletext/vue`          |
| [`@portabletext/svelte`](https://github.com/portabletext/svelte-portabletext/)                                                  | Svelte 5+    | `npm i @portabletext/svelte`       |
| [`@portabletext/solid`](https://github.com/portabletext/solid-portabletext/)                                                    | SolidJS      | `npm i @portabletext/solid`        |
| [`@portabletext/react-native`](https://github.com/portabletext/react-native-portabletext/)                                      | React Native | `npm i @portabletext/react-native` |
| [`@portabletext/react-pdf`](https://github.com/portabletext/react-pdf-portabletext)                                             | React PDF    | `npm i @portabletext/react-pdf`    |
| [`astro-portabletext`](https://github.com/theisel/astro-portabletext)                  | Astro        | `npm i astro-portabletext`         |
| [`portabletext-qwik`](https://github.com/tegonal/portabletext-qwik)                    | Qwik         | `npm i portabletext-qwik`          |
| [`@limitless-angular/sanity`](https://github.com/limitless-angular/limitless-angular)  | Angular      | `npm i @limitless-angular/sanity`  |

### Other languages

| Package                                                                                                                           | Language       |
| --------------------------------------------------------------------------------------------------------------------------------- | -------------- |
| [`dotnet-portable-text`](https://github.com/portabletext/dotnet-portable-text)                                                    | C# / .NET      |
| [`portable-text-dotnet`](https://github.com/nhi/portable-text-dotnet)                    | C# / .NET      |
| [`sanity-linq`](https://github.com/oslofjord/sanity-linq)                                | C# / .NET      |
| [`portabletext-html`](https://github.com/otovo/python-portabletext-html)                 | Python         |
| [`sanity-php`](https://github.com/sanity-io/sanity-php)                                                                           | PHP            |
| [`flutter_sanity_portable_text`](https://pub.dev/packages/flutter_sanity_portable_text)  | Dart / Flutter |
| [`flutter_portabletext`](https://github.com/JobiJoba/flutter_portabletext)               | Dart / Flutter |
| [`ruby_portable_text`](https://github.com/beaucouplus/ruby_portable_text)                | Ruby           |
| [`portabletext`](https://github.com/derickschaefer/portabletext)                         | Go             |

### Platform integrations

| Integration                                                                          | Platform         |
| ------------------------------------------------------------------------------------ | ---------------- |
| [`transform.PortableText`](https://gohugo.io/functions/transform/portabletext/)      | Hugo (built-in)  |
| [`portable-text-to-liquid`](https://github.com/portabletext/portable-text-to-liquid) | Shopify / Liquid |

## Build an editor

| Package                                                                                                            | Purpose                                                        | Install                                  |
| ------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------- | ---------------------------------------- |
| [`@portabletext/editor`](https://github.com/portabletext/editor/tree/main/packages/editor)                         | Headless, schema-driven block content editor for React         | `npm i @portabletext/editor`             |
| [`@portabletext/keyboard-shortcuts`](https://github.com/portabletext/editor/tree/main/packages/keyboard-shortcuts) | Platform-aware keyboard shortcuts                              | `npm i @portabletext/keyboard-shortcuts` |
| [`@portabletext/sanity-bridge`](https://github.com/portabletext/editor/tree/main/packages/sanity-bridge)           | Convert between Sanity schemas and Portable Text schemas       | `npm i @portabletext/sanity-bridge`      |
| [`@portabletext/schema`](https://github.com/portabletext/editor/tree/main/packages/schema)                         | Define and compile Portable Text schemas with full type safety | `npm i @portabletext/schema`             |
| [`@portabletext/toolbar`](https://github.com/portabletext/editor/tree/main/packages/toolbar)                       | Headless toolbar hooks for the editor                          | `npm i @portabletext/toolbar`            |

### Editor plugins

| Plugin                                                                                                                                       | What it does                                         | Install                                               |
| -------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | ----------------------------------------------------- |
| [`@portabletext/plugin-character-pair-decorator`](https://github.com/portabletext/editor/tree/main/packages/plugin-character-pair-decorator) | Match character pairs and decorate text between them | `npm i @portabletext/plugin-character-pair-decorator` |
| [`@portabletext/plugin-dnd`](https://github.com/portabletext/editor/tree/main/packages/plugin-dnd)                                           | Track drop position for custom drop indicators       | `npm i @portabletext/plugin-dnd`                      |
| [`@portabletext/plugin-emoji-picker`](https://github.com/portabletext/editor/tree/main/packages/plugin-emoji-picker)                         | Emoji picker                                         | `npm i @portabletext/plugin-emoji-picker`             |
| [`@portabletext/plugin-input-rule`](https://github.com/portabletext/editor/tree/main/packages/plugin-input-rule)                             | Configure input rules                                | `npm i @portabletext/plugin-input-rule`               |
| [`@portabletext/plugin-list-index`](https://github.com/portabletext/editor/tree/main/packages/plugin-list-index)                             | Compute list indices for custom list rendering       | `npm i @portabletext/plugin-list-index`               |
| [`@portabletext/plugin-markdown-shortcuts`](https://github.com/portabletext/editor/tree/main/packages/plugin-markdown-shortcuts)             | Markdown-style shortcuts in the editor               | `npm i @portabletext/plugin-markdown-shortcuts`       |
| [`@portabletext/plugin-one-line`](https://github.com/portabletext/editor/tree/main/packages/plugin-one-line)                                 | Restrict editor to a single line                     | `npm i @portabletext/plugin-one-line`                 |
| [`@portabletext/plugin-paste-link`](https://github.com/portabletext/editor/tree/main/packages/plugin-paste-link)                             | Paste URLs as links                                  | `npm i @portabletext/plugin-paste-link`               |
| [`@portabletext/plugin-sdk-value`](https://github.com/portabletext/editor/tree/main/packages/plugin-sdk-value)                               | Syncs editor value with the Sanity SDK               | `npm i @portabletext/plugin-sdk-value`                |
| [`@portabletext/plugin-table`](https://github.com/portabletext/editor/tree/main/packages/plugin-table)                                       | Table editing with spreadsheet-grade selection       | `npm i @portabletext/plugin-table`                    |
| [`@portabletext/plugin-typeahead-picker`](https://github.com/portabletext/editor/tree/main/packages/plugin-typeahead-picker)                 | Typeahead/autocomplete picker infrastructure         | `npm i @portabletext/plugin-typeahead-picker`         |
| [`@portabletext/plugin-typography`](https://github.com/portabletext/editor/tree/main/packages/plugin-typography)                             | Smart quotes, em dashes, ellipses                    | `npm i @portabletext/plugin-typography`               |

## Convert content

| Package                                                                                                                                                                  | Direction                             | Install                                                     |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------- | ----------------------------------------------------------- |
| [`@portabletext/html`](https://github.com/portabletext/editor/tree/main/packages/html)                                                                                   | HTML → Portable Text                  | `npm i @portabletext/html`                                  |
| [`@portabletext/block-tools`](https://github.com/portabletext/editor/tree/main/packages/block-tools)                                                                     | HTML → Portable Text (Sanity wrapper) | `npm i @portabletext/block-tools`                           |
| [`@portabletext/markdown`](https://github.com/portabletext/editor/tree/main/packages/markdown)                                                                           | Portable Text ↔ Markdown              | `npm i @portabletext/markdown`                              |
| [`@portabletext/contentful-rich-text-to-portable-text`](https://github.com/portabletext/contentful-rich-text-to-portable-text)                                           | Contentful → Portable Text            | `npm i @portabletext/contentful-rich-text-to-portable-text` |
| [`@emdash-cms/gutenberg-to-portable-text`](https://github.com/emdash-cms/emdash/tree/main/packages/gutenberg-to-portable-text)  | WordPress / Gutenberg → Portable Text | `npm i @emdash-cms/gutenberg-to-portable-text`              |
| [`editorjs-to-portabletext`](https://github.com/LiamMartens/editorjs-to-portabletext)                                           | Editor.js → Portable Text             | `npm i editorjs-to-portabletext`                            |
| [`@aceccarello/portable-text-to-lexical`](https://github.com/ACeccarello/portable-text-to-lexical)                              | Portable Text → Payload Lexical JSON  | `npm i @aceccarello/portable-text-to-lexical`               |

## Work with Portable Text data

| Package                                                                                                                                               | Purpose                                                         | Install                           |
| ----------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | --------------------------------- |
| [`@portabletext/toolkit`](https://github.com/portabletext/toolkit)                                                                                    | `toPlainText()`, `buildMarksTree()`, `nestLists()`, type guards | `npm i @portabletext/toolkit`     |
| [`@portabletext/types`](https://github.com/portabletext/types)                                                                                        | TypeScript type definitions for Portable Text data              | `npm i @portabletext/types`       |
| [`@portabletext/patches`](https://github.com/portabletext/editor/tree/main/packages/patches)                                                          | Apply patches to Portable Text values                           | `npm i @portabletext/patches`     |
| [`@portabletext-typed/types`](https://github.com/saiichihashimoto/sanity-typed/tree/main/packages/pt-types)  | Typed generics for `@portabletext/types`                        | `npm i @portabletext-typed/types` |

## Testing

| Package                                                                                | Purpose                                        | Install                    |
| -------------------------------------------------------------------------------------- | ---------------------------------------------- | -------------------------- |
| [`@portabletext/test`](https://github.com/portabletext/editor/tree/main/packages/test) | Testing utilities for the Portable Text Editor | `npm i @portabletext/test` |
| [`racejar`](https://github.com/portabletext/editor/tree/main/packages/racejar)         | Framework-agnostic Gherkin test driver         | `npm i racejar`            |

## Legacy packages

These packages are deprecated. Use the current equivalents listed above.

| Deprecated package                     | Replaced by                                                       |
| -------------------------------------- | ----------------------------------------------------------------- |
| `@sanity/block-content-to-react`       | [`@portabletext/react`](/rendering/react/)                        |
| `@sanity/block-content-to-html`        | [`@portabletext/to-html`](/rendering/html/)                       |
| `@sanity/block-content-to-hyperscript` | [`@portabletext/to-html`](/rendering/html/)                       |
| `@sanity/block-content-to-markdown`    | [`@portabletext/markdown`](/rendering/markdown/)                  |
| `@sanity/block-tools`                  | [`@portabletext/block-tools`](/conversion/html-to-portable-text/) |
| `@sanity/portable-text-editor`         | [`@portabletext/editor`](/editor/getting-started/)                |

For more packages, see the [Portable Text organization on GitHub](https://github.com/portabletext/).

# Portable Text Editor

> A headless, schema-driven block content editor for React. Officially supported, fully customizable, and built around the Portable Text specification.

The Portable Text Editor (`@portabletext/editor`) is the officially supported editor for working with [Portable Text](/specification/) content. It's a headless block content editor for React: you bring the UI, the editor handles the editing.

You configure the editor by declaring a [schema](/editor/concepts/portabletext/) of styles, decorators, annotations, lists, block objects, and inline objects. Rendering is yours to control through node registrations and render props on `PortableTextEditable`, and [containers](/editor/concepts/containers/) let structures like callouts, code blocks, and tables carry editable rich text. Interactions are extensible through the [Behavior API](/editor/concepts/behavior/) and a growing set of [plugins](/editor/reference/plugins/). The companion [`@portabletext/toolbar`](/editor/reference/toolbar/) package gives you headless hooks for building toolbar UI.

### [Getting started](/editor/getting-started/)

Install the editor, define a schema, and build your first toolbar.

### [Concepts](/editor/concepts/)

How the schema, decorators, annotations, containers, and behaviors fit together.

### [Guides](/editor/guides/)

Practical walkthroughs: custom blocks and inline objects, custom rendering, building toolbars, writing behaviors, and testing.

### [Reference](/editor/reference/)

API documentation for the editor, behaviors, plugins, selectors, toolbar, and keyboard shortcuts.

# Concepts

> Core concepts behind Portable Text and the Portable Text Editor.

Learn about the building blocks of Portable Text and how the editor works.

### [Portable Text Editor](/editor/concepts/portabletext/)

The parts that make up the Portable Text Editor: schema, styles, decorators, annotations, lists, block objects, inline objects, and how they connect. Includes a glossary of common terms.

### [Containers](/editor/concepts/containers/)

Nest editable rich text inside custom structures like callouts, code blocks, and tables, while the value stays plain Portable Text.

### [Behaviors](/editor/concepts/behavior/)

How behaviors work in the editor. Events, guards, and actions: the pattern that lets you customize how users interact with the editor.

# Behaviors

> How behaviors intercept and transform editor events to customize the Portable Text Editor's editing logic.

import {CardGrid, LinkCard} from '@astrojs/starlight/components'

Behaviors allow you to customize how users interact with the editor by hooking into events during the editing experience.

All behaviors follow this process:

1. Listen for an **event**.
2. Use a **guard** to decide if they should run or not.
3. Trigger a set of **actions** to perform on the editor.

This pattern is influenced by [Statecharts](https://statecharts.dev/).

Behaviors are defined with the `defineBehavior` helper. Here's an example event from the [behavior guide](/editor/guides/create-behavior/):

```tsx
defineBehavior({
  on: 'insert.text',
  guard: ({snapshot, event}) => event.text === 'a',
  actions: [
    ({snapshot, event}) => [
      {type: 'execute', event: {type: 'insert.text', text: 'A'}},
    ],
  ],
})
```

Revisiting the three step process above:

- `on` listens for the event.
- `guard` handles the conditional.
- `actions` sends, or invokes, the desired actions.

## Events

Whenever you enter text into the editor, activate a toolbar button, or anything else happens in the editor it sends an event.

There are three categories of Behavior Events:

- Native Events: Events that come from the browser or device directly.
- Synthetic Events: Editor-specific events that directly modify the editor state.
- Custom Events: Events that you create yourself.



The Behavior API uses events to trigger actions by listening for a specific event.

:::note
All events except native events can be executed or raised from within behaviors, but only synthetic events are guaranteed to resolve into a state change.
:::

## Guards

A guard is a condition that helps the behavior determine if it should perform the actions.

The `guard` key expects a response or `false`. The example above shows a simple _truthy_ guard. Here it is again:

```js
guard: ({snapshot, event}) => event.text === 'a'
```

Guards can also return parameters that you can access when firing an action.

```js
guard: ({snapshot, event}) => {
    if (event.text === 'a') {
        return {
            secret: 'secret text'
        }
    }
    return false
},
actions: [
    ({snapshot, event}, {secret}) => [
        /* ... */
    ]
]
```

Passing parameters allows you to reuse conditional behavior, such as selecting part of a string, without rewriting the logic.

Guards are optional. This means it's possible to create an unconditional behavior that always runs when an event occurs. The "soft return" behavior build into the PTE is one example:

```js
const softReturn = defineBehavior({
  on: 'insert.soft break',
  actions: [() => [execute({type: 'insert.text', text: '\n'})]],
})
```

This behavior listens for soft break events and uses the `insert.text` action to insert a `\n` instead to prevent splitting text blocks with `Shift+Enter`. These unconditional behaviors are rare and you'll mostly encounter conditional behaviors.

## Actions

Actions make things happen in the editor. This is where you change the standard behavior by modifying actions before they occur or by circumventing them completely. You've seen actions in some of the guard examples above.

The `actions` key expects an array of behavior action sets. As with guards, you have access to the `event` and `snapshot`.

So far we've only seen examples that invoke a single action, but you can send multiple actions or sets of actions from a single event.

### Raise events within actions

To send an event back into the editor, use the `raise` action type or the `raise` helper. This is useful for chaining behaviors and default events.

```tsx
// Approach A: With the type set to 'raise'
// Approach B: With the raise helper
import {defineBehavior, raise} from '@portabletext/editor/behaviors'

const raisedUppercaseA = defineBehavior({
  on: 'insert.text',
  guard: ({snapshot, event}) => event.text === 'a',
  actions: [
    ({snapshot, event}) => [
      {type: 'raise', event: {type: 'insert.text', text: 'A'}},
    ],
  ],
})

const raisedUppercaseA = defineBehavior({
  on: 'insert.text',
  guard: ({snapshot, event}) => event.text === 'a',
  actions: [({snapshot, event}) => [raise({type: 'insert.text', text: 'A'})]],
})
```

### Claiming the native event

When a Behavior's guard matches an event that carries a native event (a `keyboard.keydown`, for example), the Behavior claims it: the editor calls `preventDefault()` and the browser's default action is suppressed. The action sets can revise that claim. Every action set that returns actions casts a vote, and the last vote wins:

| The action set             | Native default              |
| -------------------------- | --------------------------- |
| contains `raise`/`execute` | prevented                   |
| contains only `forward`    | passes down the chain       |
| contains only `effect`s    | prevented                   |
| returns nothing, or throws | keeps the previous decision |

Within one set, `raise` and `execute` outrank `forward`: a set that both mutates and forwards still prevents the default.

`forward` does not mean "let the browser act". It means "no opinion at this level": the event moves on to the next Behavior in the chain, which makes its own decision, and the browser's default only survives when no Behavior along the chain claims the event.

Multiple action sets are also an undo boundary: each set after the first starts a new undo step. [`@portabletext/plugin-input-rule`](https://github.com/portabletext/editor/tree/main/packages/plugin-input-rule) uses this to let the typed text land as its own undo step before a second set transforms it, so undo peels the transformation off first.

## Selectors

Selectors are pure functions that derive state from the editor snapshot (`snapshot` in the examples). A collection of selectors is included with the core library.

```tsx
// import all selectors
import * as selectors from '@portabletext/editor/selectors'
// or individual ones
import {getFocusSpan, getFocusTextBlock} from '@portabletext/editor/selectors'
```

The core selectors are useful helper functions for checking conditions of the editor, finding selected text, and more. You can manually do anything a selector can do by parsing the editor snapshot.

## Behavior examples

Browse the existing behaviors, or check out the Behavior Recipes documentation for examples of real-world behaviors.


  
  


# Containers

> Nest editable rich text inside custom structures like callouts, code blocks, and tables, while the value stays plain Portable Text.

A container is a block object that holds editable rich text: one of its fields is an array whose members include text blocks (or further containers). Containers are how callouts carry editable paragraphs, code blocks carry editable lines, and tables carry editable cells, without leaving Portable Text.

## Containers are plain Portable Text

There is no editor-specific data format. A container in the value is an ordinary object block whose field happens to hold more blocks:

```json
{
  "_type": "callout",
  "_key": "a1b2c3",
  "tone": "note",
  "content": [
    {
      "_type": "block",
      "_key": "d4e5f6",
      "children": [
        {
          "_type": "span",
          "_key": "g7h8i9",
          "text": "Editable text inside the callout.",
          "marks": []
        }
      ],
      "markDefs": [],
      "style": "normal"
    }
  ]
}
```

Serializers and queries see nested Portable Text, nothing more. What makes it a _container_ is that the editor knows to render the `content` array as an editable region instead of treating `callout` as an opaque block object.

## Declare the schema

A container starts in the schema: a block object with an array field whose `of` includes a `{type: 'block'}` member.

```ts
import {defineSchema} from '@portabletext/editor'

const schemaDefinition = defineSchema({
  decorators: [{name: 'strong'}, {name: 'em'}],
  blockObjects: [
    {
      name: 'callout',
      fields: [
        {name: 'tone', type: 'string'},
        {name: 'content', type: 'array', of: [{type: 'block'}]},
      ],
    },
  ],
})
```

The nested `{type: 'block'}` member declares the _sub-schema_ for text inside the container. Each of `styles`, `decorators`, `annotations`, `lists`, and `inlineObjects` resolves independently:

- **Declared** on the nested block, it overrides for that property.
- **Declared empty** (`decorators: []`), it forbids that property inside the container.
- **Absent**, it inherits from the nearest enclosing container that declares one, falling back to the root schema.

This is how a code block restricts its lines to a `code` style with no decorators while the rest of the document keeps its full schema. The complete resolution rules live in the [`@portabletext/schema` README](https://github.com/portabletext/editor/tree/main/packages/schema#containers-and-sub-schemas).

## Register the container

The schema declares what a container _allows_; a registration tells the editor to _render_ it as one. Create the registration with `defineContainer` and mount it with `NodePlugin`:

```tsx
import {
  defineContainer,
  EditorProvider,
  PortableTextEditable,
} from '@portabletext/editor'
import {NodePlugin} from '@portabletext/editor/plugins'

// Module scope: a new array identity re-registers the nodes on every render.
const nodes = [
  defineContainer({
    type: 'callout',
    arrayField: 'content',
    render: ({attributes, children, selected}) => (
      
    ),
  }),
]

function App() {
  return (
    
      
      
    
  )
}
```

The render contract:

- Spread `attributes` onto your outer element so the engine can track the node.
- Render `children` where the editable content goes; the engine fills it with the container's blocks.
- Mark any chrome that is not editable content (icons, buttons, drag handles) with `contentEditable={false}`.
- `renderDefault` renders the engine's minimal wrapper; call it to fall back or wrap the default. It does not chain to a globally-registered render: the engine default is the canonical fallback at any position.

Omitting `render` falls through to the engine default, so a registration can exist purely to mark the field as editable.

Registering a container also normalizes the value: existing blocks of the registered type are seeded down to a cursor-ready structure, so a bare `table` block gains a `rows` array holding an empty row, cell, and text block.

## Nest containers

Containers nest through the `of` array, which scopes registrations to positions inside the parent. A table is three containers deep:

```tsx
defineContainer({
  type: 'table',
  arrayField: 'rows',
  render: ({attributes, children}) => 

, of: [ defineContainer({ type: 'row', arrayField: 'cells', render: ({attributes, children}) => {children}, of: [ defineContainer({ type: 'cell', arrayField: 'content', render: ({attributes, children}) => ( {children} ), }), ], }), ], }) ``` Nesting isn't limited to containers: `of` accepts any block-level registration, `defineContainer`, `defineTextBlock`, and `defineBlockObject`, so anything can render differently inside a container than in the rest of the document. A code block can render each line without paragraph spacing, and a callout can render images compactly. Inline kinds scope the same way one level down, through a text block's own `of`, which takes `defineSpan` and `defineInlineObject` registrations (a `code-span` inside a code block, for example). Scope is one level deep: an `of` override applies to the container's immediate children only, and anything nested deeper falls through to the global registrations. An image inside a table cell sees the cell's `of`, not the table's. ## Registrations opt into the new render pipeline The editor has two rendering paths: the render props on `` are the older one, and registrations replace them rather than compose with them. Registering nodes with `NodePlugin` opts those positions, and everything rendered inside them, into the editor's new render pipeline, and that changes who owns what. Your `render` owns the outer wrapper entirely: the engine emits only `data-pt-*` attributes, and the node render props on ``, `renderBlock`, `renderStyle`, `renderListItem`, and `renderChild`, do not compose for registered nodes. Span-level rendering keeps working: `renderDecorator`, `renderAnnotation`, `renderPlaceholder`, and range decorations fire on the spans inside `children` regardless of who renders the block. The pipeline boundary is the subtree. Inside a registered container, unregistered node types render through the engine defaults, never through the node render props, so registering a container usually means bringing a `defineTextBlock` (and registrations for anything else that renders inside it) along with it. Each kind of node has its own registration factory, and they mount together through one `NodePlugin`: ```tsx import { defineBlockObject, defineContainer, defineTextBlock, } from '@portabletext/editor' const nodes = [ // A container: a block object with an editable child array. defineContainer({ type: 'callout', arrayField: 'content', render: ({attributes, children}) => ( ), }), // Text blocks. `block` is the text block type at every nesting level, // so this one registration covers paragraphs at the top level and // inside the callout alike. defineTextBlock({ type: 'block', render: ({attributes, children, node}) => (

{children}

), }), // A non-editable void block. Render `children` as well: the engine // mounts its internals through them. defineBlockObject({ type: 'image', render: ({attributes, children, node}) => (

{children}

), }), ] ``` Owning the wrapper means owning things the engine used to do for you. The two that surprise people: **List rendering.** The engine's default list-item wrapping and ordered-list numbering do not apply to custom text-block renders. Your render handles `node.listItem` and `node.level`, and [`@portabletext/plugin-list-index`](https://github.com/portabletext/editor/tree/main/packages/plugin-list-index) computes the 1-based list index at any path, correct across nesting, remote edits, and non-list blocks interrupting a list. **Drop indicators.** The engine renders no drop-indicator chrome for registered nodes: where a dragged block would land is pointer-driven UI, deliberately yours. [`@portabletext/plugin-dnd`](https://github.com/portabletext/editor/tree/main/packages/plugin-dnd) tracks the drop position from the editor's public `drag.*` events. Both plugins follow the same pattern: a provider inside `EditorProvider`, and a hook read from your render, called from a component the render returns, not inline in the `render` callback, since hooks can't run there: ```tsx import type {TextBlockRenderProps} from '@portabletext/editor' import {DndProvider, useDropPosition} from '@portabletext/plugin-dnd' import {ListIndexProvider, useListIndex} from '@portabletext/plugin-list-index' const nodes = [ defineTextBlock({ type: 'block', render: (props) => , }), ] function TextBlock(props: TextBlockRenderProps) { // The 1-based position within the list, or `undefined` for a block // that is not a list item. const listIndex = useListIndex(props.path) // `'start' | 'end'` while a block drag hovers this block. const dropPosition = useDropPosition(props.path) return (

{listIndex !== undefined ? ( {listIndex}. ) : null} {props.children} {dropPosition ? : null}

) } ``` ```tsx ``` Each plugin's README carries the full recipe, including a reference `DropIndicator` implementation. :::note[Migrating from the render props?] If your editor renders through the legacy props on `` (`renderBlock`, `renderChild`, `renderStyle`, `renderListItem`), each has a registration equivalent, and the engine dispatches per `_type`, so you can migrate one kind at a time. The [migration guide](/editor/guides/migrate-render-props/) walks through it. ::: ## Editing follows the sub-schema Inside a container, the editor resolves the schema at the caret, not the top-level schema. A code block whose sub-schema declares no decorators won't accept bold, whether from the keyboard, the toolbar, or a paste. Schema-aware plugins get the same gating for free, because their callbacks receive the sub-schema at the caret as `context.schema`. Take a schema whose code block forbids decorators, and a Markdown shortcut configured by schema lookup: ```tsx import {MarkdownShortcutsPlugin} from '@portabletext/plugin-markdown-shortcuts' const schemaDefinition = defineSchema({ decorators: [{name: 'strong'}, {name: 'em'}], blockObjects: [ { name: 'code-block', fields: [ { name: 'lines', type: 'array', // The code line allows a `code` style and no decorators. of: [{type: 'block', styles: [{name: 'code'}], decorators: []}], }, ], }, ], }) ``` ```tsx context.schema.decorators.find((decorator) => decorator.name === 'strong') ?.name } /> ``` The callback runs against the schema at the caret. In a regular paragraph the lookup finds `strong`, so typing `**bold**` applies the decorator. Inside a code-block line the sub-schema declares `decorators: []`, the lookup returns `undefined`, and the shortcut skips itself. Nothing was configured per container: **the schema is the feature flag**, and the lookup is what reads it. Your own code can resolve the schema at any position with `getPathSubSchema` from `@portabletext/editor/traversal`. ## Registration validation A container registration that doesn't match the schema is skipped with a `console.warn` naming the actual mismatch: an unknown type, a missing field, a field that isn't an array, or an array of primitives only. The editor keeps working; the type renders as an ordinary block object until the registration and schema agree. ## A complete example Everything above composes in one `nodes` array. This editor renders text blocks and images everywhere, and a callout that renders the same `image` type compactly inside itself: ```tsx import { defineBlockObject, defineContainer, defineSchema, defineTextBlock, EditorProvider, PortableTextEditable, } from '@portabletext/editor' import {NodePlugin} from '@portabletext/editor/plugins' const schemaDefinition = defineSchema({ decorators: [{name: 'strong'}, {name: 'em'}], styles: [{name: 'normal'}, {name: 'h2'}], blockObjects: [ {name: 'image', fields: [{name: 'src', type: 'string'}]}, { name: 'callout', fields: [ {name: 'tone', type: 'string'}, { name: 'content', type: 'array', // The callout holds text blocks and images. of: [{type: 'block'}, {type: 'image'}], }, ], }, ], }) const nodes = [ // Text blocks, at the root and inside the callout alike. defineTextBlock({ type: 'block', render: ({attributes, children, node}) => node.style === 'h2' ? (

{children}

) : (

{children}

), }), // Images at the root: full width. defineBlockObject({ type: 'image', render: ({attributes, children, node}) => (

{children}

), }), // The callout, with a positional override: the same `image` type // renders compactly inside it. defineContainer({ type: 'callout', arrayField: 'content', render: ({attributes, children}) => ( ), of: [ defineBlockObject({ type: 'image', render: ({attributes, children, node}) => ( {children} ), }), ], }), ] function App() { return ( ) } ``` An `image` block at the document root renders through the global registration, full width. The same `_type: 'image'` inside the callout's `content` hits the positional override first and renders compact. The text block registration needs no positional counterpart: `type: 'block'` already covers both scopes. Positional overrides only need to carry what they change: an `of` entry that omits `render` falls through to the global registration's render, so a positional registration never has to re-implement what the global one already does. ## Containers in practice [`@portabletext/plugin-table`](https://github.com/portabletext/editor/tree/main/packages/plugin-table) is built entirely on this API: three nested containers plus behaviors and UI. It's both a ready-made table editor and the reference for what containers can carry. The [Portable Text Playground](https://playground.portabletext.org/) ships container examples you can try, callouts, code blocks, fact boxes, and tables. # Schema and concepts > Learn more about the parts of Portable Text and the Editor, including common terms and concepts. import {CardGrid, LinkCard} from '@astrojs/starlight/components' The Portable Text Editor (PTE) is the officially supported editor for working with [Portable Text](https://github.com/portabletext/portabletext). Customize it to fit the needs of your authors and content team using a schema, ## Schema The PTE accepts a schema that describes the kinds of content it can implement. This is used throughout the editor to configure parts of the interface and aspects of the Portable Text output. {/* */} A schema consists of styles, decorators, annotations, block objects, inline objects, and lists. Here is an example schema from the [getting started guide](/editor/getting-started/): ```js { decorators: [{name: 'strong'}, {name: 'em'}, {name: 'underline'}], annotations: [{name: 'link', fields: [{name: 'href', type: 'string'}]}], styles: [ {name: 'normal'}, {name: 'h1'}, {name: 'h2'}, {name: 'h3'}, {name: 'blockquote'}, ], lists: [{name: 'bullet'}, {name: 'number'}], inlineObjects: [{name: 'stock-ticker'}], blockObjects: [{name: 'image'}], } ``` You'll likely see connections to the elements found in rich text editors, along with some extras. ### Styles Styles are a way to identify text blocks in Portable Text and signal to the editor how to classify the block. They don't add any other data to the text. Examples include: - Headings (H1, H2, H3, etc.) - Block quotes - Normal paragraphs Convention uses HTML naming for these styles, but it is not required and has no direct impact on the style of the content. ### Decorators Decorators are inline text with added meaning. Examples include: - Bold text - Emphasis or italicized text - Underlined text Decorators are a type of [Portable Text mark](https://github.com/portabletext/portabletext?tab=readme-ov-file#markdefs-array) that adds additional meaning to existing text. ### Annotations Like decorators, annotations are inline text with added meaning. Annotations are more complex than decorators, and often include additional functionality. Examples include: - Links - References Annotations are a type of [Portable Text mark](https://github.com/portabletext/portabletext?tab=readme-ov-file#markdefs-array) that adds additional meaning to existing text. ### Lists Lists are groups of text blocks. They take into account the position each block has in a group. Examples include: - Bullet lists - Numbered lists ### Block objects Block objects sit alongside text. For example, an image block may sit between a heading and a paragraph. They can hold any kind of data. Some examples include: - Images - Code blocks - Videos - Portable Text editors ### Inline objects Inline objects, much like block objects, can hold any kind of data. Instead of existing alongside text, inline objects exist inside text blocks. Examples include: - Footnote indicators - Non-text emoji substitutes Inline objects differ from annotations and decorators because they aren't wrapping existing text. Instead, they are self contained. ## Rendering content in and out of the editor The schema serves as a foundation for how the PTE renders the text. On it's own, passing just a schema to the editor only annotates or _describes_ text, but it won't change the way it renders. To affect the way text renders in the editor, pass custom renderers to the editor. To affect the way text renders once it's stored as Portable Text, use an existing serializer or write your own. ## The toolbar A schema describes the type of content an author can create in the editor, but without a toolbar there's no way to assign the schema to each piece of text. The toolbar allows you to define the graphical user interface for creating rich text in the PTE. The most common way to do this is by using the schema as a foundation. ## Behaviors Behaviors change how users interact with the editor. They handle everything from direct text input, to changing paste behavior, to allowing you to write custom shortcuts. The editor comes with many behaviors by default, but you can also create your own. ## Common terms The following terms come up when dealing with Portable Text and the editor. Some overlap with the schema above, while others are more general. - Block: Broken down into standard and custom blocks. Standard blocks are sections of text, like paragraphs and headings. Custom blocks are block objects like images, code blocks, embeds, etc. - Span: A standard way to express inline text within a block. - Children: An array of spans or other inline types contained within a block. - Marks: `markDefs` exist in the Portable Text format and connect spans with annotations and decorators. A span can have multiple marks associated with it. Such as text that is bold and italic. - List items: Blocks can be labeled as list items to resemble lists. - Selection: The range of text selected, or the cursor location in the editor at a given time. - Selection collapsed: A collapsed selection is one where nothing is selected and is instead a single point (cursor). - Anchor: Where the user began the selection. - Focus: Where the user ends the selection. - Offset: A distance, in characters, from the selection. - Path: A representation of the location of elements. Used in the behavior API to target or select specific blocks, spans, or text. - Node: A representation of an element. Contains details about it's type and content. # Getting started > Install the Portable Text Editor and build your first block content editing experience. import { CardGrid, LinkCard, Steps, TabItem, Tabs, } from '@astrojs/starlight/components' import {PackageManagers} from 'starlight-package-managers' This guide walks you through installing and configuring the Portable Text Editor. By the end, you'll have a working block content editor with custom styles, decorators, and a toolbar. :::tip[Just need to render Portable Text?] If you already have Portable Text content and want to display it, see [Render Portable Text](/rendering/) instead. ::: :::note[Prerequisites] This guide covers `@portabletext/editor` **v7.x**, `@portabletext/toolbar` **v8.x**, and `@portabletext/keyboard-shortcuts` **v2.x**. Requires React 19.2.7+. Check the [editor changelog](https://github.com/portabletext/editor/releases) for breaking changes. ::: 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. ## Parts of the editor Before starting, it helps to understand the components that make up the editor. - **Schema:** Describes the type of content the editor accepts. Think of this as the foundation for configuring the editor. - **`EditorProvider`:** Supplies the schema and initial state to the editor. - **`EventListenerPlugin`:** Listens to events emitted by the editor. Commonly used to update application state. - **Toolbars:** UI elements that interact with the editor. - **`PortableTextEditable`:** The core editor component. Handles text rendering and manages behavior. ## Add the library to your project Start by installing the editor: Next, import the components and types you'll need: ```tsx // App.tsx import { defineSchema, EditorProvider, PortableTextEditable, } from '@portabletext/editor' import type { PortableTextBlock, RenderDecoratorFunction, RenderStyleFunction, } from '@portabletext/editor' import {EventListenerPlugin} from '@portabletext/editor/plugins' ``` You won't need all of these right away, but you can add them now. ## Define your schema Before you can render the editor, you need a schema. The editor schema configures the types of content rendered by the editor. Start with a schema that includes some common rich text elements. :::note This guide includes a limited set of schema types to get you started. See the [rendering guide](/editor/guides/custom-rendering/) 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: [], }) ``` ## Render the editor With a schema defined, you have enough to render the editor. It won't do much yet, but you can confirm your progress. Add `react` and `useState`, then scaffold out a basic application component: ```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 ( <> { if (event.type === 'mutation') { setValue(event.value) } }} /> ) } 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. ## Create render functions for schema elements :::caution[Deprecated] The block-level render props used below (`renderStyle`, `renderBlock`, `renderListItem`) are deprecated and will be removed in future major versions in favor of node registrations. The [migration guide](/editor/guides/migrate-render-props/) shows the replacement for each prop. ::: 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}

} if (props.schemaType.value === 'h2') { return

{props.children}

} if (props.schemaType.value === 'h3') { return

{props.children}

} if (props.schemaType.value === 'blockquote') { return

{props.children}

} return <>{props.children} } ``` Render functions all follow the same format: - 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 `