utility-functions.md

astro-portabletext • Documentation

---

Utility functions

This library provides utility functions to help you work with Portable Text content:

// v0.11.0+
import {
  usePortableText,
  mergeComponents,
  toPlainText,
  spanToPlainText,
} from "astro-portabletext";

// Deprecated
import {
  usePortableText,
  mergeComponents,
  toPlainText,
} from "astro-portabletext/utils";

usePortableText

usePortableText(node: TypedObject): Context

This function gives you access to helper functions like render (added in v0.11.0), which allows you to fine-tune the output of child nodes in your custom components. It should only be used within an Astro component that has been passed into the PortableText components prop. It follows a naming convention similar to React hooks, though it is not a hook as such.

💡 Refer to BlockWithRenderFunction.astro example for guidance.

mergeComponents

mergeComponents(components: SomePortableTextComponents, overrideComponents: SomePortableTextComponents): object

Combines two sets of components options, where overrideComponents takes precedence.

toPlainText

toPlainText(block): string

Extracts the text content from Portable Text blocks, preserving spacing.

💡 Refer to @portabletext/toolkit toPlainText documentation for more details.

spanToPlainText

spanToPlainText(span): string

Added in v0.11.0

Returns plain text from a Portable Text span, useful for extracting text from nested nodes.

💡 Refer to @portabletext/toolkit spanToPlainText documentation for more details.