@portabletext/types

What is @portabletext/types?

@portabletext/types is a TypeScript library that provides type definitions for Portable Text, a JSON-based rich text format. It helps developers to work with Portable Text data structures in a type-safe manner.

What are @portabletext/types's main functionalities?

Type Definitions for Portable Text

This feature provides type definitions for Portable Text blocks, ensuring that the data structure adheres to the expected format. The code sample demonstrates how to define a Portable Text block with a single span child.

import { PortableTextBlock } from '@portabletext/types';

const exampleBlock: PortableTextBlock = {
  _type: 'block',
  _key: 'a1b2c3',
  children: [
    {
      _type: 'span',
      _key: 'd4e5f6',
      text: 'Hello, world!',
      marks: []
    }
  ],
  markDefs: [],
  style: 'normal'
};

Type Definitions for Annotations and Marks

This feature provides type definitions for annotations and marks within Portable Text. The code sample shows how to define a link annotation with a URL.

import { PortableTextMarkDefinition } from '@portabletext/types';

const exampleMarkDef: PortableTextMarkDefinition = {
  _type: 'link',
  _key: 'g7h8i9',
  href: 'https://example.com'
};

Type Definitions for Custom Portable Text Objects

This feature allows developers to define custom Portable Text objects with specific properties. The code sample demonstrates how to define a custom image object with a URL and alt text.

import { PortableTextObject } from '@portabletext/types';

const exampleCustomObject: PortableTextObject = {
  _type: 'image',
  _key: 'j1k2l3',
  url: 'https://example.com/image.jpg',
  alt: 'An example image'
};

Other packages similar to @portabletext/types

slate

Slate is a completely customizable framework for building rich text editors. Unlike @portabletext/types, which focuses on type definitions for a specific JSON-based format, Slate provides a more comprehensive solution for creating and managing rich text content, including a React-based editor.

draft-js

Draft.js is a JavaScript rich text editor framework, built by Facebook. It provides a set of tools for building rich text editors, including type definitions and utilities for managing content state. While @portabletext/types focuses on type safety for Portable Text, Draft.js offers a more extensive set of features for building and managing rich text editors.

prosemirror

ProseMirror is a toolkit for building rich text editors with a focus on extensibility and customizability. It provides a robust set of tools for managing document state and rendering content. Compared to @portabletext/types, ProseMirror offers a more comprehensive solution for building rich text editors, including a wide range of plugins and extensions.

README

@portabletext/types

TypeScript types for Portable Text

Installation

npm install --save @portabletext/types

Documentation

See https://portabletext.github.io/types/

Usage

import type {
  PortableTextBlock,
  PortableTextSpan,
  PortableTextLink
} from '@portabletext/types'

const headingSpan: PortableTextSpan = {
  _type: 'span',
  _key: '5p4n',
  text: 'A simple Portable Text heading block',
  marks: [],
}

const myBlocks: PortableTextBlock[] = [
  {
    _type: 'block',
    _key: 'abc123',
    style: 'h1',
    children: [headingSpan],
    markDefs: [],
  },
  {
    _type: 'block',
    _key: 'xyz987',
    style: 'normal',
    children: [
      {_type: 'span', _key: 'c7', text: 'Check out the ', marks: []}
      {_type: 'span', _key: 'x2', text: 'TypeScript definitions', marks: ['m4hl1nk']},
      {_type: 'span', _key: 'u5', text: ' if you are using TS!', marks: []}
    ],
    markDefs: [
      {
        _key: 'm4hl1nk',
        _type: 'link',
        href: 'https://github.com/portabletext/types'
      }
    ],
  },
]

/**
 * Very specific Portable Text block, where:
 * - Only link and author references (custom) are allowed as marks
 * - Only Portable Text spans and `localCurrency` objects can be inline children
 * - Blocks can only be of style `normal` or `call-to-action` (custom)
 * - List items can only be of type `bullet`
 */
type MyCustomBlock = PortableTextListItemBlock<
  PortableTextLink | AuthorReference, // `M`: Marks
  PortableTextSpan | LocalCurrency,   // `C`: Children
  'normal' | 'call-to-action',        // `S`: Styles
  'bullet'                            // `L`: List item types
>

License

MIT © Sanity.io

Changelog

2.0.3 (2023-06-23)

Bug Fixes

• bump pkg-utils (cfa0679)
• remove pkg.exports.node condition (3a8e353)