astro-portabletext

!license

A flexible and customizable library for rendering Portable Text content in Astro projects.

⚠️ Prerequisites:

- Astro v4.6+ (as of v0.11.0)

Table of Contents

- Features
- Demonstration
- Resources
- Installation
- Usage
- Sanity Integration
- PortableText component
- Basic usage
- Custom components
- Slots
- PortableText component properties
- Utility functions
- usePortableText
- mergeComponents
- toPlainText
- Contributing
- License

🚀 Features

- 🧩 Core components: Provides pre-built components for common Portable Text elements.
- 🔧 Customizable: Use components or slots to tailor output to your needs.
- 🛠 Flexible control: Use render function via usePortableText to fine-tune rendering.
- 📘 Typescript: Built with full TypeScript support.

🎮 Demonstration

Jump in and see it in action:

📖 Resources

- Documentation: Read the full documentation including TypeScript type definitions.
- Examples: Browse practical examples to help you learn.

📦 Installation

Pick your favorite package manager and run one of these:

``bash
npm install astro-portabletext


or

This component provides a simple and flexible way to display rich text, from
using slots to custom components.

#### Basic usage

Import the PortableText component and start rendering. This library provides sensible defaults for rendering common Portable Text elements, which you can easily override.

> Use the following default mapping to understand what each node type outputs.

`js
/ .astro /
---
import { PortableText } from "astro-portabletext";

const portableText = [
{
_type: "block",
children: [
{
_type: "span",
marks: [],
text: "This is a ",
},
{
_type: "span",
marks: ["strong"],
text: "bold",
},
{
_type: "span",
marks: [],
text: " text example!",
},
],
markDefs: [],
style: "normal",
},
];
---


`

#### Custom components

Custom components allow for better control over rendering of rich text elements. You can map a component to a node type or map the component to the property of the node type.

`js
/ .astro /
---
import { PortableText } from "astro-portabletext";

const portableText = [
// ... your Portable Text content
];

const components = {
// custom types
type: { [_type]: Component } | Component,
unknownType: Component,
// block style
block: { [style]: Component } | Component,
unknownBlock: Component,
// list
list: { [listItem]: Component } | Component,
unknownList: Component,
// list item
listItem: { [listItem]: Component } | Component,
unknownListItem: Component,
// mark
mark: { [markType]: Component } | Component,
unknownMark: Component,
// strings; added in v0.11.0
text: Component,
// line break
hardBreak: Component
};
---


`

💡 Refer to custom components documentation for more details.

#### Slots

> Added in v0.11.0

Slots provide a flexible way to enhance the rendering of Portable Text elements by passing additional props to the component. This allows you to customize the output in various ways, such as:

- Applying custom styles or classes
- Wrapping elements in custom components
- Modifying the output based on specific conditions

Here's an example of using a slot to apply custom styles to strong elements:

`ts
/ .astro /
---
import { PortableText } from "astro-portabletext";

const portableText = [
// ... your Portable Text content
];
---


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



`

💡 Refer to slots documentation for more details.

$3

| Property | Type | Description |
| ------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| value | array or object | Portable Text payload |
| components (optional) | object | Mapping of components to node types or its properties. |
| onMissingComponent (optional) | function or boolean | Disable warning messages or handle unknown types. Default prints to console. |
| listNestingMode (optional) | "html" or "direct" | List nesting mode. Default is html. See ToolkitListNestMode |

$3

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

`js
import {
usePortableText,
mergeComponents,
toPlainText,
spanToPlainText, // added in v0.11.0
} from "astro-portabletext";
`

💡 Refer to the utility functions documentation for more details.

🙌 Contributing

We welcome contributions to improve astro-portabletext`!

If you find a bug or have a feature request, please open an issue on GitHub.
If you'd like to contribute code, feel free to submit a pull request.

📄 License

This project is licensed under the ISC License.