Commands

Add Slot before using editor.commands, editor.chain() or editor.can(). Each command accepts one options object unless stated otherwise.

Commands return false for invalid arguments, missing or ambiguous targets, schema violations or denied permissions. Invalid draft content is accepted; validation does not block edits.

With the Variable extension, a slot controlled by an explicit value or resolver refuses content writes with false. This includes filling, clearing, removing, dissolving, or moving the controlled slot, and writes through parent or nested slots. Inserting or wrapping content inside it is also refused. These refusals emit slotCommandRejected with code: 'variableControlled'; editor.can() returns false without emitting an event. An explicit null or undefined still controls the slot. Slots bound to variables without an explicit definition remain editable.

• Each call writes at most one transaction. No-op calls add no undo entry.
• A refused Slot command cancels the writes assembled in its chain.
• editor.can() emits no events, runs no validators and generates no real IDs. Dispatch checks again using the actual IDs.
• JSON content must fit the schema. Commands do not parse HTML or silently coerce content.

JSONContent comes from @tiptap/core. Configuration and result types are exported by the Slot package.

Value slot commands

insertSlot also accepts mode?: 'content' | 'value' and value?: JsonValue. Mode defaults to content. Value insertion refuses content; content insertion refuses value. Placement still uses kind.

editor.commands.insertSlot({
  mode: 'value',
  id: 'budget',
  value: '1.0',
  config: { input: { type: 'number' } },
})
editor.commands.setSlotValue({ id: 'budget', value: '2.50' })
editor.commands.setSlotValues({ values: [{ id: 'budget', value: '3.00' }] })

setSlotValue({ id, value }) replaces one value attribute. setSlotValues({ values }) applies a batch atomically. Both require unique IDs targeting value slots and finite JSON values. They respect protection, variable control, history, and dry runs. Duplicate batch targets are refused. Validation constraints do not block draft writes.

clearSlot writes null for value slots. moveSlot, removeSlot, repairSlotIds, and updateSlotConfig support both modes. focusSlot selects a value slot and focuses its first input, select, textarea, button, or element with a tabindex when present. fillSlot, fillSlots, dissolveSlot, and selectSlotContent refuse value slots. Wrapping content creates a content slot.

insertSlot

Inserts a Slot or replaces the current selection.

editor.commands.insertSlot()

Parameters (InsertSlotOptions, optional)

• mode? (SlotMode): 'content' or 'value'. Default: 'content'.
• kind? (SlotKind): 'block' or 'inline'. Omitted: 'inline' when the parent at the insertion position accepts inline content (including an empty paragraph); otherwise 'block'. Uses at or the current selection start.
• id? (string): Unique, nonempty ID. Omitted: generated.
• config? (SlotConfig): Embedded configuration. Default: {}.
• content? (JSONContent[]): Initial content for content slots only. Omitted: defaultContent, then empty content for the kind.
• value? (JsonValue): Initial answer for value slots only. Omitted: defaultValue, then null. Explicit null overrides the default.
• at? (number): Document position. Omitted: replace the current selection.

Returns (boolean)

true when inserted; otherwise false. Placement must fit without wrapping or lifting surrounding content.

Nested Slots in defaultContent receive fresh IDs on each insertion, with references between them remapped. Explicit content keeps supplied IDs and is refused if they duplicate existing IDs.

setSlotValue

Replaces a value slot's answer while preserving its ID and configuration.

Parameters (SetSlotValueOptions)

• id (string): Unique target value Slot ID.
• value (JsonValue): Replacement finite JSON value, including null.

Returns (boolean)

true when accepted, including an unchanged value; otherwise false. Content slots, invalid values, and denied writes are refused. Validation constraints do not block draft writes.

setSlotValues

Updates multiple value slots atomically.

Parameters

• values (SetSlotValueOptions[]): IDs and replacement values.

Returns (boolean)

true when all writes succeed, including an empty batch. false for duplicate targets or any refused write, with no slots changed.

wrapInSlot

Wraps existing content in a Slot.

Parameters (WrapSlotOptions)

• kind (SlotKind): 'block' or 'inline'.
• id? (string): Unique, nonempty ID. Omitted: generated.
• config? (SlotConfig): Embedded configuration. Default: {}.
• range? ({ from: number; to: number }): Nonempty range. Default: current selection.

