@portabletext/toolbar

Powered by Behaviors and State Machines, @portabletext/toolbar is a collection of robust React hooks for building toolbars and related UI components
for the Portable Text editor.

Refer to the toolbar in the Portable Text Playground for a comprehensive example.

Features

- Schema Extension: Extend the editor's schema with default values, icons, shortcuts and more. This makes it easier to use the schema to render toolbars, forms and other UI components.
- Hooks: Headless React hooks to help building UI components for toggle buttons, popovers and insert dialogs.
- Keyboard Shortcuts: Seamless integration with @portabletext/keyboard-shortcuts for platform-aware shortcuts.

Installation

``bash
npm install @portabletext/toolbar
`

Basic Example

`tsx
import {bold, link} from '@portabletext/keyboard-shortcuts'
import {
useDecoratorButton,
useHistoryButtons,
useToolbarSchema,
type ExtendAnnotationSchemaType,
type ExtendDecoratorSchemaType,
} from '@portabletext/toolbar'

/**
* 1. Define extensions for your schema types
*/
const extendDecorator: ExtendDecoratorSchemaType = (decorator) => {
if (decorator.name === 'strong') {
return {
...decorator,
icon: BoldIcon,
shortcut: bold,
}
}

return decorator
}
const extendAnnotation: ExtendAnnotationSchemaType = (annotation) => {
if (annotation.name === 'link') {
return {
...annotation,
icon: LinkIcon,
defaultValues: {
href: 'https://example.com',
},
shortcut: link,
}
}

return annotation
}

/**
* 2. Create a Toolbar plugin that can be used inside an EditorProvider.
*/
function ToolbarPlugin() {
/**
* 3. Obtain a ToolbarSchema by extending the EditorSchema.
*/
const toolbarSchema = useToolbarSchema({
extendDecorator,
extendAnnotation,
// extendStyle,
// extendList,
// extendBlockObject,
// extendInlineObject,
})

/**
* 4. Render the toolbar
*/
return (


return (
<>
onClick={() => historyButtons.send({type: 'history.undo'})}
disabled={historyButtons.snapshot.matches('disabled')}
>
Undo

onClick={() => historyButtons.send({type: 'history.redo'})}
disabled={historyButtons.snapshot.matches('disabled')}
>
Redo


)
}
`

Hooks

$3

Extends the editor's schema with default values, icons, shortcuts and more to make it easier to render toolbars, forms and other UI components.

`typescript
function useToolbarSchema(props: {
extendDecorator?: (
decorator: DecoratorSchemaType,
) => ToolbarDecoratorSchemaType
extendAnnotation?: (
annotation: AnnotationSchemaType,
) => ToolbarAnnotationSchemaType
extendList?: (list: ListSchemaType) => ToolbarListSchemaType
extendBlockObject?: (
blockObject: BlockObjectSchemaType,
) => ToolbarBlockObjectSchemaType
extendInlineObject?: (
inlineObject: InlineObjectSchemaType,
) => ToolbarInlineObjectSchemaType
extendStyle?: (style: StyleSchemaType) => ToolbarStyleSchemaType
}): ToolbarSchema
`

$3

Manages the state and behavior of decorator toggle buttons (bold, italic, etc.) with keyboard shortcut support.

`typescript
function useDecoratorButton(props: {
schemaType: ToolbarDecoratorSchemaType
}): DecoratorButton
`

Returns: An object with:

- snapshot: Current state snapshot with matches() method
- send: Function to dispatch events like {type: 'toggle'}

$3

Manages the state and behavior of annotation buttons in the toolbar. Handles adding/removing annotations, keyboard shortcuts, and dialog interactions.

`typescript
function useAnnotationButton(props: {
schemaType: ToolbarAnnotationSchemaType
}): AnnotationButton
`

Returns: An object with:

- snapshot: Current state snapshot with matches() method
- send: Function to dispatch events like {type: 'add'}, {type: 'remove'}, {type: 'open dialog'}, {type: 'close dialog'}

$3

Provides state management for annotation popover dialogs, including form handling and validation.

`typescript
function useAnnotationPopover(props: {
schemaTypes: ReadonlyArray
}): AnnotationPopover
`

Returns: An object with:

- snapshot: Current state snapshot with matches() method and context containing active annotations
- send: Function to dispatch events like {type: 'remove'}, {type: 'edit'}, {type: 'close'}

$3

Manages style selection (headings, paragraphs, etc.) with keyboard shortcut support.

`typescript
function useStyleSelector(props: {
schemaTypes: ReadonlyArray
}): StyleSelector
`

Returns: An object with:

- snapshot: Current state snapshot with matches() method and context.activeStyle
- send: Function to dispatch events like {type: 'toggle', style: 'h1'}

$3

Manages list item toggle buttons (bullet lists, numbered lists, etc.).

`typescript
function useListButton(props: {schemaType: ToolbarListSchemaType}): ListButton
`

Returns: An object with:

- snapshot: Current state snapshot with matches() method
- send: Function to dispatch events like {type: 'toggle'}

$3

Manages insertion of block objects like images into the editor.

`typescript
function useBlockObjectButton(props: {
schemaType: ToolbarBlockObjectSchemaType
}): BlockObjectButton
`

Returns: An object with:

- snapshot: Current state snapshot with matches() method
- send: Function to dispatch events like {type: 'open dialog'}, {type: 'insert'}

$3

Provides state management for block object insertion dialogs.

`typescript
function useBlockObjectPopover(props: {
schemaType: ToolbarBlockObjectSchemaType
}): BlockObjectPopover
`

Returns: An object with:

- snapshot: Current state snapshot with matches() method
- send: Function to dispatch events like {type: 'open dialog'}, {type: 'close dialog'}, {type: 'insert'}

$3

Manages insertion of inline objects into the editor.

`typescript
function useInlineObjectButton(props: {
schemaType: ToolbarInlineObjectSchemaType
}): InlineObjectButton
`

Returns: An object with:

- snapshot: Current state snapshot with matches() method
- send: Function to dispatch events like {type: 'open dialog'}, {type: 'insert'}

$3

Provides state management for inline object insertion dialogs.

`typescript
function useInlineObjectPopover(props: {
schemaType: ToolbarInlineObjectSchemaType
}): InlineObjectPopover
`

Returns: An object with:

- snapshot: Current state snapshot with matches() method
- send: Function to dispatch events like {type: 'open dialog'}, {type: 'close dialog'}, {type: 'insert'}

$3

Provides undo/redo functionality for the editor.

`typescript
function useHistoryButtons(): HistoryButtons
`

Returns: An object with:

- snapshot: Current state snapshot with matches() method
- send: Function to dispatch events like {type: 'history.undo'}, {type: 'history.redo'}`