Tiptap Docs

Add slots to the document

Call the insertSlot command to add a new slot to the document.

// Inserts new slot at the selection
editor.commands.insertSlot()

There are two types of slots:

  • Inline slots can contain inline content like text
  • Block slots use a block layout and contain one or more paragraphs, headings or other block Nodes.

To turn selected text into a slot while keeping its content, call wrapInSlot. It uses the editor's current selection when range is omitted; pass range: { from, to } to wrap a specific document range instead:

editor.commands.wrapInSlot({
  kind: 'inline',
  id: 'customer',
  config: { label: 'Customer name', placeholder: 'Enter a name', required: true },
})

Use kind: 'block' when selecting complete blocks. insertSlot replaces selected content instead of wrapping it.

wrapInSlot accepts id and config just like insertSlot. Omit id to generate one. Wrapping preserves the selected content; there is no callback option to transform it or derive the configuration. Your application can inspect the selection first and supply its chosen configuration to the command.

When creating a slot, you can define its type and many properties, like a unique ID, a label, and a set of rules to restrict its allowed content.

editor.commands.insertSlot({
  kind: 'inline',
  id: 'customer',
  config: {
    label: 'Customer name',
    required: true,
    constraints: { maxLength: 120 },
  },
})

Then, a slot can be filled by typing inside it or calling the fillSlot command.

editor.commands.fillSlot({
  id: 'customer',
  // Tiptap JSON content
  content: [{ type: 'text', text: 'Sam Rivera' }],
})

Other useful commands:

  • clearSlot({ id }) empties a slot.
  • dissolveSlot({ id }) removes the slot wrapper and keeps its content, turning it into regular document content.
  • removeSlot({ id }) removes a slot including its content.

Two creation shortcuts are enabled by default:

  • Type {{{ to immediately create an empty inline Slot and place the cursor inside it.
  • Type [[[ in an otherwise empty paragraph to immediately create a block Slot and place the cursor in its empty paragraph.

No closing delimiter or Enter is required. Set Slot.configure({ shortcuts: false }) to disable all Slot input rules. The input-rule resolver can configure, fill or decline the new Slot.

To also convert text between delimiters into an inline Slot, configure a pair:

Slot.configure({
  shortcuts: { inline: { open: '{{', close: '}}' } },
})

Typing {{Ada}} creates an inline Slot containing “Ada”. This pair always creates an inline Slot, including in an empty paragraph. The {{{ and [[[ creation shortcuts remain enabled. See shortcut configuration to customize or disable individual rules.

Example: Slot editor app

An example template editor where users can add slots to a document.

After that the document can be passed to a different set of users who fill the slots. To do that, configure document permissions so that users are only allowed to fill slots and not other parts of the document. Read this guide to set up the editor so that users can fill document slots.

PreviouslyOverview