Returns (boolean)

true when wrapped; otherwise false. Inline ranges must share one inline parent; block ranges must contain complete sibling blocks.

fillSlot

Replaces content while preserving the Slot ID and configuration.

Parameters (FillSlotOptions)

• id (string): Target Slot ID.
• content (JSONContent[]): Replacement content. [] creates an empty paragraph for a block Slot.

Returns (boolean)

true when accepted; otherwise false. Replacing a parent can remove nested Slots and requires permission to remove them.

Returns false when a variable controls the target or any affected nested slot, even for a replacement matching the current content.

fillSlots

Fills multiple Slots atomically.

Parameters

• values (FillSlotOptions[]): IDs and replacement content.

Returns (boolean)

true when all fills succeed, including an empty batch. false for duplicate targets, ancestor/descendant targets or any refused fill.

If any target is variable-controlled, the entire batch returns false and no slot changes.

clearSlot

For content slots, replaces content with the kind’s empty content and removes nested Slots. For value slots, writes null to the value attribute.

Parameters (SlotTarget)

• id (string): Target Slot ID.

Returns (boolean)

true when cleared; otherwise false. Does not restore defaultContent or defaultValue.

dissolveSlot

Removes the wrapper and preserves its contents, including nested Slots.

Parameters (SlotTarget)

• id (string): Target Slot ID.

Returns (boolean)

true when dissolved; false if the result cannot fit the parent or the edit is refused.

removeSlot

Removes the wrapper and all its contents.

Parameters (SlotTarget)

• id (string): Target Slot ID.

Returns (boolean)

true when removed; false if the parent would become schema-invalid or the edit is refused.

selectSlotContent

Selects the contents without the wrapper.

Parameters (SlotTarget)

• id (string): Target Slot ID.

Returns (boolean)

true when selected; false for a missing, ambiguous or concealed target.

moveSlot

Moves the complete Slot Node.

Parameters (SlotTarget & { to: number })

• id (string): Target Slot ID.
• to (number): Destination in pre-transaction coordinates.

Returns (boolean)

true when moved; false for a destination inside the Slot, an invalid parent or a refused edit.

updateSlotConfig

Replaces the complete configuration in one undoable edit.

Parameters (SlotTarget & { config: SlotConfig })

• id (string): Target Slot ID.
• config (SlotConfig): Complete replacement; not a patch.

Returns (boolean)

true when accepted; otherwise false. Existing content is unchanged and may become invalid under the new rules.

repairSlotIds

Keeps the first valid occurrence of each ID and assigns new IDs to missing or later duplicate entries.

Parameters

None.

Returns (boolean)

true when repaired or already valid; false if generation or protection refuses the repair. Ambiguous cross-field references remain unchanged.

focusSlot

Focuses a reachable position inside a Slot and scrolls it into view.

Parameters (SlotTarget & { edge?: 'start' | 'end' })

• id (string): Target Slot ID.
• edge? ('start' | 'end'): End to focus. Default: 'start'.

Returns (boolean)

true when focused; false for a concealed target or no reachable content position.

focusNextSlot

Focuses the next Slot in document order, including nested Slots. Concealed Slots are skipped.

Parameters (NavigateSlotOptions)

• fromId? (string): Starting Slot. Default: current innermost Slot.
• wrap? (boolean): Continue at the opposite end. Default: false.

The entire options object is optional.

Returns (boolean)

true when focus moves; otherwise false. Without an active Slot, starts at the first reachable Slot.

focusPreviousSlot

Focuses the previous Slot in document order, including nested Slots. Concealed Slots are skipped.

Parameters (NavigateSlotOptions)

• fromId? (string): Starting Slot. Default: current innermost Slot.
• wrap? (boolean): Continue at the opposite end. Default: false.

The entire options object is optional.

Returns (boolean)

true when focus moves; otherwise false. Without an active Slot, starts at the last reachable Slot.

invalidateSlotValidation

Increments the context revision, aborts pending validation and clears the cached result.

Parameters

None.

Returns (boolean)

true after invalidation. Changes no document content or undo history; emits slotValidationUpdate.