` 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/toolbar`](https://github.com/portabletext/editor/tree/main/packages/toolbar)                       | Headless toolbar hooks for the editor                          | `npm i @portabletext/toolbar`            |
| [`@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/keyboard-shortcuts`](https://github.com/portabletext/editor/tree/main/packages/keyboard-shortcuts) | Platform-aware keyboard shortcuts                              | `npm i @portabletext/keyboard-shortcuts` |

### Editor plugins

| Plugin                                                                                                                                       | What it does                                         | Install                                               |
| -------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | ----------------------------------------------------- |
| [`@portabletext/plugin-typography`](https://github.com/portabletext/editor/tree/main/packages/plugin-typography)                             | Smart quotes, em dashes, ellipses                    | `npm i @portabletext/plugin-typography`               |
| [`@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-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-emoji-picker`](https://github.com/portabletext/editor/tree/main/packages/plugin-emoji-picker)                         | Emoji picker                                         | `npm i @portabletext/plugin-emoji-picker`             |
| [`@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-input-rule`](https://github.com/portabletext/editor/tree/main/packages/plugin-input-rule)                             | Configure input rules                                | `npm i @portabletext/plugin-input-rule`               |
| [`@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-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-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`                |

## 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 render props on `PortableTextEditable`. 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, 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.

### [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'})]],
})
```

## 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.


  
  


# 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` **v6.x**, `@portabletext/toolbar` **v7.x**, and `@portabletext/keyboard-shortcuts` **v2.x**. Requires React 18+. 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

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 `
` elements.
:::

Update the `PortableTextEditable` with each corresponding function to attach them to the editor.

You may notice that we skipped a few types from the schema. Declare these inline in the configuration:

```tsx
 
{props.children}
}
  renderListItem={(props) => <>{props.children}}
/>
```

Before you can see if anything changed, you need a way to interact with the editor.

## Create a toolbar

A toolbar is a collection of UI elements for interacting with the editor. The `@portabletext/toolbar` library exposes hooks and types that allow you to create a toolbar however you like. The `@portabletext/keyboard-shortcuts` library provides drop-in shortcut access to link toolbar buttons to key commands.

Building a custom toolbar differs with each project, but in this example:

1. Add the `@portabletext/toolbar` and `@portabletext/keyboard-shortcuts` libraries to your project.
2. Create a `Toolbar` component, along with any sub-components in the same file.
3. Configure `useToolbarSchema` to access the editor schema, then loop over the schema types to create buttons for each style and decorator.
4. Enhance the schema with any icons, labels, or descriptions you want to display in the toolbar.
5. Create buttons for each schema group (styles, decorators, annotations, etc.).
6. Add the `Toolbar` to your render function inside the `EditorProvider`.



This example shows a minimal toolbar:

```tsx
// App.tsx
// ...
import {bold} from '@portabletext/keyboard-shortcuts'
import {
  useDecoratorButton,
  useStyleSelector,
  useToolbarSchema,
  type ExtendDecoratorSchemaType,
  type ExtendStyleSchemaType,
  type ToolbarDecoratorSchemaType,
  type ToolbarStyleSchemaType,
} from '@portabletext/toolbar'

function Toolbar() {
  // useToolbarSchema provides access to the PTE schema
  // optionally, pass in updated schemas to override the default
  const toolbarSchema = useToolbarSchema({
    extendDecorator, // see declarations below
    extendStyle, // see declarations below
  })

  return (
    

      {toolbarSchema.decorators?.map((decorator) => (
        
      ))}
      {toolbarSchema.styles?.map((style) => (
        
      ))}
    
  )
}
// Extend the schema with icons, titles, and keyboard shortcuts

const extendStyle: ExtendStyleSchemaType = (style) => {
  // Apply updates to the schema, if needed
  if (style.name === 'h1') {
    return {
      ...style,
      title: 'Title',
    }
  }
  // ...repeat for each style type, or return the original style
  return style
}
const extendDecorator: ExtendDecoratorSchemaType = (decorator) => {
  if (decorator.name === 'strong') {
    return {
      ...decorator,
      // Optional: add a react component as an icon and unset the title
      icon: () => B,
      // Optional: connect to a keyboard shortcut from the keyboard-shortcuts library
      shortcut: bold,
      title: '',
    }
  }
  // ...repeat for each decorator type, or return the original decorator
  return decorator
}

// Create a button for each decorator type
const DecoratorButton = (props: {schemaType: ToolbarDecoratorSchemaType}) => {
  const decoratorButton = useDecoratorButton(props)
  return (
     decoratorButton.send({type: 'toggle'})}
      className={
        decoratorButton.snapshot.matches({enabled: 'active'}) ? 'active' : ''
      }
    >
      {props.schemaType.icon && }
      {props.schemaType.title}
    
  )
}
function StyleButton(props: {schemaType: ToolbarStyleSchemaType}) {
  const styleSelector = useStyleSelector({schemaTypes: [props.schemaType]})
  return (
    
        styleSelector.send({type: 'toggle', style: props.schemaType.name})
      }
      className={styleSelector.snapshot.matches('enabled') ? 'active' : ''}
    >
      {props.schemaType.icon && }
      {props.schemaType.title}
    
  )
}
// ... and so on for each schema type, or create a generic button
```

The `useStyleSelector` and `useDecoratorButton` hooks give you access to the active editor. `send` lets you send events to the editor, and `snapshot` lets you read the current state of the editor.



In the next step, you'll add the toolbar to the editor.

## Bring it all together

With render functions created and a toolbar in place, you can fully render the editor. Add the `Toolbar` inside the `EditorProvider`.

```tsx
// App.tsx
// ...
function App() {
  const [value, setValue] = useState | undefined>(
    undefined,
  )

  return (
    <>
      
         {
            if (event.type === 'mutation') {
              setValue(event.value)
            }
          }}
        />
         
{props.children}
}
          renderListItem={(props) => <>{props.children}}
        />
        
      
    
  )
}
// ...
```

You can now enter text and interact with the toolbar buttons to toggle the styles and decorators. These are only a small portion of the types of things you can do. Check out the [custom rendering guide](/editor/guides/custom-rendering/) and the [toolbar customization guide](/editor/guides/customize-toolbar/) for options.

## View the Portable Text data

You can preview the Portable Text from the editor by reading the state. Add the following after the `EditorProvider`:

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

```

This displays the raw Portable Text. To customize how Portable Text renders in your apps, explore the serializers.



## Behavior API

The Behavior API lets you customize how users interact with the editor by hooking into events:

- Declaratively hook into editor **events** and define new behaviors.
- Imperatively trigger **events**.
- Derive editor **state** using **pure functions**.
- Subscribe to **emitted** editor **events**.

Learn more about [behaviors](/editor/concepts/behavior/) and how to [create your own](/editor/guides/create-behavior/).

## Next steps


  
  
  


# Guides

> Step-by-step guides for working with the Portable Text Editor.

Practical guides for customizing and extending the Portable Text Editor.

### [Custom rendering](/editor/guides/custom-rendering/)

Change how the editor renders and styles text. Covers render props for blocks, spans, decorators, annotations, list items, placeholders, and range decorations.

### [Customize the toolbar](/editor/guides/customize-toolbar/)

Build custom toolbars using `@portabletext/toolbar` hooks. Covers decorator buttons, style selectors, keyboard shortcuts, undo/redo, and reflecting editor state.

### [Create a custom behavior](/editor/guides/create-behavior/)

Add custom behaviors to the editor. Walk through defining a behavior with events, guards, and actions, then registering it with `BehaviorPlugin`.

### [Behavior recipes](/editor/guides/behavior-cheat-sheet/)

Common solutions using the Behavior API: logging, auto-closing brackets, emoji pickers, and raising events.

# Behavior recipes

> Common solutions using the Behavior API.

import {CardGrid, LinkCard} from '@astrojs/starlight/components'
import {PackageManagers} from 'starlight-package-managers'

Below are some common behavior examples. You can also find a list of core behaviors [on GitHub](https://github.com/portabletext/editor/tree/main/packages/editor/src/behaviors).

:::note[Prerequisites]
These recipes are written for `@portabletext/editor` **v6.x** ([changelog](https://github.com/portabletext/editor/releases)).
:::

To add these to your editor, first import `defineBehavior` as well as the `BehaviorPlugin`.

```tsx
import {defineBehavior} from '@portabletext/editor/behaviors'
import {BehaviorPlugin} from '@portabletext/editor/plugins'
```

Then, register the behavior within the `EditorProvider` using the `BehaviorPlugin`.

```tsx

  
  {/* ... */}

```

Read more about using behaviors and building your own with these guides:


  
  


## Log inserted text

Send and `effect` type action along with a `forward` action to perform side effects without altering the chain of events.

```js
const logInsertText = defineBehavior({
  on: 'insert.text',
  actions: [
    ({event}) => [
      {
        type: 'effect',
        effect: () => {
          console.log(event)
        },
      },
      {
        type: 'forward',
        event,
      },
    ],
  ],
})
```

The `effect` and `forward` actions also have shorthand functions:

```tsx
const logInsertText = defineBehavior({
  on: 'insert.text',
  actions: [
    ({event}) => [
      effect(() => {
        console.log(event)
      }),
      forward(event),
    ],
  ],
})
```

## Auto-close parenthesis

You can write behaviors to auto-close common paired characters. This example closes parenthesis, and then moves the cursor in between the two characters. This logic can expand to cover more sets.

```js
const autoCloseParens = defineBehavior({
  on: 'insert.text',
  guard: ({snapshot, event}) => {
    return event.text === '('
  },
  actions: [
    ({snapshot, event}) => [
      // Execute the original event that includes the '('
      {type: 'execute', event},
      // Execute a new insert.text event with a closing parenthesis
      {
        type: 'execute',
        event: {
          type: 'insert.text',
          text: ')',
        },
      },
      // Execute a select event to move the cursor in between the parens
      {
        type: 'execute',
        event: {
          type: 'select',
          selection: {
            anchor: {
              path: snapshot.context.selection.anchor.path,
              offset: snapshot.context.selection.anchor.offset + 1,
            },
            focus: {
              path: snapshot.context.selection.focus.path,
              offset: snapshot.context.selection.focus.offset + 1,
            },
          },
        },
      },
    ],
  ],
})
```

The `execute` action also has a shorthand function:

```tsx
const autoCloseParens = defineBehavior({
  on: 'insert.text',
  guard: ({snapshot, event}) => {
    return event.text === '('
  },
  actions: [
    ({snapshot, event}) => [
      execute(event),
      // ...
    ],
  ],
})
```

## Emoji picker

An emoji picker that triggers when you insert `:` is available as a separate plugin package.

![Emoji picker in Portable Text Editor](../../../../assets/emoji-picker.png)

Test it out in the [Playground](https://playground.portabletext.org).

Install the package:



Use the `useEmojiPicker` hook to handle the state and logic:

```tsx
import {
  createMatchEmojis,
  useEmojiPicker,
} from '@portabletext/plugin-emoji-picker'

const matchEmojis = createMatchEmojis({
  emojis: {
    '😂': ['joy', 'laugh'],
    '😹': ['joy_cat'],
  },
})

function EmojiPickerComponent() {
  const {keyword, matches, selectedIndex, onDismiss, onNavigateTo, onSelect} =
    useEmojiPicker({matchEmojis})

  // Render your emoji picker UI using these values
}
```

- [View the plugin source](https://github.com/portabletext/editor/tree/main/packages/plugin-emoji-picker).
- [View the playground editor source](https://github.com/portabletext/editor/blob/main/apps/playground/src/editor.tsx).

## Raise events

Sometimes you want to trigger an event from within an action. This sends the event back to the editor, where the editor treats it like any other event.

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

The `raise` action also has a shorthand function:

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

:::note
Be careful when raising events, as this technique can lead to infinite loops if behaviors dispatch actions and events that trigger one another.
:::

# Create a custom behavior

> Add custom behaviors to the Portable Text Editor

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

Behaviors add functionality to the Portable Text Editor (PTE) in a declarative way.

:::note[Prerequisites]
This guide covers `@portabletext/editor` **v6.x** ([changelog](https://github.com/portabletext/editor/releases)). Requires React 18+.
:::

For a deep dive into behaviors and how they work, check out [Behaviors](/editor/concepts/behavior/).

## Import the behavior helper

Begin by importing `defineBehavior`.

```tsx
import {defineBehavior} from '@portabletext/editor/behaviors'
```

## Define the behavior

Behaviors need three things:

- A triggering event. See the [full list of events](/editor/reference/behavior-api#behavior-event-types).
- A guard, or condition that determines if this behavior should apply.
- An action to invoke if the event and guard are met.

Here's an example behavior:

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

Let's break it down:

1. It listens for the `insert.text` event. You can use any [native, synthetic or custom event](/editor/reference/behavior-api#behavior-event-types) here.
2. The guard checks if the text that triggered this event is equal to a lowercase `a`. The guard is true and the behavior will perform the actions.
3. It sends an `execute` action with an `insert.text` event to insert "A" instead of "a".



## Register the behavior

In order to use the behavior, add it to the `EditorProvider` using the `BehaviorPlugin`.

```tsx
import {defineBehavior} from '@portabletext/editor/behaviors'
import {BehaviorPlugin} from '@portabletext/editor/plugins'

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

// ...


    
    {/* ... */}

```

# Custom blocks and inline objects

> Add images, code blocks, and other structured content to the Portable Text Editor.

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

The Portable Text Editor handles text blocks (paragraphs, headings, lists) by default. To add structured content like images, code blocks, or calls to action, you define custom block types in your schema and tell the editor how to render and insert them.

:::note[Prerequisites]
This guide covers `@portabletext/editor` **v6.x** and `@portabletext/toolbar` **v7.x** ([changelog](https://github.com/portabletext/editor/releases)). Requires React 18+. You should be familiar with the [getting started guide](/editor/getting-started/) and [custom rendering](/editor/guides/custom-rendering/).
:::

## How custom blocks work

There are two kinds of custom content in Portable Text:

- **Block objects** sit alongside text blocks in the document array. An image, a code block, or a call-to-action are block objects.
- **Inline objects** sit inside text blocks, within the text flow. A stock ticker, a product reference, or a custom emoji are inline objects.

Both follow the same three-step pattern:

1. **Define** the type in your schema (`blockObjects` or `inlineObjects`)
2. **Render** it in the editor (`renderBlock` or `renderChild` prop)
3. **Insert** it via the toolbar (`useBlockObjectButton` or `useInlineObjectButton` hook)

## Adding block objects

### Step 1: define in schema

Add your block type to the `blockObjects` array in `defineSchema`. Each block object has a name and optional fields:

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

const schemaDefinition = defineSchema({
  // ... styles, decorators, annotations, lists
  blockObjects: [{name: 'image'}, {name: 'code'}],
  inlineObjects: [],
})
```

The schema tells the editor which block types are valid. The field data (image URL, code language, etc.) is stored on the block object itself.

### Step 2: render in the editor

Use the `renderBlock` prop on `PortableTextEditable` to control how block objects appear in the editor. The function receives `props` with `schemaType.name` (the block type) and `value` (the block data):

```tsx
import type {PortableTextBlock, RenderBlockFunction} from '@portabletext/editor'

const renderBlock: RenderBlockFunction = (props) => {
  // Image block
  if (props.schemaType.name === 'image' && isImage(props.value)) {
    return (
      

        
        {props.value.caption && (
          

            {props.value.caption}
          
        )}
      
    )
  }

  // Code block
  if (props.schemaType.name === 'code' && isCodeBlock(props.value)) {
    return (
      
        {props.value.text}
      
    )
  }

  // Default: render text blocks with children
  return 
{props.children}
}

// Type guards for block data
function isImage(
  value: PortableTextBlock,
): value is PortableTextBlock & {src: string; alt?: string; caption?: string} {
  return 'src' in value
}

function isCodeBlock(
  value: PortableTextBlock,
): value is PortableTextBlock & {text: string; language?: string} {
  return 'text' in value
}
```

Pass the function to `PortableTextEditable`:

```tsx

```

:::note
The `renderBlock` function handles both text blocks and custom block objects. Text blocks have `children` (the text content). Custom block objects have `value` (the structured data). Always include a default case that renders `{props.children}` for text blocks.
:::

### Step 3: insert via toolbar

Use the `useBlockObjectButton` hook from `@portabletext/toolbar` to create an insert button. The hook follows the same pattern as `useDecoratorButton` and `useStyleSelector`:

```tsx
import {
  useBlockObjectButton,
  useToolbarSchema,
  type ExtendBlockObjectSchemaType,
  type ToolbarBlockObjectSchemaType,
} from '@portabletext/toolbar'

// Extend the schema to add icons and titles for the toolbar
const extendBlockObject: ExtendBlockObjectSchemaType = (blockObject) => {
  if (blockObject.name === 'image') {
    return {...blockObject, title: 'Image', icon: () => 🖼}
  }
  if (blockObject.name === 'code') {
    return {...blockObject, title: 'Code', icon: () => {''}}
  }
  return blockObject
}

function Toolbar() {
  const toolbarSchema = useToolbarSchema({extendBlockObject})

  return (
    

      {/* ... decorator and style buttons */}
      {toolbarSchema.blockObjects?.map((blockObject) => (
        
      ))}
    
  )
}

function BlockObjectButton(props: {schemaType: ToolbarBlockObjectSchemaType}) {
  const blockObjectButton = useBlockObjectButton(props)
  return (
     blockObjectButton.send('open dialog')}
      disabled={!blockObjectButton.snapshot.matches('enabled')}
    >
      {props.schemaType.icon && }
      {props.schemaType.title}
    
  )
}
```

When the user clicks the button, the editor opens a dialog for that block type. You control what happens in the dialog: collect the data, then insert the block.

For blocks that need user input (like images), use the dialog flow:

```tsx
// In the dialog's submit handler:
blockObjectButton.send({
  type: 'insert',
  value: {src: imageUrl, alt: altText},
  placement: undefined,
})
```

For blocks that don't need initial data, insert directly:

```tsx
onClick={() => blockObjectButton.send({
  type: 'insert',
  value: {},
  placement: undefined,
})}
```

## Adding inline objects

Inline objects work the same way as block objects, but they appear inside text blocks rather than alongside them.

### Step 1: define in schema

```tsx
const schemaDefinition = defineSchema({
  // ... styles, decorators, annotations, lists, blockObjects
  inlineObjects: [{name: 'stock-ticker'}],
})
```

### Step 2: render in the editor

Use the `renderChild` prop. Inline objects receive `props.value` with the object data:

```tsx
import type {PortableTextChild, RenderChildFunction} from '@portabletext/editor'

const renderChild: RenderChildFunction = (props) => {
  if (props.schemaType.name === 'stock-ticker' && isStockTicker(props.value)) {
    return (
      
        📈 {props.value.symbol}
        {props.value.exchange && (
          
            {props.value.exchange}
          
        )}
      
    )
  }

  // Default: render inline children
  return <>{props.children}
}

function isStockTicker(
  value: PortableTextChild,
): value is PortableTextChild & {symbol: string; exchange?: string} {
  return 'symbol' in value
}
```

### Step 3: insert via toolbar

Use `useInlineObjectButton`, which works identically to `useBlockObjectButton`:

```tsx
import {
  useInlineObjectButton,
  type ExtendInlineObjectSchemaType,
  type ToolbarInlineObjectSchemaType,
} from '@portabletext/toolbar'

const extendInlineObject: ExtendInlineObjectSchemaType = (inlineObject) => {
  if (inlineObject.name === 'stock-ticker') {
    return {...inlineObject, title: 'Stock', icon: () => 📈}
  }
  return inlineObject
}

function InlineObjectButton(props: {
  schemaType: ToolbarInlineObjectSchemaType
}) {
  const inlineObjectButton = useInlineObjectButton(props)
  return (
     inlineObjectButton.send('open dialog')}
      disabled={!inlineObjectButton.snapshot.matches('enabled')}
    >
      {props.schemaType.icon && }
      {props.schemaType.title}
    
  )
}
```

Add the inline object buttons to your toolbar alongside the block object buttons:

```tsx
function Toolbar() {
  const toolbarSchema = useToolbarSchema({
    extendBlockObject,
    extendInlineObject,
  })

  return (
    

      {/* ... decorator and style buttons */}
      {toolbarSchema.blockObjects?.map((blockObject) => (
        
      ))}
      {toolbarSchema.inlineObjects?.map((inlineObject) => (
        
      ))}
    
  )
}
```

## The Portable Text output

When a user inserts a block object, the editor produces a block in the Portable Text array with the custom `_type`:

```json
[
  {
    "_type": "block",
    "_key": "abc123",
    "style": "normal",
    "children": [{"_type": "span", "text": "Here is a photo:"}],
    "markDefs": []
  },
  {
    "_type": "image",
    "_key": "def456",
    "src": "https://example.com/photo.jpg",
    "alt": "A mountain landscape"
  },
  {
    "_type": "block",
    "_key": "ghi789",
    "style": "normal",
    "children": [
      {"_type": "span", "text": "The current price of "},
      {
        "_type": "stock-ticker",
        "_key": "jkl012",
        "symbol": "AAPL",
        "exchange": "NASDAQ"
      },
      {"_type": "span", "text": " is rising."}
    ],
    "markDefs": []
  }
]
```

The image block sits between text blocks. The stock ticker sits inside a text block's `children` array. Both carry structured data that your rendering serializers can use.



## Next steps




# Customize editor rendering

> Change the way the editor renders and styles text.

The Portable Text Editor gives you control of how it renders each schema type element. You need to explicitly tell it what. These choices have no impact on the Portable Text output—they only affect how the editor itself renders content.

:::note[Prerequisites]
This guide covers `@portabletext/editor` **v6.x** ([changelog](https://github.com/portabletext/editor/releases)). Requires React 18+.
:::

The following props can be passed to the `PortableTextEditable` component:

- `renderAnnotation`: For annotations (e.g., hyperlinks).
- `renderBlock`: For block objects (e.g., images, embeds).
- `renderChild`: For inline objects (e.g., custom emoji, stock symbols).
- `renderDecorator`: For decorators (e.g., strong, italic, emphasis text).
- `renderStyle`: For core text block types (e.g., normal, h1, h2, h3, blockquote).
- `renderListItem`: For list item styling (e.g., bullet, numbered lists).
- `renderPlaceholder`: For custom placeholder text when the editor is empty.
- `rangeDecorations`: For highlighting specific ranges of text (e.g., search results, comments).

All the different render functions passed to `PortableTextEditable` can be defined as stand-alone React components.

Most follow the same pattern of reading `props` and conditionally rendering elements based on schema data.

Lists are a bit unique. Portable Text has no concept of block nesting, so the solution is to use pure CSS to style them. We suggest [including this example CSS](https://github.com/portabletext/editor/blob/main/examples/basic/src/editor.css) or similar to manage list rendering.

Here are basic implementations of some core types:

```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}
}

// Annotations
const renderAnnotation: RenderAnnotationFunction = (props) => {
  if (props.schemaType.name === 'link') {
    return {props.children}
  }

  return <>{props.children}
}

// Block objects
const renderBlock: RenderBlockFunction = (props) => {
  if (props.schemaType.name === 'image' && isImage(props.value)) {
    return (
      

        IMG: {props.value.src}
      
    )
  }

  return 
{props.children}
}

// Check the shape of an image and confirm it has a src.
function isImage(
  props: PortableTextBlock,
): props is PortableTextBlock & {src: string} {
  return 'src' in props
}

// Styles
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}
}

// Inline objects
const renderChild: RenderChildFunction = (props) => {
  if (props.schemaType.name === 'stock-ticker' && isStockTicker(props.value)) {
    return (
      
        {props.value.symbol}
      
    )
  }

  return <>{props.children}
}

// Check the shape of the object by confirming it has a symbol.
function isStockTicker(
  props: PortableTextChild,
): props is PortableTextChild & {symbol: string} {
  return 'symbol' in props
}

// List items
const renderListItem: RenderListItemFunction = (props) => {
  return <>{props.children}
}
```

:::note
List items in Portable Text don't nest like HTML lists. The `renderListItem` function wraps the content, but visual nesting is achieved through CSS. See the [example CSS](https://github.com/portabletext/editor/blob/main/examples/basic/src/editor.css) for list styling patterns.
:::

## Placeholder text

Use `renderPlaceholder` to display custom placeholder text when the editor is empty:

```tsx
 Start typing...}
  // ... other props
/>
```

## Range decorations

Use `rangeDecorations` to highlight specific ranges of text. This is useful for features like search highlighting, comments, or collaborative cursors:

```tsx
import type {RangeDecoration} from '@portabletext/editor'

const decorations: RangeDecoration[] = [
  {
    selection: {
      anchor: {path: [{_key: 'block1'}, 'children', {_key: 'span1'}], offset: 0},
      focus: {path: [{_key: 'block1'}, 'children', {_key: 'span1'}], offset: 5},
    },
    component: ({children}) => (
      {children}
    ),
  },
]


```

You can apply styles, libraries like Tailwind, or use custom react components within the rendering functions.

# Customize the toolbar

> Common patterns and techniques for creating custom toolbars for the editor.

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

The [getting started guide](/editor/getting-started/) introduces the basics of setting up toolbar components. This guide provides some extra context, best practices, and patterns to get you started.

:::note[Prerequisites]
This guide covers `@portabletext/toolbar` **v7.x** and `@portabletext/keyboard-shortcuts` **v2.x** ([changelog](https://github.com/portabletext/editor/releases)). Requires `@portabletext/editor` v6.x and React 18+.
:::

## Render the toolbar inside the provider

You must render any toolbars within `EditorProvider`, as any toolbar actions require access to the instance of the editor. There are two ways to do this:

### The `@portabletext/toolbar` hooks

The `@portabletext/toolbar` library provides a variety of hooks that allow you to dispatch events and view a snapshot of the editor state.

Each hook accepts an individual schema item and returns a `send` method and a `snapshot`. The most common pattern is to `send`, or dispatch, events, and `snapshot.matches` state, like enabled/disabled.

For example, a button can use `useDecoratorButton` to create interactive buttons for decorators. The hook accepts details about the decorator, provided by the `useToolbarSchema` hook.

```tsx
import {
  useDecoratorButton,
  useToolbarSchema,
  type ToolbarDecoratorSchemaType,
} from '@portabletext/toolbar'

const DecoratorButton = (props: {schemaType: ToolbarDecoratorSchemaType}) => {
  const decoratorButton = useDecoratorButton(props)
  return (
     decoratorButton.send({type: 'toggle'})}
      className={
        decoratorButton.snapshot.matches({enabled: 'active'}) ? 'active' : ''
      }
    >
      {props.schemaType.name}
    
  )
}

function ToolbarPlugin() {
  const toolbarSchema = useToolbarSchema()
  return (
    

      {toolBarSchema.decorators?.map((decorator) => (
        
      ))}
    
  )
}

function App() {
  //...
  return (
    <>
      
        // ...
        
      
    
  )
}
```

### The `useEditor` hook

The toolbar library is more closely linked to parts of the PTE—like decorators, styles, and annotations—but you can also access editor state without the context of individual schema items with `useEditor`.

You can send [synthetic events](/editor/reference/behavior-api/) from within the toolbar using `editor.send`.

```tsx
import {useEditor} from '@portabletext/editor'

function Toolbar() {
  const editor = useEditor()
  // ...
  return (
    <>
       {
          // Send decorator toggle event
          editor.send({
            type: 'decorator.toggle',
            decorator: decorator.name,
          })
        }}
      >
        {decorator.name}
      
    
  )
}
function App() {
  //...
  return (
    <>
      
        // ...
        
      
    
  )
}
```

## Modify or enhance the schema

Sometimes you need to enhance your schema to change a label or add a shortcut behavior, as shown in the [getting started guide](/editor/getting-started/). A common approach is to extend the schema. This is done in two steps:

### Extend the schema

```tsx
const extendDecorator: ExtendDecoratorSchemaType = (decorator) => {
  if (decorator.name === 'strong') {
    return {
      ...decorator,
      // Optional: add a react component as an icon and unset the title
      icon: () => B,
      // Optional: connect to a keyboard shortcut from the keyboard-shortcuts library
      shortcut: bold, // imported from @portabletext/keyboard-shortcuts
      title: '',
    }
  }
  // ...repeat for each decorator type, or return the original decorator
  return decorator
}
```

Repeat this same approach for styles, annotations, blocks, etc. as needed using the types from `@portabletext/toolbar`. Types are available for each schema type:

- [ExtendAnnotationSchemaType](/api/toolbar/type-aliases/extendannotationschematype/)
- [ExtendBlockObjectSchemaType](/api/toolbar/type-aliases/extendblockobjectschematype/)
- [ExtendDecoratorSchemaType](/api/toolbar/type-aliases/extenddecoratorschematype/)
- [ExtendInlineObjectSchemaType](/api/toolbar/type-aliases/extendinlineobjectschematype/)
- [ExtendListSchemaType](/api/toolbar/type-aliases/extendlistschematype/)
- [ExtendStyleSchemaType](/api/toolbar/type-aliases/extendstyleschematype/)

### Configure `useToolbarSchema` with the extended schema

The `useToolbarSchema` hook optionally accepts these extended schemas.

```tsx
const toolbarSchema = useToolbarSchema({
  extendDecorator,
  extendAnnotation,
  extendStyle,
  // etc
})
```

## Add keyboard shortcuts

The [Keyboard Shortcuts library](/editor/reference/keyboard-shortcuts/) offers drop-in keyboard shortcuts for the editor that can be paired with toolbar buttons, as well as a way to create your own custom keyboard shortcuts.

This pairs best with the extend schema approach, as it allows you to add keyboard shortcuts to your toolbar buttons.

Add the keyboard shortcut library to your project:



Import the keyboard shortcut you want to use from the library, and extend your schema.

```tsx
import {bold} from '@portabletext/keyboard-shortcuts'

const extendDecorator: ExtendDecoratorSchemaType = (decorator) => {
  if (decorator.name === 'strong') {
    return {
      ...decorator,
      // Optional: add a react component as an icon and unset the title
      icon: () => B,
      // Optional: connect to a keyboard shortcut from the keyboard-shortcuts library
      shortcut: bold, // imported from @portabletext/keyboard-shortcuts
      title: '',
    }
  }
  // ...repeat for each decorator type, or return the original decorator
  return decorator
}
```

## Add history buttons for undo/redo

The toolbar library ships with a `useHistoryButtons` hook. This is a convenience hook that limits which events the buttons can send.

Import the hook and create buttons.

```tsx
import {useHistoryButtons} from '@portabletext/toolbar'

function HistoryButtons() {
  const historyButtons = useHistoryButtons()
  return (
    <>
       historyButtons.send({type: 'history.undo'})}
        disabled={historyButtons.snapshot.matches('disabled')}
      >
        Undo
      
       historyButtons.send({type: 'history.redo'})}
        disabled={historyButtons.snapshot.matches('disabled')}
      >
        Redo
      
    
  )
}
```

Then, render the buttons in a toolbar component.

```tsx
function ToolbarPlugin() {
  // ...
  return (
    <>
      // ...
      
    
  )
}
```

## Additional toolbar hooks

The `@portabletext/toolbar` package provides several additional hooks for building toolbar components:

**Button hooks:**

- `useDecoratorButton` - Create buttons for toggling decorators (bold, italic, etc.)
- `useStyleSelector` - Create style selectors/dropdowns
- `useListButton` - Create buttons for list formatting
- `useAnnotationButton` - Create buttons for annotations (links, etc.)
- `useBlockObjectButton` - Create buttons for inserting block objects
- `useInlineObjectButton` - Create buttons for inserting inline objects

**Popover hooks:**

- `useAnnotationPopover` - Manage popovers for annotation editing (e.g., link URL input)
- `useBlockObjectPopover` - Manage popovers for block object editing
- `useInlineObjectPopover` - Manage popovers for inline object editing

Each hook returns a `send` method for dispatching events and a `snapshot` for reading state.

## Use selectors to reflect editor state

The editor offers a variety of helpful selectors for checking the status of inline and block content. Selectors are pure functions that derive state from the editor snapshot. You can find the full list in the [selectors reference](/editor/reference/selectors/).

:::note
This approach is specific to accessing state with `useEditor`. While the hooks from `@portabletext/toolbar` do access and interact with the editor state, they do not expose the active editor itself for use in selectors.
:::

A few useful selectors for using in the toolbar are:

- `getActiveStyle`: Get's the active style of the selection.
- `isActiveDecorator`: Returns `true` if the active selection matches the decorator.
- `isActiveAnnotation`: Returns `true` if the active selection matches the annotation.
- `isActiveStyle`: Returns `true` if the active selection matches the style.

You can import each selector individually from `@portabletext/editor/selectors` or import them all as shown below.

```tsx
import * as selectors from '@portabletext/editor/selectors'
```

You can then combine these with the `useEditorSelector` hook in your toolbar components. For example, this button will underline if the selected text matches the annotation.

```tsx
function AnnotationButton(props: {
  annotation: SchemaDefinition['annotations'][number]
}) {
  const editor = useEditor()
  // useEditorSelector takes the editor instance and the selector
  const active = useEditorSelector(
    editor,
    selectors.isActiveAnnotation(props.annotation.name),
  )

  return (
    
      {props.annotation.name}
    
  )
}
```

# Testing behaviors

> Test custom behaviors with Gherkin specs or direct Vitest tests.

import {LinkCard, TabItem, Tabs} from '@astrojs/starlight/components'
import {PackageManagers} from 'starlight-package-managers'

The Portable Text Editor ships with testing infrastructure you can use for your own behaviors. There are two approaches: Gherkin specs with Racejar (the same approach every official plugin uses) and direct Vitest tests for simpler cases.

Both approaches use Vitest Browser Mode with Playwright, running tests against a real browser.

:::note[Prerequisites]
This guide covers `@portabletext/editor` **v6.x** and `racejar` **v2.x** ([changelog](https://github.com/portabletext/editor/releases)). Requires Vitest with Browser Mode and Playwright.
:::

## Setup

Install the testing dependencies:



Configure Vitest for Browser Mode in your `vitest.config.ts`:

```ts
import {defineConfig} from 'vitest/config'

export default defineConfig({
  test: {
    browser: {
      enabled: true,
      provider: 'playwright',
      instances: [{browser: 'chromium'}],
    },
  },
})
```

If you use TypeScript, declare `.feature` file imports:

```ts
// global.d.ts
declare module '*.feature?raw' {
  const content: string
  export default content
}
```

## Quick start: direct Vitest tests

For simple behavior tests, use `createTestEditor` directly. This is the fastest way to verify a behavior works:

```tsx
import {defineSchema} from '@portabletext/editor'
import {defineBehavior, execute} from '@portabletext/editor/behaviors'
import {BehaviorPlugin} from '@portabletext/editor/plugins'
import {createTestEditor} from '@portabletext/editor/test/vitest'
import {getTersePt} from '@portabletext/test'
import {describe, expect, test, vi} from 'vitest'
import {userEvent} from 'vitest/browser'

describe('uppercase A behavior', () => {
  test('replaces lowercase a with uppercase A', async () => {
    const {editor, locator} = await createTestEditor({
      children: (
         event.text === 'a',
              actions: [() => [execute({type: 'insert.text', text: 'A'})]],
            }),
          ]}
        />
      ),
      schemaDefinition: defineSchema({
        decorators: [{name: 'strong'}],
      }),
    })

    await userEvent.click(locator)
    await userEvent.type(locator, 'a')

    await vi.waitFor(() => {
      expect(getTersePt(editor.getSnapshot().context)).toEqual(['A'])
    })
  })
})
```

**Key parts:**

- **`createTestEditor`** spins up a real editor in the browser. Returns `{editor, locator}` where `editor` is the editor instance and `locator` is a Playwright locator for user interactions.
- **`getTersePt`** from `@portabletext/test` gives you a compact representation of the editor content for assertions. `['foo ,bar, baz']` means one block with three spans (commas separate spans).
- **`editor.getSnapshot().context`** gives you the full editor state including `value` (the Portable Text array) and `selection`.
- **`vi.waitFor`** is needed because editor updates are asynchronous.

## Gherkin approach with Racejar

For comprehensive behavior specs, write Gherkin feature files and run them with Racejar. This is how every official plugin is tested.

### Step 1: write a feature file

Create a `.feature` file that describes your behavior in plain English:

```gherkin
# my-behavior.feature

Feature: Auto-capitalize after period

  Scenario: Capitalizes first letter after period and space
    Given the text "hello."
    When the editor is focused
    And the caret is put after "hello."
    And " " is typed
    And "w" is typed
    Then the text is "hello. W"

  Scenario: Does not capitalize mid-sentence
    Given the text "hello"
    When the editor is focused
    And the caret is put after "hello"
    And " w" is typed
    Then the text is "hello w"

  Scenario: Undo restores original text
    Given the text "hello."
    When the editor is focused
    And the caret is put after "hello."
    And " " is typed
    And "w" is typed
    Then the text is "hello. W"
    When undo is performed
    Then the text is "hello. w"
```

Gherkin scenarios follow the Given/When/Then pattern:

- **Given** sets up the editor state (text content, marks, selections)
- **When** performs actions (typing, key presses, toolbar interactions)
- **Then** asserts the result (text content, marks, selections)

### Step 2: wire up the test

Create a test file that connects your feature file to the editor:

```tsx
// my-behavior.test.tsx
import {defineSchema} from '@portabletext/editor'
import {parameterTypes} from '@portabletext/editor/test'
import {
  createTestEditor,
  stepDefinitions,
  type Context,
} from '@portabletext/editor/test/vitest'
import {Before} from 'racejar'
import {Feature} from 'racejar/vitest'
import {MyBehaviorPlugin} from './my-behavior-plugin'
import myFeature from './my-behavior.feature?raw'

Feature({
  hooks: [
    Before(async (context: Context) => {
      const {editor, locator} = await createTestEditor({
        children: ,
        schemaDefinition: defineSchema({
          decorators: [{name: 'strong'}, {name: 'em'}],
          annotations: [{name: 'link'}],
        }),
      })

      context.locator = locator
      context.editor = editor
    }),
  ],
  featureText: myFeature,
  stepDefinitions,
  parameterTypes,
})
```

That's it. Racejar compiles the `.feature` file into test cases, and the pre-built step definitions handle the Given/When/Then steps.

### Step 3: run the tests

```bash
npx vitest
```

Each Gherkin scenario becomes a separate test case. Failures show which step failed and what the editor state was at that point.

## Pre-built step definitions

The editor ships with step definitions that cover the most common test scenarios. You get these for free when you import from `@portabletext/editor/test/vitest`:

**Given steps (setup):**

- `Given the text "..."` sets the editor content
- `Given "strong" around "..."` applies a decorator to text
- `Given a "link" "l1" around "..."` applies an annotation
- `Given a global keymap` sets up keyboard shortcut handling

**When steps (actions):**

- `When the editor is focused` focuses the editor
- `When "..." is typed` types text character by character
- `When "..." is inserted` inserts text all at once (mimics Android input)
- `When "{Enter}" is pressed` presses a key
- `When "{Backspace}" is pressed` presses backspace
- `When "..." is selected` selects text in the editor
- `When the caret is put after "..."` positions the cursor
- `When undo is performed` triggers undo
- `When redo is performed` triggers redo
- `When "link" is toggled` toggles an annotation
- `When "strong" is toggled` toggles a decorator

**Then steps (assertions):**

- `Then the text is "..."` asserts the editor content
- `Then "..." has marks "..."` asserts marks on text
- `Then "..." has no marks` asserts no marks on text
- `Then "..." is selected` asserts the current selection

These steps handle text blocks, marks, selections, undo/redo, and keyboard interactions. For custom block types or inline objects, you can add your own step definitions alongside the pre-built ones.

## Real-world example: em dash input rule

Here's how the official typography plugin tests its em dash behavior (converts `--` to `—`):

**Feature file** (`input-rule.em-dash.feature`):

```gherkin
Feature: Em Dash Input Rule

  Background:
    Given a global keymap

  Scenario: Inserting em dash in unformatted text
    Given the text "-"
    When "-" is inserted
    Then the text is "—"
    When undo is performed
    Then the text is "--"

  Scenario: Inserting em dash inside a decorator
    Given the text "foo-"
    And "strong" around "foo-"
    When the editor is focused
    And the caret is put after "foo-"
    And "-" is typed
    Then the text is "foo—"
    And "foo—" has marks "strong"
```

**Test file** (`input-rule.em-dash.test.tsx`):

```tsx
import {defineSchema} from '@portabletext/editor'
import {parameterTypes} from '@portabletext/editor/test'
import {
  createTestEditor,
  stepDefinitions,
  type Context,
} from '@portabletext/editor/test/vitest'
import {Before} from 'racejar'
import {Feature} from 'racejar/vitest'
import emDashFeature from './input-rule.em-dash.feature?raw'
import {TypographyPlugin} from './plugin.typography'

Feature({
  hooks: [
    Before(async (context: Context) => {
      const {editor, locator} = await createTestEditor({
        children: ,
        schemaDefinition: defineSchema({
          decorators: [{name: 'strong'}],
          annotations: [{name: 'link'}],
        }),
      })

      context.locator = locator
      context.editor = editor
    }),
  ],
  featureText: emDashFeature,
  stepDefinitions,
  parameterTypes,
})
```

The test file is 20 lines. The feature file describes the behavior in plain English. The pre-built step definitions do the heavy lifting.

## Adding custom step definitions

If your behavior involves custom block types or domain-specific assertions, add your own step definitions alongside the pre-built ones:

```tsx
import {stepDefinitions as builtInSteps} from '@portabletext/editor/test/vitest'
import {Given, Then, When} from 'racejar'

const customSteps = [
  Given('an image block with src {string}', async (context, src) => {
    // Set up editor with an image block
  }),
  Then('the image src is {string}', async (context, expectedSrc) => {
    // Assert image block data
  }),
]

Feature({
  // ...
  stepDefinitions: [...builtInSteps, ...customSteps],
})
```

Racejar will error if a step definition is missing or if you define duplicates.

## Next steps





# Reference

> API reference for the Portable Text Editor and its packages.

Reference documentation for the editor's APIs, plugins, and tools.

### [Editor API](/editor/reference/editor/)

The `useEditor` and `useEditorSelector` hooks for interacting with the editor programmatically.

### [Behavior API](/editor/reference/behavior-api/)

Complete reference for `defineBehavior`: all native, synthetic, and custom event types, guard patterns, and action types (`execute`, `forward`, `raise`, `effect`).

### [Selectors](/editor/reference/selectors/)

Pure functions for deriving state from the editor snapshot. Includes block selectors, span selectors, selection state, active marks, and text position utilities.

### [Keyboard shortcuts](/editor/reference/keyboard-shortcuts/)

The `@portabletext/keyboard-shortcuts` package. Platform-aware shortcuts for common formatting operations.

### [Plugins](/editor/reference/plugins/)

Available editor plugins: markdown shortcuts, emoji picker, input rules, character pair decorators, paste link, one-line mode, typeahead picker, and typography transforms.

### [Toolbar](/editor/reference/toolbar/)

The `@portabletext/toolbar` package. React hooks for building toolbar UI components.

# Behavior API overview

> Reference documentation for the Behavior API.

import EventTypesList from '@/components/EventTypesList.astro'

Reference docs for the behavior API.

## `defineBehavior`

Options Object

- on (string): Internal editor event
- guard (function or boolean): function accepts `snapshot`, `event`, and `dom`, returns boolean or guard response
- actions (array): function accepts `snapshot`, `event`, `dom`, and guard response, returns array of actions

The `dom` parameter provides access to DOM-related utilities like `dom.findDOMNode()` for accessing the underlying DOM elements.

### Example

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

## Behavior event types

### Native event types



### Synthetic event types





### Custom event types

- custom.\* (e.g. custom.add link)

## Behavior actions

- [execute](#execute)
- [forward](#forward)
- [raise](#raise)
- effect

### `execute`

The `execute` action type is used to execute events to resolution.

Properties:

- type: `execute`
- event: Native event object

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

When an event is executed, no other Behavior will be triggered.

The `execute` action also has a handy shorthand function:

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

### `forward`

The `forward` action type is used to forward events to the next Behavior.

Properties:

- type: `forward`
- event: Behavior event object

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

When an event is forwarded, the next Behavior will be triggered.

The `forward` action also has a handy shorthand function:

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

### `raise`

The `raise` action type is used to sends events back into the editor.

Properties:

- type: `raise`
- event: Behavior event object

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

The `raise` action also has a handy shorthand function:

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

# Editor API overview

> Hooks for accessing the Portable Text Editor instance and deriving state with selectors.

The editor API provides access to the editor instance and selectors for deriving state.

Use the following hooks to access the editor from within your components.

## `useEditor`

Access the editor instance. Commonly used when building toolbars or passing snapshot to selectors.

```tsx
import {useEditor} from '@portabletext/editor'

const editor = useEditor()
```

## `useEditorSelector`

Access selectors in areas where the snapshot is available by combining with `useEditor`.

```tsx
import {useEditor, useEditorSelector} from '@portabletext/editor'
import * as selectors from '@portabletext/editor/selectors'

const editor = useEditor()
const isActive = useEditorSelector(editor, selectors.isActiveDecorator('em'))
```

# Keyboard shortcuts API overview

> Drop-in and custom keyboard shortcuts for the Portable Text Editor via @portabletext/keyboard-shortcuts.

import {CardGrid, LinkCard} from '@astrojs/starlight/components'
import {PackageManagers} from 'starlight-package-managers'

The Keyboard Shortcuts API offers drop-in keyboard shortcuts for the editor that can be paired with toolbar buttons, as well as a way to create your own custom keyboard shortcuts.



See the Generated API reference for available keyboard shortcuts (variables) and functions for creating your own.


  


# Plugins

> React components placed inside the EditorProvider to register behaviors and extend the Portable Text Editor.

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

Plugins are React components placed inside the `EditorProvider`, and are primarily used to register [Behaviors](/editor/concepts/behavior/) ad-hoc in the Editor using the `editor.registerBehavior(...)` API:

```tsx
function LogTextPlugin() {
  const editor = useEditor()

  useEffect(() => {
    const unregisterBehavior = editor.registerBehavior({
      behavior: defineBehavior({
        on: 'insert.text',
        actions: [
          ({event}) => [
            {
              type: 'effect',
              effect: () => {
                console.log(event)
              },
            },
            {
              type: 'forward',
              event,
            },
          ],
        ],
      }),
    })

    return () => {
      unregisterBehavior()
    }
  }, [editor])

  return null
}
```

## Available plugins


  
  
  
  
  
  
  
  
  


# Selectors API overview

> Pure functions that derive state from the editor snapshot, used to build behaviors and toolbar components.

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

Selectors are pure functions that derive state from the editor snapshot. They provide a clean way to access editor state without directly parsing the snapshot structure.

```tsx
import * as selectors from '@portabletext/editor/selectors'
```

Selectors are commonly used for creating behaviors and toolbar components.


  
  


:::note
Unsure what a "span" is or what "focus" means in this context? Check the [common terms](/editor/concepts/portabletext/#common-terms) section.
:::

## Condition selectors

Condition selectors return a boolean or truthy value based on the current editor state.

### Active state conditions

- `isActiveAnnotation(name)` - Returns `true` if the specified annotation is active in the selection
- `isActiveDecorator(name)` - Returns `true` if the specified decorator is active in the selection
- `isActiveListItem(name)` - Returns `true` if the specified list type is active
- `isActiveStyle(name)` - Returns `true` if the specified style is active

### Selection conditions

- `isSelectionCollapsed` - Returns `true` if the selection is collapsed (cursor with no range)
- `isSelectionExpanded` - Returns `true` if the selection spans multiple characters

### Position conditions

- `isAtTheStartOfBlock` - Returns `true` if the cursor is at the start of a block
- `isAtTheEndOfBlock` - Returns `true` if the cursor is at the end of a block
- `isSelectingEntireBlocks` - Returns `true` if entire blocks are selected

### Range conditions

- `isOverlappingSelection` - Returns `true` if selections overlap
- `isPointBeforeSelection` - Returns `true` if a point is before the current selection
- `isPointAfterSelection` - Returns `true` if a point is after the current selection

## Block selectors

Retrieve block-level elements from the editor.

### Navigation

- `getFirstBlock` - Get the first block in the editor
- `getLastBlock` - Get the last block in the editor
- `getNextBlock` - Get the block after the current focus block
- `getPreviousBlock` - Get the block before the current focus block

### Focus & anchor

- `getAnchorBlock` - Get the block where the selection anchor is located
- `getFocusBlock` - Get the block where the selection focus is located

### Selection range

- `getSelectedBlocks` - Get all blocks within the current selection
- `getSelectionStartBlock` - Get the block at the start of the selection
- `getSelectionEndBlock` - Get the block at the end of the selection

## Text block selectors

Retrieve text blocks specifically (excludes block objects).

- `getAnchorTextBlock` - Get the text block where the selection anchor is located
- `getFocusTextBlock` - Get the text block where the selection focus is located
- `getSelectedTextBlocks` - Get all text blocks within the current selection
- `getFocusListBlock` - Get the list block where focus is located (if in a list)

## Span selectors

Retrieve span elements (text segments within blocks).

- `getAnchorSpan` - Get the span where the selection anchor is located
- `getFocusSpan` - Get the span where the selection focus is located
- `getNextSpan` - Get the span after the current focus span
- `getPreviousSpan` - Get the span before the current focus span
- `getSelectedSpans` - Get all spans within the current selection

## Child selectors

Retrieve child elements within blocks.

- `getAnchorChild` - Get the child element where the selection anchor is located
- `getFocusChild` - Get the child element where the selection focus is located
- `getSelectionStartChild` - Get the child at the start of the selection
- `getSelectionEndChild` - Get the child at the end of the selection

## Inline object selectors

Retrieve inline objects (custom elements embedded in text).

- `getFocusInlineObject` - Get the inline object at the current focus position
- `getNextInlineObject` - Get the next inline object after focus
- `getNextInlineObjects` - Get all inline objects after focus
- `getPreviousInlineObject` - Get the previous inline object before focus
- `getPreviousInlineObjects` - Get all inline objects before focus

## Block object selectors

Retrieve block objects (custom block-level elements).

- `getFocusBlockObject` - Get the block object at the current focus position

## Selection selectors

Get information about the current selection.

- `getSelection` - Get the current selection (anchor and focus points)
- `getSelectionText` - Get the text content of the current selection
- `getSelectedValue` - Get the Portable Text value of the selected content
- `getSelectionStartPoint` - Get the starting point of the selection
- `getSelectionEndPoint` - Get the ending point of the selection
- `getCaretWordSelection` - Get the word selection at the caret position

## Active state selectors

Get information about active formatting and marks.

- `getActiveAnnotations` - Get all active annotations in the selection
- `getActiveListItem` - Get the active list item type
- `getActiveStyle` - Get the active block style
- `getMarkState` - Get comprehensive mark state information for the selection

## Text position selectors

Get text content relative to the cursor position.

- `getBlockTextBefore` - Get text in the current block before the cursor
- `getBlockTextAfter` - Get text in the current block after the cursor
- `getBlockOffsets` - Get character offsets within the current block

## Value selectors

Access the editor value.

- `getValue` - Get the complete Portable Text value from the editor

# Toolbar API overview

> Hooks and types from @portabletext/toolbar for building custom toolbars for the Portable Text Editor.

import {CardGrid, LinkCard} from '@astrojs/starlight/components'
import {PackageManagers} from 'starlight-package-managers'

The Toolbar API offers assorted hooks and types for building your own toolbars.




  


# Introduction

> What Portable Text is, how it works, and where to start.

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

## What is Portable Text?

Portable Text is a JSON-based specification for structured block content. Instead of storing content as an HTML string or Markdown, Portable Text represents it as an array of typed blocks: each block has a `_type` and carries its own data.

```text
┌─────────────────────────────────────────┐
│         Portable Text document          │
│         (array of blocks)               │
│                                         │
│  ┌─ _type: block ────────────────────┐  │
│  │ style: "h1"                       │  │
│  │ "Why Portable Text?"              │  │
│  └───────────────────────────────────┘  │
│  ┌─ _type: block ────────────────────┐  │
│  │ style: "normal"                   │  │
│  │ "Read the **docs** for details."  │  │
│  │  └─ annotation: link (href, ...)  │  │
│  └───────────────────────────────────┘  │
│  ┌─ _type: image ────────────────────┐  │
│  │ url: "photo.jpg"                  │  │
│  │ alt: "A mountain landscape"       │  │
│  │ caption: "View from the summit"   │  │
│  └───────────────────────────────────┘  │
│  ┌─ _type: block ────────────────────┐  │
│  │ style: "normal"                   │  │
│  │ "Current price: [stockTicker] ."  │  │
│  │  └─ inline: stockTicker           │  │
│  │      symbol: "AAPL"               │  │
│  │      exchange: "NASDAQ"           │  │
│  └───────────────────────────────────┘  │
│  ┌─ _type: callToAction ─────────────┐  │
│  │ text: "Start building"            │  │
│  │ url: "/getting-started"           │  │
│  └───────────────────────────────────┘  │
└─────────────────────────────────────────┘
```

Text blocks, image blocks, and custom blocks like a call-to-action all live in the same array. A serializer walks the array and renders each block based on its type.

### Three levels of extensibility

Portable Text is a **block content format**, not just a rich text format. Rich text (formatted paragraphs with bold, italic, and links) is one type of block among many. The format supports three levels of custom content:

```text
Block level          Custom block types sit alongside text blocks
                     (images, code blocks, CTAs, embeds, tables)
                     ─────────────────────────────────────────────
Inline level         Inline objects sit inside text blocks
                     (stock tickers, product refs, custom emoji)
                     ─────────────────────────────────────────────
Mark level           Annotations carry data on text spans
                     (links with tracking, refs with doc IDs,
                      comments, footnotes)
```

**Custom blocks** are any `_type` you define. An image block carries url, alt, and caption. A code block carries language and source. A CTA carries text and a link. The serializer renders each one through a component you provide.

**Inline objects** are structured data embedded in the text flow. A stock ticker inside a paragraph carries symbol and exchange data. A product reference carries a product ID. They're not text with formatting; they're data that happens to appear within text.

**Annotations** are data-carrying marks on text spans. A link annotation isn't just an `` tag: it's a data object with href, target, tracking parameters, or whatever fields you define. You can query "find all documents that link to /pricing" because the link data is structured JSON, not buried in an HTML string.

### How rendering works

A serializer converts the block array into your target format. The same Portable Text renders as React components, HTML strings, Markdown, PDFs, or plain text:

```text
                    ┌──────────────┐
                ┌──→│ React        │──→ 
...
                │   └──────────────┘
┌───────────┐   │   ┌──────────────┐
│ Portable  │───┼──→│ HTML         │──→ 
...
│ Text JSON │   │   └──────────────┘
└───────────┘   │   ┌──────────────┐
                ├──→│ Markdown     │──→ # Hello **world**
                │   └──────────────┘
                │   ┌──────────────┐
                └──→│ PDF / email  │──→ (any format)
                    └──────────────┘
```

Default block types (paragraphs, headings, lists, bold, italic, links) work out of the box. Custom blocks and annotations need a component for each type. If a serializer encounters a type it doesn't recognize, it skips it. Nothing breaks.

### Why structured data?

Because content is JSON, you can:

- **Render anywhere.** Pass the same data to any serializer. Each renders what it can, ignores what it can't.
- **Query the content.** "Find all blocks that contain a link to /pricing" is a JSON query, not a regex over HTML.
- **Extend without breaking.** Add new block types, inline objects, or annotation types. Renderers that don't recognize them skip them gracefully.
- **Validate the structure.** The schema is explicit. You know exactly what types of content exist and what data they carry.

[Learn why Portable Text over HTML, Markdown, or Gutenberg →](/why-portable-text/)

## Get started

There are two ways to work with Portable Text:


  
  


# Render Portable Text

> How to render Portable Text as HTML, React components, or any other format.

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

Portable Text is stored as JSON. To display it, you pass the data through a **serializer** that converts each block into your target output: HTML strings, React components, Vue templates, Markdown, or any other format.

## How it works

A Portable Text document is an array of blocks. Each block has a `_type` that tells the serializer what it is and how to render it.

Some blocks are **text blocks** (`_type: "block"`): paragraphs, headings, lists, and inline formatting. Serializers handle these out of the box.

But Portable Text isn't just rich text. The same array can contain **any type of structured content**: images, code blocks, calls to action, videos, tables, or types you define yourself. These custom blocks sit alongside text blocks in the array, each with their own `_type` and data. You provide a component for each custom type, and the serializer renders them in sequence.

Within text blocks, **marks** add meaning to inline text. **Decorators** (bold, italic, underline) work by default. **Annotations** (links, references, footnotes) carry structured data as mark definitions. A link annotation isn't just an `` tag: it's a data object with href, target, tracking parameters, or whatever fields you define. You customize annotation rendering through the `marks` component map. Text blocks can also contain **inline objects**: structured data embedded in the text flow, like a stock ticker, a product reference, or a custom emoji. Inline objects are rendered through the same `types` component map as custom blocks.

If a serializer encounters a type it doesn't recognize, it skips it. Nothing breaks.

## Get started

Install the serializer for your framework:


  
    ```bash
    npm install @portabletext/react
    ```

    ```tsx
    import {PortableText} from '@portabletext/react'

    function Article({content}) {
      return 
    }
    ```

    [React guide →](/rendering/react/)

  

  
    ```bash
    npm install @portabletext/to-html
    ```

    ```ts
    import {toHTML} from '@portabletext/to-html'

    const html = toHTML(portableTextContent)
    ```

    [HTML guide →](/rendering/html/)

  

  
    ```bash
    npm install @portabletext/markdown
    ```

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

    const markdown = portableTextToMarkdown(portableTextContent)
    ```

    Also converts Markdown → Portable Text. [Conversion guide →](/conversion/markdown-to-portable-text/)

  

  
    ```bash
    npm install @portabletext/vue
    ```

    ```vue
    

    
    ```

    [Vue guide →](/rendering/vue/)

  

  
    ```bash
    npm install @portabletext/svelte -D
    ```

    ```svelte
    

    
    ```

    Requires Svelte 5+. [Svelte guide →](/rendering/svelte/)

  

  
    ```bash
    npm install astro-portabletext
    ```

    ```astro
    ---
    import {PortableText} from 'astro-portabletext'

    const {content} = Astro.props
    ---

    
    ```

    [Astro guide →](/rendering/astro/)

  


That's enough to render paragraphs, headings, lists, bold, italic, and links. But Portable Text can contain much more than formatted text. The next sections show how to render custom block types and marks.

## Rendering custom block types

This is where Portable Text goes beyond rich text. Custom blocks carry structured data (images, CTAs, embeds, code blocks) that the serializer doesn't know how to render by default. You tell it what to do by mapping the block's `_type` to a component.

Here's an image block in Portable Text:

```json
{
  "_type": "image",
  "_key": "abc123",
  "url": "https://example.com/photo.jpg",
  "alt": "A mountain landscape",
  "caption": "View from the summit"
}
```

The `_type` is `"image"`. To render it, add an `image` entry to the `types` component map:


  
    ```tsx
    import {PortableText} from '@portabletext/react'

    const components = {
      types: {
        image: ({value}) => (
          

            
            {value.caption && }
          
        ),
      },
    }

    function Article({content}) {
      return 
    }
    ```

  

  
    ```ts
    import {toHTML} from '@portabletext/to-html'

    const html = toHTML(portableTextContent, {
      components: {
        types: {
          image: ({value}) => {
            const caption = value.caption
              ? ``
              : ''
            return `
${caption}
`
          },
        },
      },
    })
    ```

  

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

    const markdown = portableTextToMarkdown(portableTextContent, {
      types: {
        image: ({value}) => {
          const alt = value.alt || ''
          const caption = value.caption ? `\n\n*${value.caption}*` : ''
          return `![${alt}](${value.url})${caption}`
        },
      },
    })
    ```

  


The pattern is the same in every framework: map the `_type` to a function that receives the block's data as `value` and returns your output.

This works for any custom block type. A call-to-action, a code block, an embedded video, a table: define the `_type` in your schema, add a component to the `types` map, and the serializer handles the rest.

## Rendering custom marks

Marks add meaning to inline text. There are two kinds:

**Decorators** are simple flags like `strong`, `em`, and `underline`. Serializers render these by default (bold, italic, underlined text).

**Annotations** carry data. A link annotation looks like this in Portable Text:

```json
{
  "_type": "block",
  "children": [
    {"_type": "span", "text": "Read the "},
    {"_type": "span", "text": "documentation", "marks": ["link1"]},
    {"_type": "span", "text": "."}
  ],
  "markDefs": [
    {
      "_key": "link1",
      "_type": "link",
      "href": "/docs",
      "openInNewTab": true
    }
  ]
}
```

The span with `"marks": ["link1"]` references the mark definition with `"_key": "link1"`. The mark definition carries the data (`href`, `openInNewTab`). To customize how this renders, add a `link` entry to the `marks` component map:


  
    ```tsx
    const components = {
      marks: {
        link: ({children, value}) => {
          const rel = !value.href.startsWith('/')
            ? 'noreferrer noopener'
            : undefined
          return (
            
              {children}
            
          )
        },
      },
    }
    ```
  

  
    ```ts
    import {uriLooksSafe} from '@portabletext/to-html'

    const components = {
      marks: {
        link: ({children, value}) => {
          const href = value.href || ''
          if (!uriLooksSafe(href)) return children

          const rel = href.startsWith('/') ? '' : ' rel="noreferrer noopener"'
          const target = value.openInNewTab ? ' target="_blank"' : ''
          return `${children}`
        },
      },
    }
    ```

    :::tip[Security]
    The `@portabletext/to-html` package exports `uriLooksSafe()` to reject dangerous URI schemes like `javascript:` and `data:`. Use it when rendering links from user-generated content.
    :::

  

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

    const markdown = portableTextToMarkdown(portableTextContent, {
      marks: {
        link: ({children, value}) => {
          const href = value.href || ''
          const title = value.title ? ` "${value.title}"` : ''
          return `[${children}](${href}${title})`
        },
      },
    })
    ```

    The default link renderer already handles standard links. Custom mark renderers are useful when your annotations carry extra data (tracking parameters, tooltips, etc.) that you want to preserve in the Markdown output.

  


Mark components receive `children` (the annotated text, already rendered) and `value` (the mark definition data). The same pattern works for any annotation type: footnotes, internal references, highlights, or custom marks specific to your schema.

## Component map reference

All serializers use the same component map structure (except Astro, which uses singular keys `type` and `mark`):

| Key         | What it renders                 | When you need it                        |
| ----------- | ------------------------------- | --------------------------------------- |
| `types`     | Custom block and inline objects | Images, CTAs, code blocks, embeds       |
| `marks`     | Annotations (marks with data)   | Links, footnotes, references            |
| `block`     | Block styles                    | Custom heading styles, pull quotes      |
| `list`      | List containers                 | Custom bullet or numbered list wrappers |
| `listItem`  | List items                      | Custom list item rendering              |
| `hardBreak` | Line breaks within text         | Custom line break handling              |

Unknown types, marks, and styles are skipped by default. You can handle them with `unknownType`, `unknownMark`, `unknownBlockStyle`, `unknownList`, and `unknownListItem` components.

## Framework guides

Each framework has its own patterns for custom components, TypeScript support, and utilities:


  
  
  
  
  
  


## All packages

For the complete list of serializers, converters, and community packages, see [All packages](/ecosystem/packages/).

# Astro

> Render Portable Text in Astro using the astro-portabletext community package.

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

`astro-portabletext` is a community package maintained by [theisel](https://github.com/theisel/astro-portabletext). It is recommended by Sanity for rendering Portable Text in Astro projects. It is not part of the official `@portabletext` organization.

**Requires Astro v4.6 or later.**

:::note[Prerequisites]
This guide covers `astro-portabletext` **v0.13.x** ([changelog](https://github.com/theisel/astro-portabletext/releases)). Requires Astro 4.6+.
:::

## Install



## Basic usage

Pass your Portable Text array to the `PortableText` component via the `value` prop.

```astro
---
import {PortableText} from 'astro-portabletext'

const {content} = Astro.props
---


```

## Custom components

You can override how any node type is rendered by passing a `components` object. The keys map to node types in your content.

```astro
---
import {PortableText} from 'astro-portabletext'
import BulletList from './BulletList.astro'
import Hero from './Hero.astro'
import Highlight from './Highlight.astro'
import Link from './Link.astro'
import PageHeading from './PageHeading.astro'

const portableText = [
  /* your Portable Text payload */
]

const components = {
  type: {
    hero: Hero,
  },
  block: {
    h1: PageHeading,
  },
  list: {
    bullet: BulletList,
  },
  mark: {
    link: Link,
    highlight: Highlight,
  },
}
---


```

:::note[Singular prop names]
Unlike React, Vue, and Svelte (which use plural `types` and `marks`), Astro uses **singular** `type` and `mark` in the components object. This matches the Astro package's API.
:::

### Custom link annotation

Mark components receive a `MarkProps` type. Use `` to render the annotated text.

```astro
---
import type {MarkProps} from 'astro-portabletext/types'

export type Props = MarkProps<{href: string; target?: string}>

const {node} = Astro.props
const {href, target} = node.value
---


  

```

### Custom block type

Custom block types (non-text blocks like heroes, callouts, or embeds) receive a `TypeProps` type.

```astro
---
import type {TypeProps} from 'astro-portabletext/types'

export type Props = TypeProps<{heading: string; imageUrl: string}>

const {node} = Astro.props
---


  
{node.heading}
  

```

## Slots

Astro's named slots let you wrap rendered output without replacing the underlying component. This is useful for adding CSS classes or wrapper elements to a whole category of nodes.

Available slot names: `type`, `block`, `list`, `listItem`, `mark`, `text`, `hardBreak`.

```astro
---
import {PortableText} from 'astro-portabletext'

const portableText = [
  /* your Portable Text payload */
]
---


  
    {
      ({Component, props, children}) => (
        
          {children}
        
      )
    }
  

  
    {
      ({Component, props, children}) => (
        {children}
      )
    }
  

```

Each slot receives a render function with `Component` (the resolved component), `props`, and `children`. You can add attributes, wrap with extra elements, or conditionally alter rendering without touching the component itself.

## Utility functions

```js
import {
  mergeComponents, // deep-merge component maps
  spanToPlainText, // extract plain text from a single span (v0.11.0+)
  toPlainText, // extract plain text from a Portable Text array
  usePortableText, // access default/unknown components inside custom components
} from 'astro-portabletext'
```

### usePortableText

`usePortableText` gives a custom component access to the default component for a given node. Use it when you want to handle some cases yourself and fall back to the default for everything else.

```astro
---
import {usePortableText} from 'astro-portabletext'
import type {MarkProps} from 'astro-portabletext/types'
import CustomLink from './CustomLink.astro'

export type Props = MarkProps

const props = Astro.props
const {getDefaultComponent} = usePortableText(props.node)

const Cmp = props.node.markType === 'link' ? CustomLink : getDefaultComponent()
---


  

```

### mergeComponents

`mergeComponents` deep-merges two component maps. Useful when you have a base set of components and want to extend or override them in a specific context.

### toPlainText and spanToPlainText

`toPlainText` extracts plain text from a Portable Text array. `spanToPlainText` (added in v0.11.0) does the same for a single span node.

## Further reading

Full documentation, changelog, and advanced usage are on [GitHub](https://github.com/theisel/astro-portabletext).

# HTML

> Render Portable Text to an HTML string using @portabletext/to-html. Works in Node.js, Deno, edge runtimes, and browsers.

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

`@portabletext/to-html` renders Portable Text to a plain HTML string. It has no framework dependency and works anywhere JavaScript runs: Node.js, Deno, edge runtimes, and browsers.

Use it for server-side rendering pipelines, static site generators, email templates, or any context where you need a string rather than a component tree.

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

## Install



## Basic usage

`toHTML` takes an array of Portable Text blocks and an options object. It returns an HTML string.

```js
import {toHTML} from '@portabletext/to-html'

const html = toHTML(portableTextBlocks, {
  components: {
    /* optional: override or extend default components */
  },
})
```

The `components` option is where you register renderers for custom types and marks. Without it, `toHTML` uses the built-in defaults for standard block styles, lists, and decorators.

## Custom components

### Custom link mark with URI safety checking

When rendering links from user-supplied content, you should validate the `href` before emitting it. `@portabletext/to-html` exports `uriLooksSafe()` for exactly this purpose.

:::caution[Security]
`uriLooksSafe()` rejects URIs with dangerous schemes like `javascript:`, `data:`, and `vbscript:`. Always run user-supplied `href` values through it before rendering them into anchor tags.
:::

The example below also uses [`htm`](https://github.com/developit/htm) and [`vhtml`](https://github.com/developit/vhtml) to construct HTML safely without string concatenation. See the note on [safe HTML construction](#safe-html-construction) below.

```js
import {toHTML, uriLooksSafe} from '@portabletext/to-html'
import htm from 'htm'
import vhtml from 'vhtml'

const html = htm.bind(vhtml)

const components = {
  types: {
    image: ({value}) =>
      html``,
    callToAction: ({value, isInline}) =>
      isInline
        ? html`${value.text}`
        : html`
${value.text}
`,
  },
  marks: {
    link: ({children, value}) => {
      const href = value.href || ''
      if (uriLooksSafe(href)) {
        const rel = href.startsWith('/') ? undefined : 'noreferrer noopener'
        return html`${children}`
      }
      return children
    },
  },
}

const result = toHTML(portableTextBlocks, {components})
```

The `link` mark renderer above:

1. Checks the `href` with `uriLooksSafe()` before rendering it.
2. Adds `rel="noreferrer noopener"` on external links (any `href` that does not start with `/`).
3. Returns `children` unwrapped if the URI fails the safety check, rather than rendering a broken or dangerous link.

### Safe HTML construction

Component functions return strings. You can use template literals directly, but that requires careful manual escaping of every interpolated value. A safer approach is to use `htm` + `vhtml`:

- [`htm`](https://github.com/developit/htm) provides JSX-like tagged template syntax.
- [`vhtml`](https://github.com/developit/vhtml) renders virtual DOM nodes to an HTML string, escaping attribute values and text content automatically.

Bind them once at the top of your file:

```js
import htm from 'htm'
import vhtml from 'vhtml'

const html = htm.bind(vhtml)
```

Then use `` html`...` `` in your component functions instead of raw string interpolation.

## API reference

### `toHTML(blocks, options)`

| Parameter                    | Type                                       | Description                                                             |
| ---------------------------- | ------------------------------------------ | ----------------------------------------------------------------------- |
| `blocks`                     | `PortableTextBlock \| PortableTextBlock[]` | The Portable Text content to render.                                    |
| `options.components`         | `PortableTextHtmlComponents`               | Component map. Keys listed below.                                       |
| `options.onMissingComponent` | `function \| false`                        | Called when a component is not found. Pass `false` to silence warnings. |

### Component map keys

| Key                 | Renders                                      | Receives                        |
| ------------------- | -------------------------------------------- | ------------------------------- |
| `types`             | Custom object types (block or inline)        | `{ value, isInline }`           |
| `marks`             | Decorators and annotations                   | `{ markType, value, children }` |
| `block`             | Block styles (normal, h1-h6, blockquote)     | `{ value, children }`           |
| `list`              | List containers (bullet, number)             | `{ value, children }`           |
| `listItem`          | List items                                   | `{ value, children }`           |
| `hardBreak`         | Line breaks within spans (default: `
`) | (none)                          |
| `unknownMark`       | Fallback for unregistered marks              | `{ markType, value, children }` |
| `unknownType`       | Fallback for unregistered types              | `{ value, isInline }`           |
| `unknownBlockStyle` | Fallback for unregistered block styles       | `{ value, children }`           |
| `unknownList`       | Fallback for unregistered list styles        | `{ value, children }`           |
| `unknownListItem`   | Fallback for unregistered list item styles   | `{ value, children }`           |

The `unknown*` keys let you define graceful fallbacks instead of relying on the default behavior (which logs a warning and renders nothing or plain text).

## Exported utilities

```js
import {
  defaultComponents, // built-in component implementations
  escapeHTML, // HTML-escape a raw string
  toHTML, // main render function
  uriLooksSafe, // URI safety checker
} from '@portabletext/to-html'
```

| Export              | Description                                                                                                    |
| ------------------- | -------------------------------------------------------------------------------------------------------------- |
| `toHTML`            | Renders Portable Text blocks to an HTML string.                                                                |
| `uriLooksSafe`      | Returns `true` if a URI does not use a dangerous scheme. Use this before rendering any user-supplied `href`.   |
| `escapeHTML`        | Escapes `&`, `<`, `>`, `"`, and `'` in a raw string. Useful when building component functions without `vhtml`. |
| `defaultComponents` | The built-in component map. Spread and override individual keys to extend defaults rather than replace them.   |

## Missing component warnings

By default, `toHTML` logs a warning to the console when it encounters a type or mark with no registered component. You can route these warnings to your own logger or silence them entirely.

```js
toHTML(blocks, {
  onMissingComponent: (message, {type, nodeType}) => {
    myLogger.warn(message, {type, nodeType})
  },
})

// Or silence entirely:
toHTML(blocks, {onMissingComponent: false})
```

`nodeType` is one of `'block'`, `'mark'`, `'blockStyle'`, `'listStyle'`, or `'listItemStyle'`. Use it to filter which missing components you care about.

## Further reading

Full API documentation, changelog, and source: [`@portabletext/to-html` on GitHub](https://github.com/portabletext/to-html).

# Markdown

> Render Portable Text as Markdown strings 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.
:::

`@portabletext/markdown` renders Portable Text blocks as Markdown strings. Use it to generate Markdown for static site generators, README files, AI prompts, or any system that consumes Markdown.

Looking to convert Markdown into Portable Text? See the [Markdown to Portable Text](/conversion/markdown-to-portable-text/) conversion guide.

## Install



## Basic usage

`portableTextToMarkdown` takes an array of Portable Text blocks and returns a Markdown string. Standard block styles, decorators, and links are handled automatically.

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

const markdown = portableTextToMarkdown(blocks)
```

## Custom type renderers

Custom block types (objects in the blocks array) are not rendered by default. Register a renderer for each type you use.

```ts
portableTextToMarkdown(blocks, {
  types: {
    chart: ({value}) => `![${value.title}](${value.imageUrl})`,
  },
})
```

Type renderers receive `value` (the block object), `index` (position in the array), and `isInline` (whether the object appears inline or as a block). Return an empty string to skip an element entirely.

```ts
portableTextToMarkdown(blocks, {
  types: {
    image: ({value, isInline}) => {
      if (isInline) return ''
      return `![${value.alt || ''}](${value.src})`
    },
  },
})
```

## Custom block style renderers

Override how block styles render by providing a `block` map. Each renderer receives `value` (the block) and `children` (the already-rendered content of the block).

```ts
portableTextToMarkdown(blocks, {
  block: {
    h1: ({children}) => `# ${children} #`,
    blockquote: ({children}) => `
${children}
`,
  },
})
```

## Built-in type renderers

The package exports default renderers for common block types. Import and register the ones you need.

```ts
import {
  DefaultCalloutRenderer,
  DefaultCodeBlockRenderer,
  DefaultHorizontalRuleRenderer,
  DefaultHtmlRenderer,
  DefaultImageRenderer,
  DefaultTableRenderer,
  portableTextToMarkdown,
} from '@portabletext/markdown'

portableTextToMarkdown(blocks, {
  types: {
    'callout': DefaultCalloutRenderer,
    'code': DefaultCodeBlockRenderer,
    'horizontal-rule': DefaultHorizontalRuleRenderer,
    'html': DefaultHtmlRenderer,
    'image': DefaultImageRenderer,
    'table': DefaultTableRenderer,
  },
})
```

| Renderer                        | Expected fields         | Output                 |
| ------------------------------- | ----------------------- | ---------------------- |
| `DefaultCalloutRenderer`        | `tone`, `content`       | `> [!TYPE]\n> content` |
| `DefaultCodeBlockRenderer`      | `code`, `language?`     | ` ```lang\ncode\n``` ` |
| `DefaultHorizontalRuleRenderer` | (none required)         | `---`                  |
| `DefaultHtmlRenderer`           | `html`                  | Raw HTML string        |
| `DefaultImageRenderer`          | `src`, `alt?`, `title?` | `![alt](src "title")`  |
| `DefaultTableRenderer`          | `rows`, `headerRows?`   | Markdown table         |

## Renderer map keys

| Key                 | What it renders                            |
| ------------------- | ------------------------------------------ |
| `types`             | Custom block and inline objects            |
| `marks`             | Annotations and decorators                 |
| `block`             | Block styles (headings, blockquotes, etc.) |
| `listItem`          | List items                                 |
| `hardBreak`         | Line breaks within blocks                  |
| `unknownType`       | Fallback for unregistered types            |
| `unknownBlockStyle` | Fallback for unregistered block styles     |
| `unknownListItem`   | Fallback for unregistered list items       |
| `unknownMark`       | Fallback for unregistered marks            |

By default, unknown types render as JSON code blocks. Unknown marks, block styles, and list items pass through their children unchanged.

## Supported features

| Feature          | PT to Markdown |
| ---------------- | :------------: |
| 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 registering the built-in renderer (see above).

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

## Further reading

- [Markdown to Portable Text](/conversion/markdown-to-portable-text/) for converting Markdown into PT blocks
- [`@portabletext/markdown` on GitHub](https://github.com/portabletext/editor/tree/main/packages/markdown) for full API documentation and changelog

# React

> How to render Portable Text in React using @portabletext/react.

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

## Install



## Basic usage

Pass your Portable Text value to the `PortableText` component. The library handles blocks, marks, lists, and inline content with sensible defaults.

```jsx
import {PortableText} from '@portabletext/react'

export default function MyComponent({value}) {
  return 
}
```

The `value` prop accepts a single block object or an array of block objects.

:::note[Prerequisites]
This guide covers `@portabletext/react` **v6.x** ([changelog](https://github.com/portabletext/react-portabletext/releases)). Requires React 18+.
:::

## Custom components

Override the default rendering by passing a `components` prop. Each key in the object maps to a part of the Portable Text structure.

### Custom link annotation

Marks are inline annotations: bold, italic, links, and any custom annotations you define. Override them under `marks`.

This example adds safe `rel` attributes to external links:

```jsx
const components = {
  marks: {
    link: ({children, value}) => {
      const rel = !value.href.startsWith('/')
        ? 'noreferrer noopener'
        : undefined
      return (
        
          {children}
        
      )
    },
  },
}
```

Pass the components object to `PortableText`:

```jsx

```

### Custom block type (image with @sanity/image-url)

Custom block types (objects embedded in your content) are handled under `types`. Each component receives the block's `value` and an `isInline` boolean indicating whether it appears inline or as a standalone block.

```jsx
import {getImageDimensions} from '@sanity/asset-utils'
import {createImageUrlBuilder} from '@sanity/image-url'

// Initialize with your Sanity project config
const builder = createImageUrlBuilder({
  projectId: 'yourProjectId',
  dataset: 'production',
})
const urlFor = (source) => builder.image(source)

const SampleImageComponent = ({value, isInline}) => {
  const {width, height} = getImageDimensions(value)
  return (
    
  )
}
```

Register it under the type name you used in your schema:

```jsx
const components = {
  types: {
    image: SampleImageComponent,
  },
}
```

### Combined example

You can define `types`, `marks`, and `block` styles in a single components object:

```jsx
const components = {
  types: {
    image: ({value}) => ,
    callToAction: ({value, isInline}) =>
      isInline ? (
        {value.text}
      ) : (
        
{value.text}
      ),
  },
  marks: {
    link: ({children, value}) => {
      const rel = !value.href.startsWith('/')
        ? 'noreferrer noopener'
        : undefined
      return (
        
          {children}
        
      )
    },
  },
  block: {
    h1: ({children}) => 
{children}
,
    blockquote: ({children}) => (
      
{children}
    ),
  },
}
```

## TypeScript

Import `PortableTextComponents` to type your components object. This gives you autocomplete on component keys and typed props for each renderer.

```tsx
import {PortableText, PortableTextComponents} from '@portabletext/react'

const components: PortableTextComponents = {
  marks: {
    link: ({value, children}) => {
      const target = (value?.href || '').startsWith('http')
        ? '_blank'
        : undefined
      return (
        
          {children}
        
      )
    },
  },
  block: {
    normal: ({children}) => 
{children}
,
    h1: ({children}) => 
{children}
,
  },
}

export default function Article({value}) {
  return 
}
```

## Available component keys

The `components` prop accepts the following keys. Any key you omit falls back to the default renderer.

| Key                 | What it renders                                                                          |
| ------------------- | ---------------------------------------------------------------------------------------- |
| `types`             | Custom block types and inline object types. Keyed by `_type` value.                      |
| `marks`             | Inline annotations (links, custom decorators). Keyed by mark type name.                  |
| `block`             | Standard text blocks. Keyed by `style` value (`normal`, `h1`, `h2`, `blockquote`, etc.). |
| `list`              | List wrappers. Keyed by list type (`bullet`, `number`).                                  |
| `listItem`          | Individual list items. Keyed by list type.                                               |
| `hardBreak`         | Line breaks within a block (rendered as `
` by default).                            |
| `unknownMark`       | Fallback for mark types with no matching component.                                      |
| `unknownType`       | Fallback for block types with no matching component.                                     |
| `unknownBlockStyle` | Fallback for block styles with no matching component.                                    |
| `unknownList`       | Fallback for list types with no matching component.                                      |
| `unknownListItem`   | Fallback for list item types with no matching component.                                 |

The `unknown*` keys are useful for debugging: render a visible warning so you can spot unhandled types during development.

## Further reading

Full API reference, changelog, and additional examples: [@portabletext/react on GitHub](https://github.com/portabletext/react-portabletext).

# Svelte

> Render Portable Text in Svelte 5 using @portabletext/svelte.

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

:::caution[Svelte 5 required]
`@portabletext/svelte` uses Svelte 5 runes and Snippets. Svelte 4 is not supported.
:::

:::note[Prerequisites]
This guide covers `@portabletext/svelte` **v3.x** ([changelog](https://github.com/portabletext/svelte-portabletext/releases)). Requires Svelte 5. Svelte 4 is not supported.
:::

## Install

Install as a dev dependency. Svelte packages are compiled at build time, so they belong in `devDependencies`.



## Basic usage

Pass your Portable Text value to the `PortableText` component. Your component receives props via the `$props()` rune.

```svelte



```

## Custom components

Override the default rendering by passing a `components` object. Use `types` for custom block types and `marks` for annotations.

```svelte



```

### Custom mark (annotation)

Mark components receive a `portableText` prop typed with `MarkComponentProps`, and a `children` Snippet for the annotated text content.

Use `$derived()` to destructure from `portableText`. This keeps the variable reactive when props change. See [Svelte 5 patterns](#svelte-5-patterns) below.

```svelte



{#if value.href}
  
    {@render children()}
  
{:else}
  {@render children()}
{/if}
```

### Custom block type

Block type components receive a `portableText` prop typed with `CustomBlockComponentProps`. Use `$derived()` to destructure `value`.

```svelte




  
  {#if value.caption}
    
  {/if}

```

## Svelte 5 patterns

`@portabletext/svelte` is built on Svelte 5 primitives. These patterns appear in every custom component.

| Pattern                | Usage                                                            |
| ---------------------- | ---------------------------------------------------------------- |
| `$props()`             | All components receive props via the `$props()` rune             |
| `$derived()`           | Use `$derived()` to keep variables reactive when props change    |
| `children: Snippet`    | Mark and block components receive children as a Svelte 5 Snippet |
| `{@render children()}` | Renders child content (replaces Svelte 4's ``)           |

### The $derived() reactivity requirement

Always use `$derived()` when destructuring from `portableText`. Destructuring directly breaks reactivity and leaves the variable stale after the first render.

```svelte

let { value } = $derived(portableText)


let { value } = portableText
```

This is the most common mistake when writing custom components. If your component renders correctly on first load but does not update when content changes, check your destructuring.

## Context prop

Use the `context` prop to share data with all components in the tree. This is useful for things like footnote numbering, theme tokens, or any value that multiple components need to read.

```svelte

```

Inside `Footnote.svelte`, read context from `portableText.global.context`. Use `$derived()` here too.

```svelte
let { footnotes } = $derived(portableText.global.context)
let number = $derived(
  footnotes.findIndex(note => note._key === portableText.value._key) + 1
)
```

## Plain text

Use `toPlainText()` to extract a plain text string from a Portable Text value. Useful for meta descriptions, search indexes, and other contexts where HTML is not appropriate.

```svelte



  

```

## Full documentation

For the complete API reference, all component prop types, and advanced usage, see the [`@portabletext/svelte` README on GitHub](https://github.com/portabletext/svelte-portabletext).

# Vue

> Render Portable Text in Vue 3 using @portabletext/vue.

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

## Install



## Basic usage

Pass your Portable Text value to the `PortableText` component using the `:value` prop.

```vue



```

The component renders standard block types (paragraphs, headings, lists, blockquotes) out of the box.

:::note[Prerequisites]
This guide covers `@portabletext/vue` **v1.x** ([changelog](https://github.com/portabletext/vue-portabletext/releases)). Requires Vue 3.
:::

## Custom components

Pass a `components` object to the `:components` prop to override how specific node types are rendered.
The prop names are plural: `types`, `marks`, `block`, `list`, `listItem`.

### Inline render functions with h()

For simple overrides, you can define components inline using Vue's `h()` function.
The render function receives props as the first argument and the render context (including `slots`) as the second.

Use `slots.default?.()` to render child content inside block and mark components.

```vue



```

### Vue SFC as a custom component

For more complex components, write a standard Vue single-file component and register it in the `components` map.

Use `PortableTextComponentProps` to type the props. The generic parameter `T` is the shape of your custom block's `value` field.

```vue




```

Then import and register it:

```vue



```

## Vue-specific patterns

| Pattern                         | Notes                                                                                                     |
| ------------------------------- | --------------------------------------------------------------------------------------------------------- |
| `