` | Text block, style `"normal"` | | `

` through `

` | Text block, style `"h1"` through `"h6"` | | `

` | Text block, style `"blockquote"` | | ``, `` | `"strong"` decorator | | ``, `` | `"em"` decorator | | `` | `"code"` decorator | | ``, ``, `` | `"strike-through"` decorator | | `` | `"link"` annotation with `href` and `title` | | `

` / `
` with `
1. ` | List items with `"bullet"` or `"number"` type | | `
   ` | Newline character within a span | | `

   ---

   ` | `"horizontal-rule"` block object | ## Schema as whitelist :::caution[Marks not in your schema are silently dropped] The schema controls what appears in the output. If a decorator, annotation, or block type isn't defined in the schema, the converter drops it without warning. This is the most common source of "my formatting disappeared" bugs. ::: The default schema includes `strong`, `em`, `code`, and `strike-through` as decorators. It does **not** include `underline`. If your HTML contains `` tags, the underline is silently removed unless you add it to your schema: ```ts import {htmlToPortableText} from '@portabletext/html' import {compileSchema, defineSchema} from '@portabletext/schema' const schema = compileSchema(defineSchema({ styles: [{name: 'normal'}, {name: 'h1'}, {name: 'h2'}, {name: 'h3'}], decorators: [ {name: 'strong'}, {name: 'em'}, {name: 'code'}, {name: 'strike-through'}, {name: 'underline'}, // now tags are preserved ], annotations: [{name: 'link', fields: [{name: 'href', type: 'string'}]}], lists: [{name: 'bullet'}, {name: 'number'}], })) const blocks = htmlToPortableText(html, {schema}) ``` In Sanity, your schema already defines which decorators are available. If your block type includes `underline` as a decorator, `htmlToBlocks` will preserve `` tags automatically. Other HTML elements that map to decorators but are **not** in the default schema: | HTML | Decorator name | Add to schema to preserve | | --------- | -------------- | ------------------------- | | `` | `underline` | `{name: 'underline'}` | | `` | `sup` | `{name: 'sup'}` | | `` | `sub` | `{name: 'sub'}` | | `` | `ins` | `{name: 'ins'}` | | `` | `mark` | `{name: 'mark'}` | | `` | `small` | `{name: 'small'}` | ## Handling images Images are skipped by default. This is intentional: the converter is synchronous, but image handling typically requires async work (downloading, uploading to a CDN, generating asset references). The converter can't do that inline. To capture images, provide a matcher: ```ts import {htmlToPortableText, type ObjectMatcher} from '@portabletext/html' import {compileSchema, defineSchema} from '@portabletext/schema' const schema = compileSchema(defineSchema({ blockObjects: [{name: 'image', fields: [{name: 'src', type: 'string'}]}], inlineObjects: [{name: 'image', fields: [{name: 'src', type: 'string'}]}], })) const imageMatcher: ObjectMatcher<{src?: string; alt?: string}> = ({ context, value, isInline, }) => { const collection = isInline ? context.schema.inlineObjects : context.schema.blockObjects if (!collection.some((obj) => obj.name === 'image')) return undefined return { _key: context.keyGenerator(), _type: 'image', ...(value.src ? {src: value.src} : {}), } } const blocks = htmlToPortableText(html, { schema, types: {image: imageMatcher}, }) ``` ```ts const blocks = htmlToBlocks(html, blockContentType, { parseHtml: (html) => new JSDOM(html).window.document, matchers: { image: ({context, props}) => ({ _key: context.keyGenerator(), _type: 'image', _sanityAsset: `image@${props.src}`, }), inlineImage: ({context, props}) => ({ _key: context.keyGenerator(), _type: 'image', _sanityAsset: `image@${props.src}`, }), }, }) ``` The `_sanityAsset` convention tells the Sanity client to download and upload the image during import. ### Two-phase image upload For migration scripts where you need to upload images to your own CDN or asset pipeline, use a two-phase approach: capture the URLs synchronously, then upload asynchronously: ```ts // Phase 1: capture image URLs as temporary block types const blocks = htmlToPortableText(html, { rules: [ { deserialize(el, next, createBlock) { if (el.tagName?.toLowerCase() !== 'img') return undefined return createBlock({ _type: 'externalImage', url: el.getAttribute('src') ?? '', alt: el.getAttribute('alt') ?? '', }).block }, }, ], }) // Phase 2: upload images and replace temporary blocks const finalBlocks = await Promise.all( blocks.map(async (block) => { if (block._type !== 'externalImage') return block const uploadedUrl = await uploadToYourCDN(block.url) return { _key: block._key, _type: 'image', src: uploadedUrl, alt: block.alt, } }), ) ``` ## Handling tables Tables are skipped by default. The `createFlattenTableRule` function (currently in beta) converts tables into a flat list of text blocks: ```ts import {htmlToPortableText} from '@portabletext/html' import {createFlattenTableRule} from '@portabletext/html/rules' const blocks = htmlToPortableText(html, { rules: [ createFlattenTableRule({ schema, separator: () => ({_type: 'span', text: ': '}), }), ], }) ``` This turns each table cell into a text block, with an optional separator between cells. For preserving full table structure, write a custom rule that maps `` to your own block type. :::note `createFlattenTableRule` is marked `@beta`. The API may change in future releases. ::: ## Custom rules Custom rules let you handle HTML elements that the built-in converter doesn't cover. A rule receives a DOM node and returns Portable Text blocks (or `undefined` to skip and let the next rule handle it). ### Example: code blocks with language The default converter treats `

   ` 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 round-tripping
   
   > What a Markdown → Portable Text → Markdown round trip preserves, normalizes, and degrades with @portabletext/markdown.
   
   {/* This page is the canonical source for round-trip behavior. packages/markdown/README.md and apps/docs/src/content/docs/conversion/markdown-to-portable-text.mdx (Round-trip behavior section) both carry condensed summaries; keep all three in sync, a claim corrected here is stale there. */}
   
   Converting Markdown to Portable Text and back with `markdownToPortableText` and `portableTextToMarkdown` isn't a lossless mirror. It's a contract with six guarantees and a short list of named exceptions. This page is for anyone evaluating a Markdown-based pipeline, an AI agent that reads or writes Markdown, an import/export tool, a migration from a Markdown-first CMS, who needs to know exactly what a round trip preserves, normalizes, or degrades.
   
   ## The contract
   
   ### 1. Translation preserves semantics, not source spelling
   
   The first Markdown → Portable Text → Markdown pass normalizes Markdown to one canonical spelling: autolinks and reference links become inline links, indented code becomes fenced code, soft-wrapped lines join into one, and emphasis, headings, lists, and tables each get one canonical form.
   
   ```md
   
   ```
   
   parses and serializes back as:
   
   ```md
   [https://portabletext.org](https://portabletext.org)
   ```
   
   ### 2. The normalized Markdown is a fixpoint
   
   The normalized Markdown is a fixpoint for plain text and for every construct in the [Supported features](/conversion/markdown-to-portable-text/#supported-features) table: parsing it and serializing again reproduces it byte-for-byte. Literal Markdown punctuation in a span's text is backslash-escaped when it serializes, so a second parse reads back the same characters instead of new markup.
   
   ```ts
   import {
     markdownToPortableText,
     portableTextToMarkdown,
   } from '@portabletext/markdown'
   
   portableTextToMarkdown([
     {
       _type: 'block',
       style: 'normal',
       children: [{_type: 'span', text: '*bar*', marks: []}],
       markDefs: [],
     },
   ])
   // -> '\*bar\*'
   
   markdownToPortableText('\\*bar\\*')
   // -> span text back to '*bar*'
   ```
   
   ### 3. MD → PT survival is schema-driven
   
   Constructs whose type the schema doesn't declare degrade predictably: they keep their content and drop the structure that named them. A mark, list, or task checkbox whose type isn't in the schema keeps its text and drops the formatting.
   
   ```ts
   import {compileSchema, defineSchema} from '@portabletext/schema'
   
   const schema = compileSchema(defineSchema({})) // no 'strong' decorator declared
   
   markdownToPortableText('**bar**', {schema})
   // -> [{..., children: [{text: 'bar', marks: []}]}]
   ```
   
   ### 4. PT → MD degradation is predictable
   
   Portable Text structures with no Markdown form degrade predictably going back out. GFM tables have one header row, so header rows beyond the first flatten into the body.
   
   ```ts
   portableTextToMarkdown([
     {
       _type: 'table',
       headerRows: 2,
       rows: [
         {
           _type: 'row',
           cells: [
             {
               _type: 'cell',
               value: [
                 /* 'H1a' */
               ],
             },
           ],
         },
         {
           _type: 'row',
           cells: [
             {
               _type: 'cell',
               value: [
                 /* 'H1b' */
               ],
             },
           ],
         },
         {
           _type: 'row',
           cells: [
             {
               _type: 'cell',
               value: [
                 /* 'data' */
               ],
             },
           ],
         },
       ],
     },
   ])
   ```
   
   ```md
   | H1a  |
   | ---- |
   | H1b  |
   | data |
   ```
   
   Deep or level-skipping list levels collapse to relative nesting: a list's first item renders at the top level whatever its `level`, and each deeper jump between items indents one step, however many levels it skips.
   
   ```ts
   portableTextToMarkdown([
     {
       _type: 'block',
       listItem: 'bullet',
       level: 1,
       children: [{_type: 'span', text: 'foo', marks: []}],
     },
     {
       _type: 'block',
       listItem: 'bullet',
       level: 4,
       children: [{_type: 'span', text: 'bar', marks: []}],
     },
     {
       _type: 'block',
       listItem: 'bullet',
       level: 1,
       children: [{_type: 'span', text: 'baz', marks: []}],
     },
   ])
   // -> '- foo\n   - bar\n- baz'
   ```
   
   An unknown object type renders as a fenced JSON block. That block is not a stopgap spelling of the original type: on reparse it comes back as a `code` object, not the type that went out. Round-tripping an unrecognized type through Markdown is destructive.
   
   ````ts
   portableTextToMarkdown([{_type: 'widget', _key: 'w1', color: 'blue'}])
   // -> '```json\n{\n  "_type": "widget",\n  "_key": "w1",\n  "color": "blue"\n}\n```'
   
   markdownToPortableText(/* the fenced block above */)
   // -> [{_type: 'code', language: 'json', code: '{\n  "_type": "widget",\n  "_key": "w1",\n  "color": "blue"\n}'}]
   // (a 'code' object, not the original 'widget' type)
   ````
   
   ### 5. Identity does not round-trip
   
   Keys are regenerated on every parse, and adjacent spans with identical marks merge into one.
   
   ```ts
   portableTextToMarkdown([
     {
       _type: 'block',
       children: [
         {_type: 'span', text: 'foo', marks: ['strong']},
         {_type: 'span', text: 'bar', marks: ['strong']},
       ],
     },
   ])
   // -> '**foobar**'
   
   markdownToPortableText('**foobar**')
   // -> one span, a new key, text: 'foobar', marks: ['strong']
   // (the two original spans and their keys are gone)
   ```
   
   ### 6. Hard breaks round-trip through a dedicated channel
   
   A `\n` inside a span's text and hard-break syntax (two or more trailing spaces, or a backslash, before the newline) are exclusive counterparts in both directions: a `\n` always renders as hard-break syntax on the way out, and hard-break syntax always becomes `\n` on the way in, never the space a soft wrap joins with.
   
   ```ts
   markdownToPortableText('line one\nline two')
   // -> one span, text: 'line one line two' (soft wrap, joined with a space)
   
   markdownToPortableText('line one  \nline two')
   // -> one span, text: 'line one\nline two' (hard break, kept as \n)
   
   portableTextToMarkdown([
     {
       _type: 'block',
       children: [{_type: 'span', text: 'line one\nline two', marks: []}],
     },
   ])
   // -> 'line one  \nline two' (hard-break syntax)
   ```
   
   ## Exceptions
   
   Three named exceptions qualify the fixpoint claim in guarantee 2 above.
   
   **Linkified substrings.** An explicit-scheme URL or an email address in a span's text is never escaped: the text stays byte-identical, but it gains a `link` mark on the next parse (autolinking is a parser feature, not a round-trip bug).
   
   ```ts
   portableTextToMarkdown([
     {
       _type: 'block',
       children: [
         {_type: 'span', text: 'Visit https://example.com now', marks: []},
       ],
     },
   ])
   // -> 'Visit https://example.com now'
   
   markdownToPortableText('Visit https://example.com now')
   // -> three spans: 'Visit ' (no marks), 'https://example.com' (marks: ['']),
   //    ' now' (no marks); a 'link' markDef with href 'https://example.com'
   
   portableTextToMarkdown(/* the three-span result above */)
   // -> 'Visit [https://example.com](https://example.com) now'
   ```
   
   The next serialization renders the now-marked span as the explicit inline link `[https://example.com](https://example.com)`, which is the stable form from that point on: reparsing and serializing again reproduces the same markdown byte-for-byte. The loop converges after one cycle, it never oscillates between the bare and linked spellings.
   
   Fuzzy `www.` forms follow the same unescaped-and-linkified path only while they carry no markdown-significant punctuation. Once one does, the punctuation takes normal escaping instead, the same as it would anywhere else in a span's text:
   
   ```ts
   portableTextToMarkdown([
     {
       _type: 'block',
       children: [
         {_type: 'span', text: 'see www.example.com/*x* today', marks: []},
       ],
     },
   ])
   // -> 'see www.example.com/\*x\* today'
   
   markdownToPortableText('see www.example.com/\\*x\\* today')
   // -> text back to 'see www.example.com/*x* today' (byte-identical), split across three spans:
   //    'see ' (no marks), 'www.example.com/' (marks: ['']), '*x* today' (no marks)
   ```
   
   **Heading hard-break structural split.** A hard break inside a heading forces a structural split into a second block on reparse, since an ATX heading is single-line. The text itself still survives, split across the two blocks.
   
   ```ts
   portableTextToMarkdown([
     {
       _type: 'block',
       style: 'h1',
       children: [{_type: 'span', text: 'foo\nbar', marks: []}],
     },
   ])
   // -> '# foo  \nbar' (hard-break syntax: two trailing spaces before the newline)
   
   markdownToPortableText('# foo  \nbar')
   // -> two blocks: {style: 'h1', children: [{text: 'foo'}]}, {style: 'normal', children: [{text: 'bar'}]}
   // (the span text survives, split across the two blocks; block identity doesn't)
   ```
   
   **CommonMark-inherent whitespace trimming.** Leading or trailing whitespace that CommonMark's own block parsing trims isn't part of the fixpoint claim.
   
   ```ts
   markdownToPortableText('  hello world  ')
   // -> span text: 'hello world' (no leading or trailing spaces)
   ```
   
   ## Further reading
   
   - [Markdown to Portable Text](/conversion/markdown-to-portable-text/) for parsing Markdown into PT blocks
   - [Markdown rendering](/rendering/markdown/) for rendering PT blocks as Markdown
   - [`@portabletext/markdown` on GitHub](https://github.com/portabletext/editor/tree/main/packages/markdown) for full API documentation and changelog
   
   # Markdown to Portable Text
   
   > Convert Markdown strings into Portable Text blocks using @portabletext/markdown.
   
   import {PackageManagers} from 'starlight-package-managers'
   
   {/* The schema, matcher, and supported-features tables mirror packages/markdown/README.md. Keep the twins in sync: a claim corrected in one place is stale in the other. The Round-trip behavior section is a summary; [Markdown round-tripping](/conversion/markdown-round-tripping/) is canonical. */}
   
   :::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.
   
   Soft-wrapped lines within a paragraph join with a single space; a hard break (two or more trailing spaces, or a backslash, before the newline) becomes a line break within the block.
   
   ## 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`, `task`                                     |
   | `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, build one with `compileSchema` and `defineSchema` from `@portabletext/schema` and pass it as the `schema` option; a Sanity schema converts first through `@portabletext/sanity-bridge`. The [package README](https://github.com/portabletext/editor/tree/main/packages/markdown#schema-configuration) has the configuration recipes for both.
   
   ## 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 (say, `'heading 1'` instead of `'h1'`): pass your own function under the matcher's group and name, resolve the type against `context.schema`, and return its name, or `undefined` to skip the element. The [package README](https://github.com/portabletext/editor/tree/main/packages/markdown#configuring-matchers) has worked matcher recipes, including the structural `table`, `list`, and `blockquote` shapes.
   
   ## Supported features
   
   | Feature          | Markdown to PT |
   | ---------------- | :------------: |
   | Headings (h1-h6) |       ✅       |
   | Paragraphs       |       ✅       |
   | Bold             |       ✅       |
   | Italic           |       ✅       |
   | Inline code      |       ✅       |
   | Strikethrough    |       ✅       |
   | Links            |       ✅       |
   | Blockquotes      |       ✅       |
   | Ordered lists    |       ✅       |
   | Unordered lists  |       ✅       |
   | Task lists       |       ✅       |
   | Nested lists     |       ✅       |
   | Code blocks      |       ✅       |
   | Horizontal rules |       ✅       |
   | Images           |       ✅       |
   | Tables           |       ✅       |
   | HTML blocks      |       ✅       |
   | Callouts         |       ✅       |
   
   :::note
   This package uses markdown-it as its Markdown parser. Remark and unified plugins are not compatible.
   :::
   
   ## Round-trip behavior
   
   Converting Markdown to Portable Text and back isn't a lossless mirror: translation normalizes rather than preserves, and structures either side can't express degrade predictably rather than failing. See [Markdown round-tripping](/conversion/markdown-round-tripping/) for the full contract, worked examples, and the named exceptions (linkified substrings, heading hard breaks, whitespace trimming).
   
   ## Other conversion paths
   
   | Source format   | Tool                                                                                                                           |
   | --------------- | ------------------------------------------------------------------------------------------------------------------------------ |
   | HTML → PT       | [`@portabletext/html`](/conversion/html-to-portable-text/)                                                                     |
   | Gutenberg → PT  | [`@emdash-cms/gutenberg-to-portable-text`](https://github.com/emdash-cms/emdash) (30+ block types)                             |
   | Contentful → PT | [`@portabletext/contentful-rich-text-to-portable-text`](https://github.com/portabletext/contentful-rich-text-to-portable-text) |
   
   ## Further reading
   
   - [Markdown rendering guide](/rendering/markdown/) for converting PT blocks to Markdown strings
   - [`@portabletext/markdown` on GitHub](https://github.com/portabletext/editor/tree/main/packages/markdown) for full API documentation and changelog
   
   # All packages
   
   > Every Portable Text package — serializers, converters, editor plugins, and utilities.
   
   import {Badge} from '@astrojs/starlight/components'
   
   The Portable Text ecosystem: official packages from the [`portabletext`](https://github.com/portabletext/) organization and community-maintained libraries. Packages marked with  are maintained outside the official organization.
   
   ## Render Portable Text
   
   Serializers convert Portable Text JSON into your target output.
   
   ### JavaScript
   
   | Package                                                                                                                         | Target       | Install                            |
   | ------------------------------------------------------------------------------------------------------------------------------- | ------------ | ---------------------------------- |
   | [`@portabletext/react`](https://github.com/portabletext/react-portabletext/)                                                    | React        | `npm i @portabletext/react`        |
   | [`@portabletext/to-html`](https://github.com/portabletext/to-html/)                                                             | HTML string  | `npm i @portabletext/to-html`      |
   | [`@portabletext/vue`](https://github.com/portabletext/vue-portabletext/)                                                        | Vue          | `npm i @portabletext/vue`          |
   | [`@portabletext/svelte`](https://github.com/portabletext/svelte-portabletext/)                                                  | Svelte 5+    | `npm i @portabletext/svelte`       |
   | [`@portabletext/solid`](https://github.com/portabletext/solid-portabletext/)                                                    | SolidJS      | `npm i @portabletext/solid`        |
   | [`@portabletext/react-native`](https://github.com/portabletext/react-native-portabletext/)                                      | React Native | `npm i @portabletext/react-native` |
   | [`@portabletext/react-pdf`](https://github.com/portabletext/react-pdf-portabletext)                                             | React PDF    | `npm i @portabletext/react-pdf`    |
   | [`astro-portabletext`](https://github.com/theisel/astro-portabletext)                  | Astro        | `npm i astro-portabletext`         |
   | [`portabletext-qwik`](https://github.com/tegonal/portabletext-qwik)                    | Qwik         | `npm i portabletext-qwik`          |
   | [`@limitless-angular/sanity`](https://github.com/limitless-angular/limitless-angular)  | Angular      | `npm i @limitless-angular/sanity`  |
   
   ### Other languages
   
   | Package                                                                                                                           | Language       |
   | --------------------------------------------------------------------------------------------------------------------------------- | -------------- |
   | [`dotnet-portable-text`](https://github.com/portabletext/dotnet-portable-text)                                                    | C# / .NET      |
   | [`portable-text-dotnet`](https://github.com/nhi/portable-text-dotnet)                    | C# / .NET      |
   | [`sanity-linq`](https://github.com/oslofjord/sanity-linq)                                | C# / .NET      |
   | [`portabletext-html`](https://github.com/otovo/python-portabletext-html)                 | Python         |
   | [`sanity-php`](https://github.com/sanity-io/sanity-php)                                                                           | PHP            |
   | [`flutter_sanity_portable_text`](https://pub.dev/packages/flutter_sanity_portable_text)  | Dart / Flutter |
   | [`flutter_portabletext`](https://github.com/JobiJoba/flutter_portabletext)               | Dart / Flutter |
   | [`ruby_portable_text`](https://github.com/beaucouplus/ruby_portable_text)                | Ruby           |
   | [`portabletext`](https://github.com/derickschaefer/portabletext)                         | Go             |
   
   ### Platform integrations
   
   | Integration                                                                          | Platform         |
   | ------------------------------------------------------------------------------------ | ---------------- |
   | [`transform.PortableText`](https://gohugo.io/functions/transform/portabletext/)      | Hugo (built-in)  |
   | [`portable-text-to-liquid`](https://github.com/portabletext/portable-text-to-liquid) | Shopify / Liquid |
   
   ## Build an editor
   
   | Package                                                                                                            | Purpose                                                        | Install                                  |
   | ------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------- | ---------------------------------------- |
   | [`@portabletext/editor`](https://github.com/portabletext/editor/tree/main/packages/editor)                         | Headless, schema-driven block content editor for React         | `npm i @portabletext/editor`             |
   | [`@portabletext/keyboard-shortcuts`](https://github.com/portabletext/editor/tree/main/packages/keyboard-shortcuts) | Platform-aware keyboard shortcuts                              | `npm i @portabletext/keyboard-shortcuts` |
   | [`@portabletext/sanity-bridge`](https://github.com/portabletext/editor/tree/main/packages/sanity-bridge)           | Convert between Sanity schemas and Portable Text schemas       | `npm i @portabletext/sanity-bridge`      |
   | [`@portabletext/schema`](https://github.com/portabletext/editor/tree/main/packages/schema)                         | Define and compile Portable Text schemas with full type safety | `npm i @portabletext/schema`             |
   | [`@portabletext/toolbar`](https://github.com/portabletext/editor/tree/main/packages/toolbar)                       | Headless toolbar hooks for the editor                          | `npm i @portabletext/toolbar`            |
   
   ### Editor plugins
   
   | Plugin                                                                                                                                       | What it does                                         | Install                                               |
   | -------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | ----------------------------------------------------- |
   | [`@portabletext/plugin-character-pair-decorator`](https://github.com/portabletext/editor/tree/main/packages/plugin-character-pair-decorator) | Match character pairs and decorate text between them | `npm i @portabletext/plugin-character-pair-decorator` |
   | [`@portabletext/plugin-dnd`](https://github.com/portabletext/editor/tree/main/packages/plugin-dnd)                                           | Track drop position for custom drop indicators       | `npm i @portabletext/plugin-dnd`                      |
   | [`@portabletext/plugin-emoji-picker`](https://github.com/portabletext/editor/tree/main/packages/plugin-emoji-picker)                         | Emoji picker                                         | `npm i @portabletext/plugin-emoji-picker`             |
   | [`@portabletext/plugin-input-rule`](https://github.com/portabletext/editor/tree/main/packages/plugin-input-rule)                             | Configure input rules                                | `npm i @portabletext/plugin-input-rule`               |
   | [`@portabletext/plugin-list-index`](https://github.com/portabletext/editor/tree/main/packages/plugin-list-index)                             | Compute list indices for custom list rendering       | `npm i @portabletext/plugin-list-index`               |
   | [`@portabletext/plugin-markdown-shortcuts`](https://github.com/portabletext/editor/tree/main/packages/plugin-markdown-shortcuts)             | Markdown-style shortcuts in the editor               | `npm i @portabletext/plugin-markdown-shortcuts`       |
   | [`@portabletext/plugin-one-line`](https://github.com/portabletext/editor/tree/main/packages/plugin-one-line)                                 | Restrict editor to a single line                     | `npm i @portabletext/plugin-one-line`                 |
   | [`@portabletext/plugin-paste-link`](https://github.com/portabletext/editor/tree/main/packages/plugin-paste-link)                             | Paste URLs as links                                  | `npm i @portabletext/plugin-paste-link`               |
   | [`@portabletext/plugin-sdk-value`](https://github.com/portabletext/editor/tree/main/packages/plugin-sdk-value)                               | Syncs editor value with the Sanity SDK               | `npm i @portabletext/plugin-sdk-value`                |
   | [`@portabletext/plugin-table`](https://github.com/portabletext/editor/tree/main/packages/plugin-table)                                       | Table editing with spreadsheet-grade selection       | `npm i @portabletext/plugin-table`                    |
   | [`@portabletext/plugin-typeahead-picker`](https://github.com/portabletext/editor/tree/main/packages/plugin-typeahead-picker)                 | Typeahead/autocomplete picker infrastructure         | `npm i @portabletext/plugin-typeahead-picker`         |
   | [`@portabletext/plugin-typography`](https://github.com/portabletext/editor/tree/main/packages/plugin-typography)                             | Smart quotes, em dashes, ellipses                    | `npm i @portabletext/plugin-typography`               |
   
   ## Convert content
   
   | Package                                                                                                                                                                  | Direction                             | Install                                                     |
   | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------- | ----------------------------------------------------------- |
   | [`@portabletext/html`](https://github.com/portabletext/editor/tree/main/packages/html)                                                                                   | HTML → Portable Text                  | `npm i @portabletext/html`                                  |
   | [`@portabletext/block-tools`](https://github.com/portabletext/editor/tree/main/packages/block-tools)                                                                     | HTML → Portable Text (Sanity wrapper) | `npm i @portabletext/block-tools`                           |
   | [`@portabletext/markdown`](https://github.com/portabletext/editor/tree/main/packages/markdown)                                                                           | Portable Text ↔ Markdown              | `npm i @portabletext/markdown`                              |
   | [`@portabletext/contentful-rich-text-to-portable-text`](https://github.com/portabletext/contentful-rich-text-to-portable-text)                                           | Contentful → Portable Text            | `npm i @portabletext/contentful-rich-text-to-portable-text` |
   | [`@emdash-cms/gutenberg-to-portable-text`](https://github.com/emdash-cms/emdash/tree/main/packages/gutenberg-to-portable-text)  | WordPress / Gutenberg → Portable Text | `npm i @emdash-cms/gutenberg-to-portable-text`              |
   | [`editorjs-to-portabletext`](https://github.com/LiamMartens/editorjs-to-portabletext)                                           | Editor.js → Portable Text             | `npm i editorjs-to-portabletext`                            |
   | [`@aceccarello/portable-text-to-lexical`](https://github.com/ACeccarello/portable-text-to-lexical)                              | Portable Text → Payload Lexical JSON  | `npm i @aceccarello/portable-text-to-lexical`               |
   
   ## Work with Portable Text data
   
   | Package                                                                                                                                               | Purpose                                                         | Install                           |
   | ----------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | --------------------------------- |
   | [`@portabletext/toolkit`](https://github.com/portabletext/toolkit)                                                                                    | `toPlainText()`, `buildMarksTree()`, `nestLists()`, type guards | `npm i @portabletext/toolkit`     |
   | [`@portabletext/types`](https://github.com/portabletext/types)                                                                                        | TypeScript type definitions for Portable Text data              | `npm i @portabletext/types`       |
   | [`@portabletext/patches`](https://github.com/portabletext/editor/tree/main/packages/patches)                                                          | Apply patches to Portable Text values                           | `npm i @portabletext/patches`     |
   | [`@portabletext-typed/types`](https://github.com/saiichihashimoto/sanity-typed/tree/main/packages/pt-types)  | Typed generics for `@portabletext/types`                        | `npm i @portabletext-typed/types` |
   
   ## Testing
   
   | Package                                                                                | Purpose                                        | Install                    |
   | -------------------------------------------------------------------------------------- | ---------------------------------------------- | -------------------------- |
   | [`@portabletext/test`](https://github.com/portabletext/editor/tree/main/packages/test) | Testing utilities for the Portable Text Editor | `npm i @portabletext/test` |
   | [`racejar`](https://github.com/portabletext/editor/tree/main/packages/racejar)         | Framework-agnostic Gherkin test driver         | `npm i racejar`            |
   
   ## Legacy packages
   
   These packages are deprecated. Use the current equivalents listed above.
   
   | Deprecated package                     | Replaced by                                                       |
   | -------------------------------------- | ----------------------------------------------------------------- |
   | `@sanity/block-content-to-react`       | [`@portabletext/react`](/rendering/react/)                        |
   | `@sanity/block-content-to-html`        | [`@portabletext/to-html`](/rendering/html/)                       |
   | `@sanity/block-content-to-hyperscript` | [`@portabletext/to-html`](/rendering/html/)                       |
   | `@sanity/block-content-to-markdown`    | [`@portabletext/markdown`](/rendering/markdown/)                  |
   | `@sanity/block-tools`                  | [`@portabletext/block-tools`](/conversion/html-to-portable-text/) |
   | `@sanity/portable-text-editor`         | [`@portabletext/editor`](/editor/getting-started/)                |
   
   For more packages, see the [Portable Text organization on GitHub](https://github.com/portabletext/).
   
   # Portable Text Editor
   
   > A headless, schema-driven block content editor for React. Officially supported, fully customizable, and built around the Portable Text specification.
   
   The Portable Text Editor (`@portabletext/editor`) is the officially supported editor for working with [Portable Text](/specification/) content. It's a headless block content editor for React: you bring the UI, the editor handles the editing.
   
   You configure the editor by declaring a [schema](/editor/concepts/portabletext/) of styles, decorators, annotations, lists, block objects, and inline objects. Rendering is yours to control through node registrations and render props on `PortableTextEditable`, and [containers](/editor/concepts/containers/) let structures like callouts, code blocks, and tables carry editable block content. Interactions are extensible through the [Behavior API](/editor/concepts/behavior/) and a growing set of [plugins](/editor/reference/plugins/). The companion [`@portabletext/toolbar`](/editor/reference/toolbar/) package gives you headless hooks for building toolbar UI.
   
   ### [Getting started](/editor/getting-started/)
   
   Install the editor, define a schema, and build your first toolbar.
   
   ### [Concepts](/editor/concepts/)
   
   How the schema, decorators, annotations, containers, and behaviors fit together.
   
   ### [Guides](/editor/guides/)
   
   Practical walkthroughs: custom blocks and inline objects, custom rendering, building toolbars, writing behaviors, and testing.
   
   ### [Reference](/editor/reference/)
   
   API documentation for the editor, behaviors, plugins, selectors, toolbar, and keyboard shortcuts.
   
   # Concepts
   
   > Core concepts behind Portable Text and the Portable Text Editor.
   
   Learn about the building blocks of Portable Text and how the editor works.
   
   ### [Portable Text Editor](/editor/concepts/portabletext/)
   
   The parts that make up the Portable Text Editor: schema, styles, decorators, annotations, lists, block objects, inline objects, and how they connect. Includes a glossary of common terms.
   
   ### [Rendering](/editor/concepts/rendering/)
   
   How node registrations own the editor's markup, and how the engine dispatches between global, positional, and legacy renders.
   
   ### [Containers](/editor/concepts/containers/)
   
   Nest editable block content inside custom structures like callouts, code blocks, and tables, while the value stays plain Portable Text.
   
   ### [Behaviors](/editor/concepts/behavior/)
   
   How behaviors work in the editor. Events, guards, and actions: the pattern that lets you customize how users interact with the editor.
   
   ### [Traversal](/editor/concepts/traversal/)
   
   Pure functions that answer questions about the editor's value tree, given a path and a snapshot.
   
   ### [Clipboard](/editor/concepts/clipboard/)
   
   How copy and paste run through behaviors: the events in each direction and how several behaviors compose around the same clipboard.
   
   # Behaviors
   
   > How behaviors intercept and transform editor events to customize the Portable Text Editor's editing logic.
   
   import {CardGrid, LinkCard} from '@astrojs/starlight/components'
   
   Behaviors allow you to customize how users interact with the editor by hooking into events during the editing experience.
   
   All behaviors follow this process:
   
   1. Listen for an **event**.
   2. Use a **guard** to decide if they should run or not.
   3. Trigger a set of **actions** to perform on the editor.
   
   This pattern is influenced by [Statecharts](https://statecharts.dev/).
   
   Behaviors are defined with the `defineBehavior` helper. Here's an example event from the [behavior guide](/editor/guides/create-behavior/):
   
   ```tsx
   defineBehavior({
     on: 'insert.text',
     guard: ({snapshot, event}) => event.text === 'a',
     actions: [
       ({snapshot, event}) => [
         {type: 'execute', event: {type: 'insert.text', text: 'A'}},
       ],
     ],
   })
   ```
   
   Revisiting the three step process above:
   
   - `on` listens for the event.
   - `guard` handles the conditional.
   - `actions` sends, or invokes, the desired actions.
   
   ## Events
   
   Whenever you enter text into the editor, activate a toolbar button, or anything else happens in the editor it sends an event.
   
   There are three categories of Behavior Events:
   
   - Native Events: Events that come from the browser or device directly.
   - Synthetic Events: Editor-specific events that directly modify the editor state.
   - Custom Events: Events that you create yourself.
   
   
   
   The Behavior API uses events to trigger actions by listening for a specific event.
   
   :::note
   All events except native events can be executed or raised from within behaviors, but only synthetic events are guaranteed to resolve into a state change.
   :::
   
   ## Guards
   
   A guard is a condition that helps the behavior determine if it should perform the actions.
   
   The `guard` key expects a response or `false`. The example above shows a simple _truthy_ guard. Here it is again:
   
   ```js
   guard: ({snapshot, event}) => event.text === 'a'
   ```
   
   Guards can also return parameters that you can access when firing an action.
   
   ```js
   guard: ({snapshot, event}) => {
       if (event.text === 'a') {
           return {
               secret: 'secret text'
           }
       }
       return false
   },
   actions: [
       ({snapshot, event}, {secret}) => [
           /* ... */
       ]
   ]
   ```
   
   Passing parameters allows you to reuse conditional behavior, such as selecting part of a string, without rewriting the logic.
   
   Guards are optional. This means it's possible to create an unconditional behavior that always runs when an event occurs. The "soft return" behavior build into the PTE is one example:
   
   ```js
   const softReturn = defineBehavior({
     on: 'insert.soft break',
     actions: [() => [execute({type: 'insert.text', text: '\n'})]],
   })
   ```
   
   This behavior listens for soft break events and uses the `insert.text` action to insert a `\n` instead to prevent splitting text blocks with `Shift+Enter`. These unconditional behaviors are rare and you'll mostly encounter conditional behaviors.
   
   ## Actions
   
   Actions make things happen in the editor. This is where you change the standard behavior by modifying actions before they occur or by circumventing them completely. You've seen actions in some of the guard examples above.
   
   The `actions` key expects an array of behavior action sets. As with guards, you have access to the `event` and `snapshot`.
   
   So far we've only seen examples that invoke a single action, but you can send multiple actions or sets of actions from a single event.
   
   ### Raise events within actions
   
   To send an event back into the editor, use the `raise` action type or the `raise` helper. This is useful for chaining behaviors and default events.
   
   ```tsx
   // Approach A: With the type set to 'raise'
   // Approach B: With the raise helper
   import {defineBehavior, raise} from '@portabletext/editor/behaviors'
   
   const raisedUppercaseA = defineBehavior({
     on: 'insert.text',
     guard: ({snapshot, event}) => event.text === 'a',
     actions: [
       ({snapshot, event}) => [
         {type: 'raise', event: {type: 'insert.text', text: 'A'}},
       ],
     ],
   })
   
   const raisedUppercaseA = defineBehavior({
     on: 'insert.text',
     guard: ({snapshot, event}) => event.text === 'a',
     actions: [({snapshot, event}) => [raise({type: 'insert.text', text: 'A'})]],
   })
   ```
   
   ### Claiming the native event
   
   When a Behavior's guard matches an event that carries a native event (a `keyboard.keydown`, for example), the Behavior claims it: the editor calls `preventDefault()` and the browser's default action is suppressed. The action sets can revise that claim. Every action set that returns actions casts a vote, and the last vote wins:
   
   | The action set             | Native default              |
   | -------------------------- | --------------------------- |
   | contains `raise`/`execute` | prevented                   |
   | contains only `forward`    | passes down the chain       |
   | contains only `effect`s    | prevented                   |
   | returns nothing, or throws | keeps the previous decision |
   
   Within one set, `raise` and `execute` outrank `forward`: a set that both mutates and forwards still prevents the default.
   
   `forward` does not mean "let the browser act". It means "no opinion at this level": the event moves on to the next Behavior in the chain, which makes its own decision, and the browser's default only survives when no Behavior along the chain claims the event.
   
   Multiple action sets are also an undo boundary: each set after the first starts a new undo step. [`@portabletext/plugin-input-rule`](https://github.com/portabletext/editor/tree/main/packages/plugin-input-rule) uses this to let the typed text land as its own undo step before a second set transforms it, so undo peels the transformation off first.
   
   ## Selectors
   
   Selectors are pure functions that derive state from the editor snapshot (`snapshot` in the examples). A collection of selectors is included with the core library.
   
   ```tsx
   // import all selectors
   import * as selectors from '@portabletext/editor/selectors'
   // or individual ones
   import {getFocusSpan, getFocusTextBlock} from '@portabletext/editor/selectors'
   ```
   
   The core selectors are useful helper functions for checking conditions of the editor, finding selected text, and more. You can manually do anything a selector can do by parsing the editor snapshot.
   
   ## Behavior examples
   
   Browse the existing behaviors, or check out the Behavior Recipes documentation for examples of real-world behaviors.
   
   
     
     
   
   
   # Clipboard
   
   > How the editor turns a selection into clipboard data and clipboard data back into content, and how behaviors compose when several of them care about the same clipboard.
   
   import {LinkCard} from '@astrojs/starlight/components'
   
   Copying and pasting run entirely through [behaviors](/editor/concepts/behavior/). Both directions are a small pipeline of events, and every step is one your own behaviors can take over.
   
   ## Copy
   
   A copy raises one `serialize` event, which fans out into five `serialize.data` events, one per format, in this order:
   
   1. `application/x-portable-text`
   2. `application/json`
   3. `text/markdown`
   4. `text/html`
   5. `text/plain`
   
   Each one is handled independently and writes its result into the same clipboard, so a single copy produces up to five representations and the receiving application picks the richest one it understands. A cut does the same, then raises `delete`. Neither does anything when the selection is collapsed.
   
   :::note
   Taking over one format leaves the other four untouched. Your HTML lands on the clipboard next to the editor's Portable Text, Markdown, and plain text.
   :::
   
   If a format fails to serialize, the editor logs a warning and moves on. There is no second attempt at that format, so the clipboard is left without it.
   
   ## Paste
   
   A paste raises `deserialize`, which looks through the clipboard in the same order of preference and picks the first format that is present. That format becomes a `deserialize.data` event.
   
   On success the resulting blocks are fitted to the paste destination and inserted. On failure the editor tries the next format present on the clipboard, so a failed HTML paste can still fall back to plain text.
   
   ## One handler per format
   
   Within a single `serialize.data` or `deserialize.data` event, the first behavior whose guard returns a truthy value handles it, and no later behavior sees that event.
   
   That makes the guard the contract. A guard that returns `false` declines cleanly and costs nothing, so a behavior should claim a format only in the situation it actually cares about:
   
   ```tsx
   defineBehavior({
     on: 'serialize.data',
     guard: ({snapshot, event}) => {
       if (event.mimeType !== 'text/plain') {
         return false
       }
   
       const rectangle = getTableRectangle(snapshot)
   
       if (!rectangle) {
         return false
       }
   
       return {
         type: 'serialization.success' as const,
         mimeType: 'text/plain' as const,
         data: toTabSeparatedValues(rectangle),
         originEvent: event.originEvent.type,
       }
     },
     actions: [
       ({event}, serialization) => [
         raise({...serialization, originEvent: event.originEvent}),
       ],
     ],
   })
   ```
   
   The guard narrows twice, on the format and on the situation, so the behavior owns plain-text copy inside a table and leaves every other selection alone. A guard that checked only `event.mimeType` would own plain-text copy for the whole editor, including selections that have nothing to do with tables.
   
   The guard does the work and returns the `serialization.success` event, which the action raises; the editor writes the data to the clipboard. The paste direction mirrors this: raise `deserialization.success` with the blocks you produced, and the editor fits and inserts them. Raising the matching `failure` event hands the format back, and the editor moves on as if nothing had claimed it.
   
   ## Ordering
   
   Behaviors you register always run before the editor's own. Among your own, the order is the order they were registered in: a `BehaviorPlugin` registers its `behaviors` array top to bottom, and separate plugins register in mount order.
   
   There is no way to declare that one behavior should run before or after another. If two behaviors claim the same format, the earlier registration wins, silently. When that matters, keep both guards narrow enough that only one of them can match.
   
   A behavior can also decline to end the event: `forward` passes it to the behaviors that come after, which is what lets several behaviors each inspect the same paste.
   
   
   
   ## The callback escape hatch
   
   `onCopy`, `onCut`, and `onPaste` on `PortableTextEditable` run in front of this pipeline, and they do not all fall through the same way.
   
   `onCopy` and `onCut` replace it. Providing either one means `clipboard.copy` and `clipboard.cut` are never sent, so no clipboard behavior runs and none of the five formats are written, whatever the callback returns. Adding an `onCopy` to log something removes the editor's own copy along with it.
   
   `onPaste` is the forgiving one: return nothing, or a result without blocks to insert, and the paste continues into `clipboard.paste` and the normal deserialization pipeline.
   
   Anything that can be a behavior should be one. Behaviors compose; callbacks replace.
   
   # Containers
   
   > Nest editable block content inside custom structures like callouts, code blocks, and tables, while the value stays plain Portable Text.
   
   A container is a block object that holds editable block content: one of its fields is an array whose members include text blocks (or further containers). Containers are how callouts carry editable paragraphs, code blocks carry editable lines, and tables carry editable cells, without leaving Portable Text.
   
   ## Containers are plain Portable Text
   
   There is no editor-specific data format. A container in the value is an ordinary object block whose field happens to hold more blocks:
   
   ```json
   {
     "_type": "callout",
     "_key": "a1b2c3",
     "tone": "note",
     "content": [
       {
         "_type": "block",
         "_key": "d4e5f6",
         "children": [
           {
             "_type": "span",
             "_key": "g7h8i9",
             "text": "Editable text inside the callout.",
             "marks": []
           }
         ],
         "markDefs": [],
         "style": "normal"
       }
     ]
   }
   ```
   
   Serializers and queries see nested Portable Text, nothing more. What makes it a _container_ is that the editor knows to render the `content` array as an editable region instead of treating `callout` as an opaque block object.
   
   ## Declare the schema
   
   A container starts in the schema: a block object with an array field whose `of` includes a `{type: 'block'}` member.
   
   ```ts
   import {defineSchema} from '@portabletext/editor'
   
   const schemaDefinition = defineSchema({
     decorators: [{name: 'strong'}, {name: 'em'}],
     blockObjects: [
       {
         name: 'callout',
         fields: [
           {name: 'tone', type: 'string'},
           {name: 'content', type: 'array', of: [{type: 'block'}]},
         ],
       },
     ],
   })
   ```
   
   The nested `{type: 'block'}` member declares the _sub-schema_ for text inside the container. Each of `styles`, `decorators`, `annotations`, `lists`, and `inlineObjects` resolves independently:
   
   - **Declared** on the nested block, it overrides for that property.
   - **Declared empty** (`decorators: []`), it forbids that property inside the container.
   - **Absent**, it inherits from the nearest enclosing container that declares one, falling back to the root schema.
   
   This is how a code block restricts its lines to a `code` style with no decorators while the rest of the document keeps its full schema. The complete resolution rules live in the [`@portabletext/schema` README](https://github.com/portabletext/editor/tree/main/packages/schema#containers-and-sub-schemas).
   
   ## Register the container
   
   The schema declares what a container _allows_; a registration tells the editor to _render_ it as one. Create the registration with `defineContainer` and mount it with `NodePlugin`:
   
   ```tsx
   import {
     defineContainer,
     EditorProvider,
     PortableTextEditable,
   } from '@portabletext/editor'
   import {NodePlugin} from '@portabletext/editor/plugins'
   
   // Module scope: a new array identity re-registers the nodes on every render.
   const nodes = [
     defineContainer({
       type: 'callout',
       arrayField: 'content',
       render: ({attributes, children, selected}) => (
         
       ),
     }),
   ]
   
   function App() {
     return (
       
         
         
       
     )
   }
   ```
   
   The render contract:
   
   - Spread `attributes` onto your outer element so the engine can track the node.
   - Render `children` where the editable content goes; the engine fills it with the container's blocks.
   - Mark any chrome that is not editable content (icons, buttons, drag handles) with `contentEditable={false}`.
   - `selected` is `true` when the container is the current selection; use it for selection styling, as `data-selected` above does.
   - `readOnly` is `true` when the editor is read-only; check it before making chrome interactive, for example `draggable={!readOnly}` on a drag handle.
   - `renderDefault` renders the engine's minimal wrapper; call it to fall back or wrap the default.
   
   Omitting `render` falls through to the engine default, so a registration can exist purely to mark the field as editable.
   
   Registering a container also normalizes the value: existing blocks of the registered type are seeded down to a cursor-ready structure, so a bare `callout` block gains a `content` array holding an empty text block.
   
   A container registration that doesn't match the schema is skipped with a `console.warn` naming the actual mismatch: an unknown type, a missing field, a field that isn't an array, or an array of primitives only. The editor keeps working; the type renders as an ordinary block object until the registration and schema agree.
   
   Containers only exist as registrations, there's no legacy render prop to migrate from. If the rest of your editor still renders through the deprecated props, the [migration guide](/editor/guides/migrate-render-props/) covers moving those to registrations too.
   
   ## Editing follows the sub-schema
   
   Inside a container, the editor resolves the schema at the caret, not the top-level schema. A code block whose sub-schema declares no decorators won't accept bold, whether from the keyboard, the toolbar, or a paste.
   
   Schema-aware plugins get the same gating for free: `MarkdownShortcutsPlugin` passes each callback a `context` object carrying the schema at the caret as `context.schema`. Take a schema whose code block forbids decorators, and a Markdown shortcut configured by schema lookup:
   
   ```tsx
   import {MarkdownShortcutsPlugin} from '@portabletext/plugin-markdown-shortcuts'
   
   const schemaDefinition = defineSchema({
     decorators: [{name: 'strong'}, {name: 'em'}],
     blockObjects: [
       {
         name: 'code-block',
         fields: [
           {
             name: 'lines',
             type: 'array',
             // The code line allows a `code` style and no decorators.
             of: [{type: 'block', styles: [{name: 'code'}], decorators: []}],
           },
         ],
       },
     ],
   })
   ```
   
   ```tsx
   
       context.schema.decorators.find((decorator) => decorator.name === 'strong')
         ?.name
     }
   />
   ```
   
   The callback runs against the schema at the caret. In a regular paragraph the lookup finds `strong`, so typing `**bold**` applies the decorator. Inside a code-block line the sub-schema declares `decorators: []`, the lookup returns `undefined`, and the shortcut skips itself. Nothing was configured per container: **the schema is the feature flag**, and the lookup is what reads it.
   
   Your own code can resolve the schema at any position with `getPathSubSchema` from the [traversal API](/editor/concepts/traversal/).
   
   ## Narrow rendering with `of`
   
   A registration's markup ownership, and how the engine dispatches between global and positional renders, is one model shared by every kind of registration. [Rendering](/editor/concepts/rendering/) covers that model; this page covers the part specific to containers: an `of` array scopes registrations to positions inside one.
   
   A container's `of` entry beats the global registration for the same type, one level down, in its immediate children. A code block can render its lines without paragraph spacing, or a callout can render its paragraphs tighter than the rest of the document:
   
   ```tsx
   import {defineContainer, defineTextBlock} from '@portabletext/editor'
   
   const nodes = [
     // Paragraphs everywhere: `block` is the text block type at every
     // nesting level.
     defineTextBlock({
       type: 'block',
       render: ({attributes, children, node}) => (
         
   
           {children}
         
       ),
     }),
     defineContainer({
       type: 'callout',
       arrayField: 'content',
       render: ({attributes, children}) => (
         
       ),
       // Inside the callout, the same `block` type renders tighter.
       of: [
         defineTextBlock({
           type: 'block',
           render: ({attributes, children}) => (
             
   
               {children}
             
           ),
         }),
       ],
     }),
   ]
   ```
   
   Paragraphs render through the first `defineTextBlock` everywhere else and through the tighter one inside the callout.
   
   Any text block's `of` can scope marks one level deeper, into `defineDecorator` and `defineAnnotation` entries, whether or not that text block sits inside a container; it lives on this page because `of` scoping is this page's subject. Register the same decorator globally and positionally to see the scoping:
   
   ```tsx
   defineDecorator({
     type: 'strong',
     render: ({children}) => {children},
   })
   
   defineTextBlock({
     type: 'block',
     render: ({attributes, children}) => (
       
   
         {children}
       
     ),
     of: [
       defineDecorator({
         type: 'strong',
         render: ({children}) => {children},
       }),
     ],
   })
   ```
   
   With both registered, `strong` renders as `` inside these text blocks and as `` everywhere else. A global `defineDecorator` or `defineAnnotation` renders inside every text block; a positional entry, registered through a text block's `of`, only renders inside that scope, everywhere else the global registration still applies. Remove the positional entry's `render` and `strong` renders as `` everywhere: an `of` entry without its own `render` defers to the global registration, or, absent one, whatever would have rendered anyway. That is a different fall-through than a top-level registration: a top-level registration without `render` falls to the engine default, while an `of` entry without `render` falls to the global registration first. See [Dispatch precedence](/editor/concepts/rendering/#dispatch-precedence) for how positional, global, and the `'*'` catch-all rank against each other.
   
   ## Nest containers
   
   Containers nest through the `of` array, which scopes registrations to positions inside the parent. A table is three containers deep:
   
   ```tsx
   defineContainer({
     type: 'table',
     arrayField: 'rows',
     render: ({attributes, children}) => 

   {children}, of: [ defineContainer({ type: 'row', arrayField: 'cells', render: ({attributes, children}) => {children}, of: [ defineContainer({ type: 'cell', arrayField: 'content', render: ({attributes, children}) => ( {children} ), }), ], }), ], }) ``` Nesting isn't limited to containers: `of` accepts any block-level registration, `defineContainer`, `defineTextBlock`, and `defineBlockObject`, so anything can render differently inside a container than in the rest of the document. A code block can render each line without paragraph spacing, and a callout can render images compactly. Inline kinds scope the same way one level down, through a text block's own `of`, which takes `defineSpan` and `defineInlineObject` registrations (a `code-span` inside a code block, for example). Scope is one level deep: an `of` override applies to the container's immediate children only, and anything nested deeper falls through to the global registrations. An image inside a table cell sees the cell's `of`, not the table's. ## A complete example Everything above composes in one `nodes` array. This editor renders text blocks and images everywhere, and a callout that renders the same `image` type compactly inside itself: ```tsx import { defineBlockObject, defineContainer, defineSchema, defineTextBlock, EditorProvider, PortableTextEditable, } from '@portabletext/editor' import {NodePlugin} from '@portabletext/editor/plugins' const schemaDefinition = defineSchema({ decorators: [{name: 'strong'}, {name: 'em'}], styles: [{name: 'normal'}, {name: 'h2'}], blockObjects: [ {name: 'image', fields: [{name: 'src', type: 'string'}]}, { name: 'callout', fields: [ {name: 'tone', type: 'string'}, { name: 'content', type: 'array', // The callout holds text blocks and images. of: [{type: 'block'}, {type: 'image'}], }, ], }, ], }) const nodes = [ // Text blocks, at the root and inside the callout alike. defineTextBlock({ type: 'block', render: ({attributes, children, node}) => node.style === 'h2' ? (

   {children}

   ) : (

   {children}

   ), }), // Images at the root: full width. defineBlockObject({ type: 'image', render: (props) => typeof props.node.src === 'string' ? (

   

   {props.children}

   ) : ( props.renderDefault(props) ), }), // The callout, with a positional override: the same `image` type // renders compactly inside it. defineContainer({ type: 'callout', arrayField: 'content', render: ({attributes, children}) => ( ), of: [ defineBlockObject({ type: 'image', render: (props) => typeof props.node.src === 'string' ? ( {props.children} ) : ( props.renderDefault(props) ), }), ], }), ] function App() { return ( ) } ``` An `image` block at the document root renders through the global registration, full width. The same `_type: 'image'` inside the callout's `content` hits the positional override first and renders compact. The text block registration needs no positional counterpart: `type: 'block'` already covers both scopes. Both registrations call `renderDefault` when `node.src` isn't a string; see [`renderDefault`](/editor/concepts/rendering/#renderdefault) on the Rendering page for what that falls back to. Decorators and annotations scope the same way, one level deeper: a `defineDecorator` or `defineAnnotation` entry inside the callout's text block `of` (as shown under [Narrow rendering with `of`](#narrow-rendering-with-of)) makes an annotation like `link` render differently only inside the callout, and the text block entry needs no `render` of its own to carry it. ## Read the registered containers `snapshot.context.containers` exposes what's currently registered, keyed by the container's bare block-object `_type` (`callout`, `table`, and so on). Each entry carries `type` and the `field` that holds the container's editable children: the field's name, plus the schema's `of` list of allowed child types. If the registration declared a nested `of`, the entry also carries that array, holding further container entries or positional entries (span, block object, inline object overrides). Only top-level registrations appear as flat map entries: a type registered solely inside a parent's `of` shows up nested there, not as its own entry. Read it with a [selector](/editor/reference/selectors/) like any other part of the snapshot: ```ts import type {EditorSelector} from '@portabletext/editor' const isCalloutRegistered: EditorSelector = (snapshot) => snapshot.context.containers.has('callout') ``` ## Containers in practice [`@portabletext/plugin-table`](https://github.com/portabletext/editor/tree/main/packages/plugin-table) is built entirely on this API: three nested containers plus behaviors and UI. It's both a ready-made table editor and the reference for what containers can carry. The [Portable Text Playground](https://playground.portabletext.org/) ships container examples you can try, callouts, code blocks, fact boxes, and tables. # Schema and concepts > Learn more about the parts of Portable Text and the Editor, including common terms and concepts. import {CardGrid, LinkCard} from '@astrojs/starlight/components' The Portable Text Editor (PTE) is the officially supported editor for working with [Portable Text](https://github.com/portabletext/portabletext). Customize it to fit the needs of your authors and content team using a schema, ## Schema The PTE accepts a schema that describes the kinds of content it can implement. This is used throughout the editor to configure parts of the interface and aspects of the Portable Text output. {/* */} A schema consists of styles, decorators, annotations, block objects, inline objects, and lists. Here is an example schema from the [getting started guide](/editor/getting-started/): ```js { decorators: [{name: 'strong'}, {name: 'em'}, {name: 'underline'}], annotations: [{name: 'link', fields: [{name: 'href', type: 'string'}]}], styles: [ {name: 'normal'}, {name: 'h1'}, {name: 'h2'}, {name: 'h3'}, {name: 'blockquote'}, ], lists: [{name: 'bullet'}, {name: 'number'}], inlineObjects: [{name: 'stock-ticker'}], blockObjects: [{name: 'image'}], } ``` You'll likely see connections to the elements found in rich text editors, along with some extras. ### Styles Styles are a way to identify text blocks in Portable Text and signal to the editor how to classify the block. They don't add any other data to the text. Examples include: - Headings (H1, H2, H3, etc.) - Block quotes - Normal paragraphs Convention uses HTML naming for these styles, but it is not required and has no direct impact on the style of the content. ### Decorators Decorators are inline text with added meaning. Examples include: - Bold text - Emphasis or italicized text - Underlined text Decorators are a type of [Portable Text mark](https://github.com/portabletext/portabletext?tab=readme-ov-file#markdefs-array) that adds additional meaning to existing text. ### Annotations Like decorators, annotations are inline text with added meaning. Annotations are more complex than decorators, and often include additional functionality. Examples include: - Links - References Annotations are a type of [Portable Text mark](https://github.com/portabletext/portabletext?tab=readme-ov-file#markdefs-array) that adds additional meaning to existing text. ### Lists Lists are groups of text blocks. They take into account the position each block has in a group. Examples include: - Bullet lists - Numbered lists ### Block objects Block objects sit alongside text. For example, an image block may sit between a heading and a paragraph. They can hold any kind of data. Some examples include: - Images - Code blocks - Videos - Portable Text editors ### Inline objects Inline objects, much like block objects, can hold any kind of data. Instead of existing alongside text, inline objects exist inside text blocks. Examples include: - Footnote indicators - Non-text emoji substitutes Inline objects differ from annotations and decorators because they aren't wrapping existing text. Instead, they are self contained. ## Rendering content in and out of the editor The schema serves as a foundation for how the PTE renders the text. On it's own, passing just a schema to the editor only annotates or _describes_ text, but it won't change the way it renders. To affect the way text renders in the editor, pass custom renderers to the editor. To affect the way text renders once it's stored as Portable Text, use an existing serializer or write your own. ## The toolbar A schema describes the type of content an author can create in the editor, but without a toolbar there's no way to assign the schema to each piece of text. The toolbar allows you to define the graphical user interface for creating rich text in the PTE. The most common way to do this is by using the schema as a foundation. ## Behaviors Behaviors change how users interact with the editor. They handle everything from direct text input, to changing paste behavior, to allowing you to write custom shortcuts. The editor comes with many behaviors by default, but you can also create your own. ## Common terms The following terms come up when dealing with Portable Text and the editor. Some overlap with the schema above, while others are more general. - Block: Broken down into standard and custom blocks. Standard blocks are sections of text, like paragraphs and headings. Custom blocks are block objects like images, code blocks, embeds, etc. - Span: A standard way to express inline text within a block. - Children: An array of spans or other inline types contained within a block. - Marks: `markDefs` exist in the Portable Text format and connect spans with annotations and decorators. A span can have multiple marks associated with it. Such as text that is bold and italic. - List items: Blocks can be labeled as list items to resemble lists. - Selection: The range of text selected, or the cursor location in the editor at a given time. - Selection collapsed: A collapsed selection is one where nothing is selected and is instead a single point (cursor). - Anchor: Where the user began the selection. - Focus: Where the user ends the selection. - Offset: A distance, in characters, from the selection. - Path: A representation of the location of elements. Used in the behavior API to target or select specific blocks, spans, or text. - Node: A representation of an element. Contains details about it's type and content. # Rendering > How node registrations own the editor's markup, and how the engine dispatches between positional, global, and default renders. The editor renders every kind of Portable Text node, text blocks, spans, decorators, annotations, block objects, and inline objects, through the same mechanism: a node registration. This page covers the model that every registration shares. [Containers](/editor/concepts/containers/) covers the container-specific factory and how `of` scopes a registration to positions inside one. ## Markup ownership Every registration owns its markup: your `render` gets `children` to render where the editable content goes, and the engine adds nothing around what you return (with one exception: annotations compose inside an engine-owned anchor span). Every kind except decorators and annotations also receives `attributes` to spread on the outer element, so the engine can track the node; decorators and annotations wrap inline content rather than owning an element the engine tracks, so their `render` receives no `attributes`. ```tsx import {defineTextBlock} from '@portabletext/editor' const paragraph = defineTextBlock({ type: 'block', render: ({attributes, children, node}) => (

   {children}

   ), }) ``` Spread `attributes` onto your outer element when your registration receives one, and render `children` where the editable content goes. That's the whole interface: no hidden classes, no wrapper the engine adds behind your back. ## Register a node The schema declares what the editor allows; a registration only renders what the schema already permits. `defineDecorator({type: 'strong'})` and `defineAnnotation({type: 'link'})` below render because the schema declares a `strong` decorator and a `link` annotation: ```tsx import {defineSchema} from '@portabletext/editor' const schemaDefinition = defineSchema({ decorators: [{name: 'strong'}], annotations: [{name: 'link', fields: [{name: 'href', type: 'string'}]}], }) ``` Each node kind has a factory: `defineTextBlock`, `defineBlockObject`, `defineInlineObject`, `defineSpan`, `defineDecorator`, `defineAnnotation`, and `defineContainer` (see [Containers](/editor/concepts/containers/) for that one). Every factory returns a plain registration object; mount them together through one `NodePlugin`: ```tsx import { defineAnnotation, defineDecorator, defineTextBlock, EditorProvider, PortableTextEditable, } from '@portabletext/editor' import {NodePlugin} from '@portabletext/editor/plugins' // Module scope: a new array identity re-registers the nodes on every render. const nodes = [ defineTextBlock({ type: 'block', render: ({attributes, children}) =>

   {children}

   , }), defineDecorator({ type: 'strong', render: ({children}) => {children}, }), defineAnnotation({ type: 'link', render: ({annotation, children}) => typeof annotation.href === 'string' ? ( {children} ) : ( children ), }), ] function App() { return ( ) } ``` `annotation` is the markDef object from the block's `markDefs`: `{_key, _type, ...fields}`. Its fields type as `unknown` because they depend on the schema, so narrow with `typeof` before use; the fallback renders `children` untouched, matching the engine default. Each render callback is a plain function call, not a component: when a render needs hooks, return a component instead, `render: (props) => `. Keep `nodes` at module scope, as above: a fresh array identity on every render makes `NodePlugin` unregister and re-register every keystroke. ## Subtree ownership A block-level registration (a text block, block object, or container) owns everything rendered inside it, its rendering subtree. Unregistered node types inside it fall back to the engine defaults: a registered text block holding an unregistered inline object still renders that inline object through the engine's default wrapper, not through markup you control. Register a node type when you need to own its markup, wherever it appears: ```tsx const nodes = [ defineTextBlock({ type: 'block', render: ({attributes, children}) =>

   {children}

   , }), defineInlineObject({ type: 'stock-ticker', render: (props) => typeof props.node.symbol === 'string' ? ( {props.children} {props.node.symbol} ) : ( props.renderDefault(props) ), }), ] ``` ## Dispatch precedence At a given position, a positional registration (one scoped through a container or text block's own `of`, see [Containers](/editor/concepts/containers/)) beats a global registration, which beats the engine default. Within a level, an exact `type` match beats a `'*'` catch-all: ```tsx const nodes = [ // `strong` hits the exact match... defineDecorator({ type: 'strong', render: ({children}) => {children}, }), // ...every other decorator hits the catch-all. defineDecorator({ type: '*', render: ({decorator, children}) => ( {children} ), }), ] ``` [Narrow rendering with `of`](/editor/concepts/containers/#narrow-rendering-with-of) covers how far a positional entry's scope reaches and what it falls back to when it omits `render`. ## `renderDefault` Every render receives `renderDefault`, a function that renders the engine's minimal wrapper for that position. Call it to fall back, or to wrap the default instead of replacing it: ```tsx render: (props) => props.renderDefault(props) ``` Its most common use is the fallback branch of a field-presence check: a document can carry a partially filled value, and the engine default beats rendering nothing: ```tsx defineBlockObject({ type: 'image', render: (props) => typeof props.node.src === 'string' ? (

   

   {props.children}

   ) : ( props.renderDefault(props) ), }) ``` The `contentEditable={false}`/`draggable` wrapper is the block-object render contract; the [custom blocks guide](/editor/guides/custom-blocks/) covers it in full. `renderDefault` is the engine default at any position: it never chains back to a global registration's render, even from inside a positional one. PTE has one user layer plus positional overrides, and the engine default is the canonical fallback everywhere. For block-level, span, and inline-object registrations the default is a minimal wrapper; for decorators the default is identity, the engine applies no decorator markup of its own. For annotations the default is identity too, but every known annotation renders inside an engine-owned anchor span the engine adds regardless of which render fires. ## Plugins for lists and drag-and-drop Two rendering concerns ship as plugins instead of registration props: - List numbering: your text-block render reads `node.listItem` and `node.level` for list markup, and [`@portabletext/plugin-list-index`](https://github.com/portabletext/editor/tree/main/packages/plugin-list-index) computes the 1-based list index at any path, correct across nesting, remote edits, and non-list blocks interrupting a list. - Drop indicators: pointer-driven UI rendered by you. [`@portabletext/plugin-dnd`](https://github.com/portabletext/editor/tree/main/packages/plugin-dnd) tracks the drop position from the editor's public `drag.*` events. Both plugins follow the same pattern: a provider inside `EditorProvider`, and a hook read from a component your `render` returns, not inline in the `render` callback, since hooks can't run there: ```tsx import type {TextBlockRenderProps} from '@portabletext/editor' import {useListIndex} from '@portabletext/plugin-list-index' const nodes = [ defineTextBlock({ type: 'block', render: (props) => , }), ] function TextBlock(props: TextBlockRenderProps) { const listIndex = useListIndex(props.path) return (

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

   ) } ``` `useListIndex` reads from `ListIndexProvider`, mounted inside `EditorProvider`. Each plugin's README carries the full recipe, including a reference `DropIndicator` implementation. :::note[Migrating from the render props?] If your editor still renders through the render props from the previous major, removed in this one (`renderBlock`, `renderChild`, `renderStyle`, `renderListItem`, `renderDecorator`, `renderAnnotation`), each has a registration equivalent, and the engine dispatches per `_type`, so you can migrate one kind at a time. The [migration guide](/editor/guides/migrate-render-props/) walks through it. ::: # Traversal > Pure functions that answer questions about the editor's value tree, given a path and a snapshot. import {LinkCard} from '@astrojs/starlight/components' The traversal API is a set of pure functions that answer questions about the editor's value tree: what node lives at this path, what is its parent, does this range intersect that selection. They take a snapshot and a path (or two) and return an answer, with no side effects and no dependency on the current selection. ```ts import * as traversal from '@portabletext/editor/traversal' ``` ## Snapshots The lookups and family walkers below take an `EditorSnapshot` as their first argument. You already hold one in the places where you'd reach for traversal: a selector receives it as its only argument, a behavior guard or action receives it as `snapshot`, and `editor.getSnapshot()` returns one at event time, for example inside a plugin's `useEffect`. A few functions work from narrower inputs instead: `pathContains` compares two paths with no snapshot at all, and `getUnionSchema` takes a schema and a container map, both readable off `snapshot.context`. ```ts import type {EditorSelector} from '@portabletext/editor' import * as traversal from '@portabletext/editor/traversal' const hasFooBlock: EditorSelector = (snapshot) => traversal.hasNode(snapshot, [{_key: 'foo'}]) ``` There's no public way to build a snapshot yourself. Take the one your call site already has. ## Paths A path is a sequence of keyed segments and field names: `{_key: 'foo'}` addresses a node by its key, and a string like `'children'` names the array field to descend into next. Nested containers chain the same shape one level deeper. Reaching a cell in a table looks like: ```ts const cellPath = [{_key: 't1'}, 'rows', {_key: 'r1'}, 'cells', {_key: 'c1'}] ``` `getNode` and the other lookups also accept numeric indexes in place of a keyed segment, but the path on the returned result is always fully keyed: an index like `0` resolves to whatever node currently sits there, and the answer comes back addressed by that node's `_key`, not by the index you passed in. ## Entries A lookup like `getNode` or `getParent` doesn't return the node on its own. It returns the node together with its canonical keyed path, fully keyed even when the path you passed in used an index. That path is exactly what you'd pass into the next call, so results chain: get a node, get its parent, get the parent's first child, without re-deriving a path by hand at each step. ## Finding and walking nodes `getNode` resolves any path to its node and canonical path, or `undefined` if nothing lives there. `hasNode` asks the same question as a boolean. Typed lookups narrow to a specific shape and return `undefined` if the node at the path isn't that shape: - `getBlock` - a block: a text block or an object node at block position - `getTextBlock` - a text block specifically - `getSpan` - a span - `getAnnotation` - resolves an annotation reference. Annotations live in `markDefs` on a text block, alongside `children` rather than inside it, so `getNode` can't reach one; use `getAnnotation` for a path like `[..., {_key: block}, 'markDefs', {_key: annotation}]`. - `getContainer` - the registered editable container at a path, or `undefined` if the node there isn't one `getText` sits alongside these: it returns the concatenated text content of the node at a path, walking its descendants for a span's text when the node itself isn't a span. Family walkers move relative to a path: - `getParent` - the enclosing text block or object node - `getAncestor` / `getAncestors` - one matching ancestor, or every ancestor from nearest to furthest - `getChildren` / `getFirstChild` / `getLastChild` - a node's children - `getSibling` - the next or previous sibling, optionally the first one matching a predicate - `getEnclosingBlock` - the node at the path if it's already a block, otherwise the nearest block ancestor - `getLeaf` - walks from a path toward the `start` or `end` edge and returns the deepest leaf it reaches ## Narrowing `isBlock` and `isInline` classify a path by its parent: a node is a block unless its parent is a text block, and inline is the inverse. Children of a container are blocks within that container, the same way top-level nodes are blocks within the document. `isObject` classifies a node value directly and is true for anything that isn't a text block or span. `isLeafObject` takes the node's path as well as the node, and narrows further to an object with no editable children, an object that isn't a container. Reach for a typed lookup like `getSpan` or `getTextBlock` when the node also has to exist: it does the existence check and the narrowing in one call. Reach for a predicate like `isBlock` when you already have the node and only need the classification. ## Points and ranges `comparePoints` orders two `EditorSelectionPoint`s by document position, returning `-1`, `0`, or `1`. `pathContains` asks whether one path's subtree contains another, comparing path shape alone with no snapshot and no notion of selection. `rangeIntersects` asks whether an `EditorSelection` overlaps a path, a point, or another selection. A behavior guard that only wants to run when the selection sits inside a specific subtree reaches for `rangeIntersects` with the selection on the snapshot: ```ts defineBehavior({ on: 'delete.backward', guard: ({snapshot}) => { const rowPath = [{_key: 't1'}, 'rows', {_key: 'r1'}] return traversal.rangeIntersects( snapshot, snapshot.context.selection, rowPath, ) }, actions: [ () => [ /* ... */ ], ], }) ``` ## Schema at a position `getPathSubSchema` returns the `Schema` view that applies at a path: the top-level schema outside any container, or the sub-schema derived from the nearest enclosing container's `of` declaration. See [Containers](/editor/concepts/containers/) for how that sub-schema is built. `getUnionSchema` returns a `Schema` merging every named member reachable from any position where text is edited: the root schema plus the sub-schema of every registered container whose field accepts text blocks, deduped by name. It takes the schema and the container map directly rather than a snapshot, both available as `snapshot.context.schema` and `snapshot.context.containers`. Where `getPathSubSchema` answers "what applies right here," `getUnionSchema` answers "what could ever apply somewhere," useful for a toolbar whose buttons stay stable across selection moves. ## Traversal and selectors Selectors build on the same snapshot and add current-selection semantics: `getFocusBlock` finds a block by asking where the selection focus is, using traversal underneath. Reach for traversal directly when you already hold a path, and for a selector when the question starts from the selection itself. # 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. ::: You'll need to: - Create a schema that defines your content elements. - Create a toolbar to toggle and insert these elements. - Set up rendering for your text blocks and inline formatting, like bold and italic. - 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. - **Node registrations:** Own how each content element renders, mounted through `NodePlugin`. [Rendering](/editor/concepts/rendering/) covers the model. - **Toolbars:** UI elements that interact with the editor. - **`PortableTextEditable`:** The core editor component. Hosts the editable surface and manages behavior. ## Add the library to your project Start by installing the editor (it requires React 19.2.8 or later): Next, import the components and types you'll need: ```tsx // App.tsx import { defineDecorator, defineSchema, defineTextBlock, EditorProvider, PortableTextEditable, } from '@portabletext/editor' import type {PortableTextBlock} from '@portabletext/editor' import {EventListenerPlugin, NodePlugin} 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 formatting elements. :::note This guide includes a limited set of schema types to get you started. See the [rendering guide](/editor/guides/custom-rendering/) for mark examples, and the [custom blocks guide](/editor/guides/custom-blocks/) for block and inline objects. ::: ```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 render inside your registered text-block render; ordered-list // numbering comes from `@portabletext/plugin-list-index`. 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 { defineDecorator, defineSchema, defineTextBlock, EditorProvider, PortableTextEditable, } from '@portabletext/editor' import type {PortableTextBlock} from '@portabletext/editor' import {EventListenerPlugin, NodePlugin} 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. ## Set up rendering for schema elements At this point the editor renders every text block as plain text, whatever its style. Fix that by registering a `defineTextBlock` node for the text blocks and `defineDecorator` nodes for the marks. The [Rendering](/editor/concepts/rendering/) page covers the model these registrations share. If you're maintaining an editor that rendered through the `renderStyle`, `renderBlock`, `renderListItem`, `renderDecorator`, and `renderAnnotation` props, removed in this major, see the [migration guide](/editor/guides/migrate-render-props/) to move to node registrations instead of following this section from scratch. Start by registering the text block render with `defineTextBlock`. The editor dispatches every text block to this callback. Your callback owns the block's wrapper element, so spread `props.attributes` on the outermost element you return, and use the block's `style` to pick the element. ```tsx const textBlock = defineTextBlock({ type: 'block', render: (props) => { if (props.node.style === 'h1') { return

   {props.children}

   } if (props.node.style === 'h2') { return

   {props.children}

   } if (props.node.style === 'h3') { return

   {props.children}

   } if (props.node.style === 'blockquote') { return

   {props.children}

   } return
   {props.children}
   }, }) ``` Marks (decorators and annotations) join the same `nodes` array. Registrations all follow the same shape: - They take in props and return JSX elements. - They decide what to render from the registration's `type` and the node itself. - They return JSX that renders `children` somewhere inside it, the editable content the registration wraps. With this in mind, continue for the remaining schema types. Register a decorator with `defineDecorator`, one per decorator name: ```tsx const strong = defineDecorator({ type: 'strong', render: ({children}) => {children}, }) const em = defineDecorator({ type: 'em', render: ({children}) => {children}, }) const underline = defineDecorator({ type: 'underline', render: ({children}) => {children}, }) const nodes = [textBlock, strong, em, underline] ``` :::note By default, text is rendered as an inline `span` element in the editor. A decorator's render can pass `children` through unwrapped, but the registered text block render must return a block-level element, like a `
   `. ::: Mount every registration through one `NodePlugin`, inside the `EditorProvider`. Keep the `nodes` array itself at module scope, as above: a fresh array on every render would make `NodePlugin` unregister and re-register on every keystroke. ```tsx <> ``` 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 ? ( ) : null}

   ) } // 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 ? : null} {props.schemaType.title} ) } // One `useStyleSelector` drives all style buttons: a block has one style at // a time, so the hook is a selector, not a per-button toggle function StyleButtons(props: { schemaTypes: ReadonlyArray }) { const styleSelector = useStyleSelector(props) const activeStyle = styleSelector.snapshot.context.activeStyle ?? 'normal' return props.schemaTypes.map((schemaType) => ( styleSelector.send({type: 'toggle', style: schemaType.name}) } className={activeStyle === schemaType.name ? 'active' : ''} > {schemaType.icon ? : null} {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 the registrations 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) } }} /> ) } // ... ``` 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. ### [Migrate render props to node registrations](/editor/guides/migrate-render-props/) Move an editor from the render props on `PortableTextEditable` to `defineX` node registrations, one kind at a time. ### [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). 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.  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. To learn how behaviors work, read [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 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. If your editor still renders block objects and inline objects through the deprecated `renderBlock`/`renderChild` props, see the [migration guide](/editor/guides/migrate-render-props/) to move to node registrations. You should be familiar with the [getting started guide](/editor/getting-started/) and [custom rendering](/editor/guides/custom-rendering/) first. ## 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 as a node registration (`defineBlockObject` or `defineInlineObject`), mounted through `NodePlugin` 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 it Register each block object type with `defineBlockObject`. The registration's `render` owns the block's wrapper element entirely: - Spread `attributes` onto the outer element. - Always render `children`, the engine's caret spacer that lets the browser place the cursor next to the block. - Wrap the visible content in a `contentEditable={false}` element with `draggable={!readOnly}`. Block objects are void, and this makes them drag-movable while the outer element stays the caret anchor. - Check for a field before using it: the registration already guarantees `node._type`, but individual fields can be absent on a partially-filled value. Fall back to `props.renderDefault(props)`, the engine's placeholder, when a field the render needs is missing. ```tsx import {defineBlockObject} from '@portabletext/editor' const imageBlock = defineBlockObject({ type: 'image', render: (props) => typeof props.node.src === 'string' ? (

   {props.children}

   {typeof props.node.caption === 'string' ? (

   {props.node.caption}

   ) : null}

   ) : ( props.renderDefault(props) ), }) const codeBlock = defineBlockObject({ type: 'code', render: (props) => typeof props.node.text === 'string' ? (

   {props.children}

             {props.node.text}
           

   ) : ( props.renderDefault(props) ), }) ``` Mount registrations through `NodePlugin`, alongside a `defineTextBlock` registration for your text blocks (a bare wrapper is enough if you don't customize them further): ```tsx import {defineTextBlock} from '@portabletext/editor' import {NodePlugin} from '@portabletext/editor/plugins' const textBlock = defineTextBlock({ type: 'block', render: ({attributes, children}) =>

   {children}

   , }) const nodes = [textBlock, imageBlock, codeBlock] ; ``` :::note A registration claims its type entirely: register `type: '*'` instead of a specific name to catch every block object type that has no more specific registration. A block object type with no registration at all, specific or `'*'`, gets a generic placeholder rendering instead of your custom look. ::: ### 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({type: 'open dialog'})} disabled={!blockObjectButton.snapshot.matches('enabled')} > {props.schemaType.icon && } {props.schemaType.title} ) } ``` Clicking the button moves the hook into its `showing dialog` state. Render the dialog for that state, and send `insert` from the dialog's submit handler: ```tsx import {useState} from 'react' function ImageButton(props: {schemaType: ToolbarBlockObjectSchemaType}) { const blockObjectButton = useBlockObjectButton(props) const [imageUrl, setImageUrl] = useState('') return ( <> blockObjectButton.send({type: 'open dialog'})} disabled={!blockObjectButton.snapshot.matches('enabled')} > {props.schemaType.icon && } {props.schemaType.title} {blockObjectButton.snapshot.matches({enabled: 'showing dialog'}) ? (

   setImageUrl(event.target.value)} placeholder="Image URL" /> { blockObjectButton.send({ type: 'insert', value: {src: imageUrl}, placement: undefined, }) setImageUrl('') }} > Insert blockObjectButton.send({type: 'close dialog'})} > Cancel

   ) : null} ) } ``` For a block type that needs no user input at all, skip the dialog states and insert straight from `useEditor`: ```tsx import {useEditor} from '@portabletext/editor' function InsertButton(props: {schemaType: ToolbarBlockObjectSchemaType}) { const editor = useEditor() return ( editor.send({ type: 'insert.block object', blockObject: {name: props.schemaType.name, value: {}}, placement: 'auto', }) } > {props.schemaType.icon && } {props.schemaType.title} ) } ``` ## 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 it `defineInlineObject` follows the same shape as `defineBlockObject`, with two differences. Inline objects need no `contentEditable={false}` on the visible content: the engine's outer attributes already carry non-editability, and your content inherits it. They do need the visible content wrapped in a `draggable={!readOnly}`, `display: inline-block` element, which makes the object drag-movable and keeps its text unselectable (a draggable element starts a drag instead of a text selection). ```tsx import {defineInlineObject} from '@portabletext/editor' const stockTicker = defineInlineObject({ type: 'stock-ticker', render: (props) => typeof props.node.symbol === 'string' ? ( {props.children} 📈 {props.node.symbol} {typeof props.node.exchange === 'string' ? ( {props.node.exchange} ) : null} ) : ( props.renderDefault(props) ), }) ``` Add it to the same `NodePlugin`: ```tsx const nodes = [textBlock, imageBlock, codeBlock, stockTicker] ; ``` ### 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({type: '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. Marks (decorators and annotations) render through node registrations: `defineDecorator` and `defineAnnotation`, mounted with `NodePlugin` alongside the editor's other registrations. [Rendering](/editor/concepts/rendering/) covers the model every registration shares: markup ownership, dispatch precedence, and `renderDefault`. [Containers](/editor/concepts/containers/) covers positional overrides, rendering a mark differently only inside one part of the document. `renderPlaceholder` and `rangeDecorations`, the remaining rendering props without a registration equivalent, stay on ``; this guide documents them below. The `renderDecorator`, `renderAnnotation`, `renderBlock`, `renderChild`, `renderStyle`, and `renderListItem` props are removed in this major; the [migration guide](/editor/guides/migrate-render-props/) walks through moving to registrations. None of these choices affect the Portable Text output: they only change how the editor itself renders content. ## Decorators Register one `defineDecorator` per decorator name. `render` receives the styled `children` to wrap: ```tsx import {defineDecorator} from '@portabletext/editor' const strong = defineDecorator({ type: 'strong', render: ({children}) => {children}, }) const em = defineDecorator({ type: 'em', render: ({children}) => {children}, }) const underline = defineDecorator({ type: 'underline', render: ({children}) => {children}, }) ``` Or keep one switching function with `type: '*'`, which matches any decorator that has no more specific registration; see [dispatch precedence](/editor/concepts/rendering/#dispatch-precedence) for how it ranks against an exact `type` match: ```tsx const decorator = defineDecorator({ type: '*', render: ({children, decorator}) => { if (decorator === 'strong') { return {children} } if (decorator === 'em') { return {children} } if (decorator === 'underline') { return {children} } return <>{children} }, }) ``` ## Annotations Register `defineAnnotation` for a markDef `_type`. `render` receives the markDef object as `annotation`: ```tsx import {defineAnnotation} from '@portabletext/editor' const link = defineAnnotation({ type: 'link', render: ({annotation, children}) => typeof annotation.href === 'string' ? ( {children} ) : ( children ), }) ``` `render` is a plain function call, not a component, so hooks inside it violate the Rules of Hooks. When a render needs hooks, for example to open a tooltip on the annotation, return a component instead: ```tsx import {useState} from 'react' import type {AnnotationRenderProps} from '@portabletext/editor' function LinkSpan(props: AnnotationRenderProps) { const [hovered, setHovered] = useState(false) const href = typeof props.annotation.href === 'string' ? props.annotation.href : '' return ( setHovered(true)} onMouseLeave={() => setHovered(false)} style={{textDecoration: 'underline'}} > {props.children} {hovered ? {href} : null} ) } const link = defineAnnotation({ type: 'link', render: (props) => , }) ``` ## Mount the registrations Marks join the same `nodes` array as your other registrations, mounted through one `NodePlugin`: see [Register a node](/editor/concepts/rendering/#register-a-node) on the Rendering page for the full example. ## Lists Lists are a bit unique. A list in Portable Text is flat: a run of sibling text blocks carrying `listItem` and `level`, with no wrapper node. ([Containers](/editor/concepts/containers/) nest blocks through object fields, but lists stay flat.) Visual nesting comes from CSS, and list numbering comes from [`@portabletext/plugin-list-index`](https://github.com/portabletext/editor/tree/main/packages/plugin-list-index). We suggest [including this example CSS](https://github.com/portabletext/editor/blob/main/examples/basic/src/editor.css) or similar to manage list rendering. ## 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. ### Following a range across edits Edits can move, shrink, or invalidate a decorated range: typing before it shifts its offsets, and deleting it removes it entirely. Pass `onMoved` on a `RangeDecoration` to keep your own state in sync instead of recomputing the selection from scratch: ```tsx import type { EditorSelection, RangeDecoration, RangeDecorationOnMovedDetails, } from '@portabletext/editor' import {useState} from 'react' function Highlight() { const [highlightSelection, setHighlightSelection] = useState( { anchor: { path: [{_key: 'block1'}, 'children', {_key: 'span1'}], offset: 0, }, focus: {path: [{_key: 'block1'}, 'children', {_key: 'span1'}], offset: 5}, }, ) const onMoved = (details: RangeDecorationOnMovedDetails) => { // `newSelection` is `null` when the edit removed the decorated range. setHighlightSelection(details.newSelection) } const decorations: RangeDecoration[] = [ { selection: highlightSelection, component: ({children}) => ( {children} ), onMoved, }, ] return ( ) } ``` # 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. ## 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} ) } ``` # Migrate from v7 to v8 > Everything v8 of the Portable Text Editor removes or changes, and what to do about each. v7 introduced [containers](/editor/concepts/containers/) and, alongside them, a new [rendering API](/editor/concepts/rendering/): node registrations. In v7 you rendered through one callback per node kind, switching on types inside it. With registrations, each node type is defined once, with its own `render`: ```tsx // v7: a render prop on props.value === 'strong' ? ( {props.children} ) : ( props.children ) } /> // v8: a node registration, mounted once inside const strong = defineDecorator({ type: 'strong', render: ({children}) => {children}, }) ``` v8 makes registrations the only rendering API: the six render props on ``, one callback per node kind, are removed, along with the Slate-era `data-slate-*` attributes and the default CSS classes the old rendering emitted. :::tip[A third off the bundle] v8 is about a third smaller than v7: a full import of `@portabletext/editor` drops from 209 KB to 144 KB minified and gzipped (measured with esbuild, React externalized). Editors that never used Markdown paste also stop shipping `markdown-it`. ::: Prepare on your latest v7 release first: move render props to node registrations and swap `data-slate-*` selectors for `data-pt-*`, both work on v7. Then bump the `@portabletext/*` packages together and sweep the rest of the checklist. This page covers every removal and rename of the editor's public surface, in upgrade order; if a piece of surface is not mentioned here, v8 does not remove or rename it. The breaking changes at a glance: - [Node 22.12 or later](#node-2212-or-later) is required. - [The six render props are removed](#render-props-become-node-registrations); rendering goes through node registrations. - [The `data-slate-*` attributes and the default CSS classes are gone](#style-and-query-on-data-pt-); style and query on `data-pt-*`. - [The built-in drop indicator is gone](#draw-your-own-drop-indicator); `@portabletext/plugin-dnd` tracks the drop position for your own. - [The built-in `text/markdown` clipboard converter is removed](#restore-the-textmarkdown-clipboard-behavior); a recipe restores it. - [The `loading`, `done loading`, and `error` events are removed](#removed-editor-events). - [Packages resolve through `exports` only](#packaging); the `main` and `module` fields are gone. - [`resolveContainerAt` is no longer exported](#resolvecontainerat-is-no-longer-exported). v8 also ships behavior improvements that need no migration work. Dropping a block object mid-paragraph now splits the paragraph at the drop point, where v7 snapped the drop to the nearest block edge. See the [changelog](https://github.com/portabletext/editor/releases) for the full list. ## Node 22.12 or later Every package now requires Node 22.12 or later, since Node 20 reached end of life in April 2026. `@portabletext/to-html` and `@portabletext/toolkit` take a major for the same Node requirement. ## Render props become node registrations If your editor mounts any of these six props on ``, each has a registration waiting for it: | Removed prop | Removed types | Replacement | | ------------------ | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | `renderStyle` | `RenderStyleFunction`, `BlockStyleRenderProps` | `defineTextBlock` | | `renderListItem` | `RenderListItemFunction`, `BlockListItemRenderProps` | `defineTextBlock` + [`@portabletext/plugin-list-index`](https://github.com/portabletext/editor/tree/main/packages/plugin-list-index) | | `renderBlock` | `RenderBlockFunction`, `BlockRenderProps` | `defineTextBlock` (text blocks) / `defineBlockObject` (block objects) | | `renderChild` | `RenderChildFunction`, `BlockChildRenderProps` | `defineInlineObject` (inline objects) / `defineSpan` (spans) | | `renderDecorator` | `RenderDecoratorFunction`, `BlockDecoratorRenderProps` | `defineDecorator` | | `renderAnnotation` | `RenderAnnotationFunction`, `BlockAnnotationRenderProps` | `defineAnnotation` | Registrations mount through `NodePlugin` and the engine dispatches per type (decorator name, annotation `_type`, block or object `_type`), so you can migrate one prop at a time on the latest v7 release, where both paths still work, and bump to v8 when the props are gone from your code. The [render props migration guide](/editor/guides/migrate-render-props/) has a worked example for each, and [Rendering](/editor/concepts/rendering/) covers the model they all share. Two props you might expect on the list are not on it. `renderPlaceholder` stays, the placeholder is empty-editor chrome with no type to register under, and `rangeDecorations` stays, it wraps a span's output from the outside. If your render callbacks read `schemaType` or `block` from their payload, both are derivable inside a registered render: `getPathSubSchema` and `getEnclosingBlock` from [`@portabletext/editor/traversal`](/editor/concepts/traversal/), called in a selector. The one field with no equivalent is `editorElementRef`, the engine's own DOM node; put a ref on your own rendered element instead, it reaches the same position in the DOM. ## Style and query on `data-pt-*` The Slate-era `data-slate-*` attributes are gone from the engine's DOM. If you have CSS or DOM queries keyed on the editor's markup, this section is your checklist, and the surface to key on is the `data-pt-*` family, present on v7 too, so the selector swap below can land before you bump to v8: | Attribute | Carried by | Value | | -------------------- | ----------------------------- | --------------------------------- | | `data-pt-editor` | the root editable | `true` | | `data-read-only` | the root editable | `true` or `false`, always present | | `data-pt-path` | every rendered node | the node's serialized path | | `data-pt-block` | block-level nodes | `text`, `object`, or `container` | | `data-pt-inline` | inline nodes | `span` or `object` | | `data-pt-marks` | every leaf, marked or not | `true` | | `data-pt-text` | the text node wrapper | `true` | | `data-pt-spacer` | the engine's void spacers | `true` | | `data-pt-zero-width` | zero-width fillers | `true` | | `data-pt-line-break` | zero-width line-break fillers | `true` | Query read-only state with `[data-read-only="true"]`: React always emits the attribute, so a bare `[data-read-only]` selector matches whether the editor is read-only or not. Line breaks are zero-width fillers too, so they carry both `data-pt-zero-width` and `data-pt-line-break`. Selectors on the Slate-era aliases map row for row, but check match breadth before a mechanical find-and-replace: the bare `[data-pt-path]` matches more nodes than `[data-slate-node="element"]` did, since `data-pt-path` sits on every rendered node, not only elements. | Removed | Replacement | | --------------------------- | ------------------------------------------------------------------ | | `data-slate-editor` | `data-pt-editor` | | `data-slate-node="element"` | `data-pt-path` (blocks also carry `data-pt-block`) | | `data-slate-node="text"` | `data-pt-inline="span"` | | `data-slate-leaf` | `data-pt-marks` | | `data-slate-string` | `data-pt-text` | | `data-slate-zero-width` | `data-pt-zero-width` (line breaks also carry `data-pt-line-break`) | | `data-slate-void` | `data-pt-block="object"` / `data-pt-inline="object"` | | `data-slate-spacer` | `data-pt-spacer` | The old default render's CSS classes and data attributes have no one-to-one replacements, because your registered render owns the markup now. Where you need a styling hook, emit your own attribute: - Classes: `pt-block`, `pt-text-block`, `pt-text-block-style-*`, `pt-list-item`, `pt-list-item-*`, `pt-list-item-level-*`, `pt-object-block`, `pt-inline-object`, and `pt-editable` on the root editable (a consumer-passed `className` still applies) - Data attributes: `data-block-key`, `data-block-name`, `data-block-type`, `data-child-key`, `data-child-name`, `data-child-type`, `data-style`, `data-list-item`, `data-level`, and `data-list-index` (re-emittable via [`@portabletext/plugin-list-index`](https://github.com/portabletext/editor/tree/main/packages/plugin-list-index): wrap the editor in `ListIndexProvider` and read `useListIndex` in your render) That does mean this bucket depends on the previous section: you need a registered render before you can emit anything from it. ## Draw your own drop indicator The engine no longer draws its own drop indicator during block drags. Block drag-and-drop itself keeps working: [`@portabletext/plugin-dnd`](https://github.com/portabletext/editor/tree/main/packages/plugin-dnd) tracks the drop position from the editor's public `drag.*` events, and your render draws whatever indicator your design wants. ## Restore the `text/markdown` clipboard behavior The editor no longer ships a built-in `text/markdown` converter: pasting Markdown-formatted text no longer auto-parses it into Portable Text blocks, and copying no longer writes a `text/markdown` entry to the clipboard alongside `text/html` and `text/plain`. The built-in ran the markdown package's defaults with no way to configure renderers or type mappings, and markdown copy/paste is something most consumers want to configure for their own schema. `text/markdown` is also mostly a dead clipboard channel: almost nothing writes it, and markdown usually arrives as `text/plain`, so a converter keyed on `text/markdown` rarely saw a real paste. Now only apps that want markdown interop carry the dependency, configured their way; every other editor stops bundling `markdown-it` (about 145 KB minified). To keep markdown interop, add [`@portabletext/markdown`](https://github.com/portabletext/editor/tree/main/packages/markdown) as your own dependency and register two Behaviors (via `BehaviorPlugin` or `editor.registerBehavior`). Both sides are a faithful restore: `text/markdown` goes back on the clipboard on copy, and `deserialize.data` for `text/markdown` parses it back into Portable Text blocks on paste. Since markdown usually arrives as `text/plain`, most consumers will want to widen the guard to accept that too. `text/markdown` keeps its place ahead of `text/html` and `text/plain` in the paste priority. With no converter and no Behavior answering `deserialize.data` for it, a paste doesn't dead-end: it falls through to the next available format on the clipboard. Table copies from [`@portabletext/plugin-table`](https://github.com/portabletext/editor/tree/main/packages/plugin-table) lose their `text/markdown` entry with the converter. Copying and pasting between two Portable Text Editors is unaffected: that round-trips through `application/x-portable-text`. ```tsx import {defineBehavior, raise} from '@portabletext/editor/behaviors' import {getFragment} from '@portabletext/editor/selectors' import { markdownToPortableText, portableTextToMarkdown, } from '@portabletext/markdown' const deserializeMarkdown = defineBehavior({ on: 'deserialize.data', guard: ({snapshot, event}) => { if (event.mimeType !== 'text/markdown') { return false } const blocks = markdownToPortableText(event.data, { schema: snapshot.context.schema, keyGenerator: snapshot.context.keyGenerator, }) return blocks.length > 0 ? {blocks} : false }, actions: [ ({event}, {blocks}) => [ raise({...event, type: 'deserialization.success', data: blocks}), ], ], }) const serializeMarkdown = defineBehavior({ on: 'serialize.data', guard: ({event}) => event.mimeType === 'text/markdown', actions: [ ({snapshot, event}) => [ raise({ type: 'serialization.success', mimeType: 'text/markdown', data: portableTextToMarkdown( getFragment(snapshot).map((entry) => entry.node), ), originEvent: event.originEvent, }), ], ], }) ``` ## Removed editor events Three members leave `EditorEmittedEvent`: `loading`, `done loading`, and `error`. `error` was never emitted, so its listeners were dead code. `loading` and `done loading` were real: they fired around an async `onPaste` resolution. `onPaste` stays in v8, but nothing signals around it anymore; if you showed paste progress from these events, track it around your own `onPaste` promise instead. An exhaustive switch over `event.type` loses three cases. ## Packaging Published packages resolve through `exports` only; the legacy `main` and `module` fields are gone. Tooling old enough to ignore `exports` predates the packages' Node requirement. ## `resolveContainerAt` is no longer exported The `@alpha` API has been removed. If you use it, [`snapshot.context.containers`](/editor/concepts/containers/#read-the-registered-containers) exposes the registered container map, and [`getContainerChildren`](/editor/reference/traversal/) covers per-node descent; the full path walk builds from that primitive. # Migrate render props to node registrations > Move an editor from the render props on PortableTextEditable to defineX node registrations, one kind at a time. Through v7, the editor rendered a document's content (text blocks, block objects, inline objects, spans, decorators, and annotations) through render props on ``: `renderBlock`, `renderChild`, `renderStyle`, `renderListItem`, `renderDecorator`, `renderAnnotation`. v8 removes them in favor of node registrations (`defineTextBlock`, `defineBlockObject`, `defineInlineObject`, `defineSpan`, `defineContainer`, `defineDecorator`, `defineAnnotation`) mounted through `NodePlugin`. Registrations are how [containers](/editor/concepts/containers/) render, and for a registered node, decorator, or annotation they owned the wrapper entirely: the matching render prop did not fire once a registration claimed that type. This guide maps each render prop to its registration equivalent, so you can migrate before upgrading to v8. You don't have to do it in one go. ## What maps to what | Legacy | New | | ---------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | `renderStyle`, `renderListItem`, `renderBlock` (for text blocks) | `defineTextBlock({type: 'block'})` | | `renderBlock` (for block objects) | `defineBlockObject`, per type or `type: '*'` | | `renderChild` (for inline objects) | `defineInlineObject`, per type or `type: '*'` | | `renderChild` (for spans) | `defineSpan({type: 'span'})` | | `renderDecorator` | `defineDecorator`, per decorator name or `type: '*'` | | `renderAnnotation` | `defineAnnotation`, per `_type` or `type: '*'` | | `renderPlaceholder`, range decorations | Unchanged, keep them | | Engine list wrapping and numbering | Your text block render + [`@portabletext/plugin-list-index`](https://github.com/portabletext/editor/tree/main/packages/plugin-list-index) | | Engine drop indicator | [`@portabletext/plugin-dnd`](https://github.com/portabletext/editor/tree/main/packages/plugin-dnd) | ## Migrate one kind at a time The engine dispatched per `_type`: a node rendered through a registration when one matched its type (or a `'*'` catch-all for its kind), and at the top level fell back to the render prop when none did. Registering block objects didn't affect how text blocks rendered, so you could migrate kind by kind and keep the remaining render props in place until their kind was migrated. One boundary to plan around: a registration claimed everything rendered inside it. Inside a registered [container](/editor/concepts/containers/), unregistered types rendered through the engine defaults, not through your remaining render props, so when a container entered the picture mid-migration, you had to register everything that rendered inside it in the same step. The same applied one level down: a registered text block claimed its inline children, and `renderChild` stopped firing for the spans and inline objects inside it. That is why the steps below migrate inline objects and spans before text blocks. Decorators and annotations sat outside this claiming rule. The engine dispatched them per decorator and annotation inside every span's leaf render, independent of whether the enclosing span or text block was registered, so migrating them carried no ordering dependency on the other kinds; do it whenever you like. ## Step 1: block objects The legacy `renderBlock` handles text blocks and block objects in one callback, branching on `schemaType`: ```tsx const renderBlock: RenderBlockFunction = (props) => { if (props.schemaType.name === 'image' && isImage(props.value)) { return (

   

   ) } // Default case for text blocks return

   {props.children}

   } ``` The registration splits that branch into kinds. A block object registers by its type, no `isImage` guard needed, the registration _is_ the type match: ```tsx import {defineBlockObject} from '@portabletext/editor' const imageBlock = defineBlockObject({ type: 'image', render: (props) => typeof props.node.src === 'string' ? (

   

   {props.children}

   ) : ( props.renderDefault(props) ), }) ``` Four contract differences from the legacy callback: spread `attributes` onto your outer element, render `children` even though the block is a void (the engine mounts its internals through them), mark the visible content `contentEditable={false}` while keeping the outer element editable (the engine anchors the caret through it), and put `draggable={!readOnly}` on that non-editable wrapper. The legacy pipeline added the `contentEditable` and `draggable` wrapper for you; a registration owns the whole node, so dropping `draggable` silently loses drag-to-move. This mirrors the engine's own default block-object render. If you render every block object the same way, a preview card, say, the catch-all `type: '*'` matches every block object type that has no more specific registration, which is the direct equivalent of the generic legacy callback: ```tsx const blockObjectFallback = defineBlockObject({ type: '*', render: ({attributes, children, node, readOnly}) => (

   {children}

   ), }) ``` Per-type registrations and the catch-all compose: register `image` specifically and `'*'` for the rest. ## Step 2: inline objects `renderChild` migrates the same way. Before: ```tsx const renderChild: RenderChildFunction = (props) => { if (props.schemaType.name === 'stock-ticker' && isStockTicker(props.value)) { return {props.value.symbol} } return props.children } ``` After, per type or catch-all: ```tsx import {defineInlineObject} from '@portabletext/editor' const stockTicker = defineInlineObject({ type: 'stock-ticker', render: (props) => typeof props.node.symbol === 'string' ? ( {props.children} {props.node.symbol} ) : ( props.renderDefault(props) ), }) ``` Unlike block objects, inline objects need no `contentEditable={false}`: the engine's outer attributes already carry non-editability, and your content inherits it. They DO need the inner `draggable={!readOnly}` wrapper around the visible content: the legacy pipeline wrapped your `renderChild` output in a `draggable` inline-block span, which is what makes an inline object drag-movable and keeps its text unselectable (a draggable element starts a drag instead of a text selection). A registration that renders the content bare loses both behaviors, and nothing fails loudly. The legacy default case (`return props.children`) disappears: spans keep rendering through the engine, with decorator and annotation renders still composing inside them exactly as before, and only registered inline object types hit your render. ## Step 3: spans, if you customized them Most editors never touch how spans render directly: decorators and annotations, covered in steps 5 and 6, handle the styling inside a span. But the legacy `renderChild` also fired for the spans themselves, and if yours wrapped them, the registration equivalent is `defineSpan`: ```tsx import {defineSpan} from '@portabletext/editor' const span = defineSpan({ type: 'span', render: ({attributes, children}) => ( {children} ), }) ``` A registered span owns the outer wrapper, and `children` arrive with the decorator and annotation renders from `defineDecorator`/`defineAnnotation` already applied, the same composition the legacy pipeline produced inside the span. `'span'` is the span type at the top level; text blocks can positionally register renamed span-like types through their own `of` (a `code-span` inside a code block's line, say), which is a [containers](/editor/concepts/containers/) concern rather than a migration one. ## Step 4: text blocks Text blocks register as `type: 'block'`, which is the text block type at every nesting level, top level and inside containers alike. The registration's render owns the whole wrapper, so the three legacy callbacks fold into one function. Reproduce the engine's legacy composition order: style innermost, list item around it, block wrapper outermost. :::note[Why pass `type` at all?] If the text block is always `block` and the span is always `span`, the parameter looks redundant. It exists because registrations live in a type-keyed registry with two tiers: `'*'` is an optional catch-all, matching any type of that kind without a more specific registration, and positional overrides can register renamed types at that scope: block-level kinds through a container's `of`, inline kinds through a text block's `of`. `'block'` and `'span'` are those kinds' canonical names at the top level. ::: Before: ```tsx const renderStyle: RenderStyleFunction = (props) => { if (props.schemaType.value === 'h1') { return

   {props.children}

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

   {props.children}

   } return <>{props.children} } const renderListItem: RenderListItemFunction = (props) => ( {props.children} ) // Plus the text-block default case of the `renderBlock` from step 1: //

   {props.children}

   ``` After: ```tsx import {defineTextBlock} from '@portabletext/editor' const textBlock = defineTextBlock({ type: 'block', render: ({attributes, children, node}) => { let content = children // Your `renderStyle` logic, innermost. if (node.style === 'h1') { content =

   {content}

   } else if (node.style === 'blockquote') { content =

   {content}

   } // Your `renderListItem` logic around it. if (node.listItem !== undefined) { content = ( {content} ) } // Your `renderBlock` default case, outermost. return (

   {content}

   ) }, }) ``` The render props carry `node`, `path`, `focused`, and `selected`, so components you already have keep receiving the information the legacy callbacks gave them. ## Step 5: decorators The legacy `renderDecorator` switches on the decorator name via `props.value`: ```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} } ``` A per-decorator registration replaces each branch. `type` is the decorator name, so no `props.value` check is needed: ```tsx import {defineDecorator} from '@portabletext/editor' const strong = defineDecorator({ type: 'strong', render: ({children}) => {children}, }) const em = defineDecorator({ type: 'em', render: ({children}) => {children}, }) const underline = defineDecorator({ type: 'underline', render: ({children}) => {children}, }) ``` If you'd rather keep one switching function, `type: '*'` matches every decorator that has no more specific registration and hands you the decorator name as `decorator` where the legacy callback gave you `value`: ```tsx const decoratorFallback = defineDecorator({ type: '*', render: ({children, decorator}) => { if (decorator === 'strong') { return {children} } if (decorator === 'em') { return {children} } if (decorator === 'underline') { return {children} } return <>{children} }, }) ``` Per-decorator registrations and the catch-all compose: register `strong` specifically and `'*'` for the rest. ## Step 6: annotations Before: ```tsx const renderAnnotation: RenderAnnotationFunction = (props) => { if (props.schemaType.name === 'link') { return {props.children} } return <>{props.children} } ``` After, per `_type`. The registration receives the annotation's `markDef` object as `annotation`, in place of the legacy `schemaType`/`value` pair: ```tsx import {defineAnnotation} from '@portabletext/editor' const link = defineAnnotation({ type: 'link', render: ({children}) => ( {children} ), }) ``` Or, matching the legacy switching style, `type: '*'` and discriminate on `annotation._type`: ```tsx const annotationFallback = defineAnnotation({ type: '*', render: ({annotation, children}) => annotation._type === 'link' ? ( {children} ) : ( <>{children} ), }) ``` `annotation` is the full `markDef` object (`{_key, _type, ...fields}`) with an `unknown` index signature, so a field the legacy callback read off a separately-typed `value` (a `link` annotation's `href`, say) needs a cast: `String(annotation.href)`. It is named `annotation`, not `node`, because `path` addresses the span carrying the annotation, not the markDef. :::note[Legacy fields with no registration equivalent] `renderDecorator` and `renderAnnotation` both carried `editorElementRef`, a ref to the engine-owned leaf DOM anchor. No registration exposes it, and the prop is gone, so there is nothing to fall back to: put a ref on your own rendered element instead. A decorator's `render` owns the markup and an annotation's composes inside the engine's anchor, so a ref on your own element reaches the same position in the DOM. Both props also carried `schemaType` (`renderAnnotation` carried `block` too), which a registration's `render` doesn't receive, but you can derive them yourself from a `path`: `getPathSubSchema` and `getEnclosingBlock`, both from the [traversal API](/editor/concepts/traversal/), read the sub-schema and enclosing text block inside a selector. ::: :::caution[Registration renders are plain function calls, not components] This holds for every `define*` render, and it matters most here: the legacy `renderDecorator`/`renderAnnotation` callbacks each ran inside their own wrapper component, so hooks in them happened to work. A registration's `render` runs as a plain call inside the engine's render, where hooks violate the Rules of Hooks and crash as decorators toggle. If a migrated callback uses hooks, move them into a component and return it: `render: (props) => `. ::: ## Step 7: reclaim the engine's chrome Under the legacy pipeline the engine wrapped list items and numbered ordered lists for you, and drew a drop indicator during block drags. Under registrations both are yours. [`@portabletext/plugin-list-index`](https://github.com/portabletext/editor/tree/main/packages/plugin-list-index) computes the 1-based list index at any path, and [`@portabletext/plugin-dnd`](https://github.com/portabletext/editor/tree/main/packages/plugin-dnd) tracks the drop position from the editor's `drag.*` events. Both follow the same pattern, a provider inside `EditorProvider` and a hook read from a component your render returns; the [Rendering page](/editor/concepts/rendering/#plugins-for-lists-and-drag-and-drop) covers the pattern, and each plugin's README carries the full recipe, including a reference `DropIndicator` implementation. ## Step 8: mount and clean up Mount every registration through one `NodePlugin` with a stable identity, and drop the migrated render props: ```tsx import {NodePlugin} from '@portabletext/editor/plugins' // Plus `span` from step 3, if you needed it. const nodes = [ imageBlock, blockObjectFallback, stockTicker, textBlock, strong, em, underline, link, ] function App() { return ( ) } ``` `renderPlaceholder` is the only render prop left unmigrated: registrations render nodes identified by a schema type, and the placeholder is empty-editor chrome with no type to register under, so it stays as is. `rangeDecorations` is a separate data prop, not a render prop: it carries a component that wraps a span's rendered output from the outside, after the span (registered or not) has already rendered, so it is untouched by this migration too. # 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. ## 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 To spec a behavior end to end, 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 } ``` Plugins that render document nodes register through `editor.registerNode(...)` instead, passing the result of a `defineX` factory (`defineContainer`, `defineTextBlock`, `defineSpan`, `defineBlockObject`, `defineInlineObject`). Like `registerBehavior`, `registerNode` returns an unregister function: ```tsx function LogImagesPlugin() { const editor = useEditor() useEffect(() => { const unregisterNode = editor.registerNode({ node: defineBlockObject({ type: 'image', render: (props) => { console.log(props.node) return props.renderDefault(props) }, }), }) return () => { unregisterNode() } }, [editor]) return null } ``` `NodePlugin` is a thin wrapper around `registerNode` for the common case of registering a stable list of nodes; reach for `registerNode` directly when a plugin needs to register a node conditionally or alongside other setup. ## 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. Selectors delegate their path work to the [traversal API](/editor/concepts/traversal/). ```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 the full mark state 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. # Traversal API overview > Pure functions that answer questions about the editor's value tree, given a path and a snapshot. import {LinkCard} from '@astrojs/starlight/components' Traversal functions are pure functions that answer questions about the editor's value tree, given a snapshot and a path. They provide a clean way to navigate and inspect the value tree without directly parsing the snapshot structure. ```ts import * as traversal from '@portabletext/editor/traversal' ``` ## Lookups Resolve a path to the node that lives there. - `getNode` - Get the node at a given path - `hasNode` - Check if a node exists at a given path - `getBlock` - Get the node at a given path if it is a block - `getTextBlock` - Get the text block node at a given path - `getSpan` - Get the span node at a given path - `getAnnotation` - Get the annotation at a given path - `getContainer` - Get the registered editable container at a given path only, does not walk up to an enclosing container - `getText` - Get the concatenated text content of the node at a given path ## Family walkers Move relative to a path. - `getParent` - Get the parent of a node at a given path - `getAncestor` - Walk up from a path to find an ancestor that matches a predicate - `getAncestors` - Get all ancestors of the node at a given path, from nearest to furthest - `getChildren` - Get the children of a node at a given path - `getContainerChildren` - Resolve a container node's editable child array (beta) - `getFirstChild` - Get the first child of a node at a given path - `getLastChild` - Get the last child of a node at a given path - `getSibling` - Get a sibling of the node at a given path - `getEnclosingBlock` - Walk up from a path to find the nearest enclosing block - `getLeaf` - Walk from a path toward the `start` or `end` edge and get the deepest leaf node reached ## Narrowing predicates - `isBlock` - Determine if a node at the given path is a block - `isInline` - Determine if a node at the given path is inline - `isObject` - Check if a node is an object node (not a text block or span) - `isLeafObject` - Check if a node is a leaf object: an object node that has no editable children ## Path and point utilities - `pathContains` - Returns true if `ancestor` is equal to `descendant`, or if `descendant` lives anywhere inside `ancestor`'s subtree - `comparePoints` - Compares two points by document order, resolved at any depth - `rangeIntersects` - Returns true if a range and a target path, point, or selection intersect ## Schema resolution - `getPathSubSchema` - Return the `Schema` view that applies at a given path; its `blockObjects` and `inlineObjects` fields answer what can exist there - `getUnionSchema` - Return a `Schema` that contains every named member reachable from a position where text is edited # 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. - **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 falls back to an unknown-type handler instead of throwing; what that fallback renders varies per serializer (the [Markdown serializer](/rendering/markdown/), for example, renders unrecognized types as a fenced JSON block). ## 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 `${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 go through an unknown-type fallback whose default varies per serializer (the React serializer renders a hidden warning, the Markdown serializer a fenced JSON block). You can take over 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. For what survives a Markdown → Portable Text → Markdown loop, see [Markdown round-tripping](/conversion/markdown-round-tripping/). ## 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 `callout`, `code`, `horizontal-rule`, `html`, `image`, and `table` block objects render as Markdown out of the box. `callout`, `code`, `html`, `image`, and `table` fall back to a fenced JSON block when a value doesn't match the shape its renderer expects (a consumer's own differently-shaped `code` type, say); `horizontal-rule` always renders `---`. Register a renderer for other custom types you use, or to override one of the defaults. ```ts portableTextToMarkdown(blocks, { types: { chart: ({value}) => ``, }, }) ``` 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 `` }, }, }) ``` ## 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 `callout`, `code`, `horizontal-rule`, `html`, `image`, and `table` are registered by default. The package also exports `DefaultBlockquoteObjectRenderer` and `DefaultListRenderer` for the structural container shapes the parser produces when `types.blockquote`/`types.list` matchers are registered; those two stay opt-in since the parser only produces that shape when asked to. ```ts import { DefaultBlockquoteObjectRenderer, DefaultListRenderer, portableTextToMarkdown, } from '@portabletext/markdown' portableTextToMarkdown(blocks, { types: { blockquote: DefaultBlockquoteObjectRenderer, list: DefaultListRenderer, }, }) ``` Supply your own `types.` renderer to override any of the defaults. | 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?` | `` | | `DefaultTableRenderer` | `rows`, `headerRows?` | Markdown table | | `DefaultBlockquoteObjectRenderer` | `content` | `> content` | | `DefaultListRenderer` | `kind`, `items` | Markdown list | ## 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 | ✅ | :::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 | | ------------------------------- | --------------------------------------------------------------------------------------------------------- | | `