---
title: "Commands"
description: "Typed Slot authoring, filling and navigation commands."
canonical_url: "https://tiptap-docs.lin52025i.qzz.io/composable-docs/slots/api-reference/commands"
---

# Commands

Typed Slot authoring, filling and navigation 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](https://tiptap-docs.lin52025i.qzz.io/composable-docs/variables/guides/bind-slots.md), 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](https://tiptap-docs.lin52025i.qzz.io/composable-docs/slots/api-reference/concepts.md) and [result types](https://tiptap-docs.lin52025i.qzz.io/composable-docs/slots/api-reference/types.md) 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`.

```ts
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.

```ts
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`.