---
title: "Configuration"
description: "Embedded Slot configuration, content rules and defaults."
canonical_url: "https://tiptap.dev/docs/composable-docs/slots/api-reference/concepts"
---

# Configuration

Embedded Slot configuration, content rules and defaults.

A Slot stores its rules in `attrs.config`. Rules report invalid content when validation is requested; they do not block editing or change the schema.

## `SlotConfig`

### Properties

- `label?` (`string`): Accessible name. Omitted: use the Slot ID.
- `instructions?` (`string`): Application-facing instructions. Omitted: none.
- `placeholder?` (`string`): View-only text for an empty Slot. Omitted: none.
- `defaultContent?` (`JSONContent[]`): Initial content when insertion omits `content`. Omitted: empty content for the kind.
- `required?` (`boolean`): Whether empty content fails validation. Default: `false`.
- `allowedBlocks?` (`SlotContentType[]`): Permitted direct non-Slot block children. Omitted: any installed block type. `[]`: none.
- `allowedInline?` (`SlotContentType[]`): Permitted non-text, non-Slot inline descendants. Omitted: any installed inline type. `[]`: none.
- `allowText?` (`boolean`): Whether text is valid. Default: `true`.
- `allowedMarks?` (`SlotContentType[]`): Permitted Marks. Omitted: any installed Mark. `[]`: none.
- `constraints?` (`SlotConfig['constraints']`): Value constraints listed below. Omitted: no value restrictions.
- `nesting?` (`SlotConfig['nesting']`): Nested Slot rules listed below. Default: `{ allowed: false }`.
- `validators?` (`ValidatorReference[]`): Application checks. Default: `[]`.
- `crossFieldRules?` (`CrossFieldRule[]`): Checks involving other fields. Default: `[]`.
- `metadata?` (`Record<string, JsonValue>`): Application-owned JSON. Default: no metadata; the package assigns no meaning to it.

```ts
const config: SlotConfig = {
  required: true,
  allowedBlocks: [{ type: 'paragraph' }],
  constraints: { maxLength: 600 },
}
```

### `constraints`

- `minLength?` (`number`): Minimum text length in Unicode code points. Omitted: no minimum.
- `maxLength?` (`number`): Maximum text length in Unicode code points. Omitted: no maximum.
- `minChildren?` (`number`): Minimum direct children of a block Slot. Omitted: no minimum.
- `maxChildren?` (`number`): Maximum direct children of a block Slot. Omitted: no maximum.
- `pattern?` (`{ source: string; flags?: string; message?: string }`): Regular-expression test. Omitted: no pattern check.
- `values?` (`string[]`): Accepted exact text values. Omitted: unrestricted. `[]`: no nonempty value is valid.

Counts are nonnegative integers; minima cannot exceed maxima. Child counts include nested Slots and the empty paragraph in an empty block Slot.

### `constraints.pattern`

- `source` (`string`): JavaScript regular-expression source. Add `^` and `$` for a full-text match.
- `flags?` (`string`): Combination of `i`, `m`, `s`, `u`. Default: `''`. Stateful flags `g` and `y` are not supported.
- `message?` (`string`): Failure message. Omitted: built-in message.

### `nesting`

- `allowed` (`boolean`): Whether descendant Slots are valid.
- `kinds?` (`SlotKind[]`): Permitted descendant kinds. Omitted: both kinds, subject to the schema. `[]`: none.
- `maxDepth?` (`number`): Maximum Slot edges below the owner. Direct nested Slots have depth `1`. Omitted: unlimited.

Every ancestor's nesting restrictions apply. Inline Slots cannot contain block Slots.

## `SlotContentType`

### Properties

- `type` (`string`): Exact schema Node or Mark name.
- `attributes?` (`Record<string, JsonValue[]>`): Allowed values per attribute. Omitted: no attribute restrictions. Each value list must be nonempty.

Entries in an allow list use OR; attributes within an entry use AND. Values use structural JSON equality without coercion.

`allowedBlocks` checks direct non-Slot children. Nested Slots are checked by `nesting`, not the block allow list. Inline, text and Mark rules check descendants but stop at nested Slots, which use their own configuration.

## `ValidatorReference`

### Properties

- `name` (`string`): Key in the configured `validators` registry.
- `params?` (`JsonValue`): Validator parameters. Default: `null`.

## `CrossFieldRule`

### Properties

- `id?` (`string`): Optional diagnostic identifier, unique within the owner. Without an ID, diagnostics use `ruleIndex`.
- `validator` (`string`): Key in `crossFieldValidators`.
- `fields` (`string[]`): Referenced Slot IDs, including the owner.
- `params?` (`JsonValue`): Validator parameters. Default: `null`.

Evaluated once at its owner. Findings may target only declared fields. See [custom validators](https://tiptap.dev/docs/composable-docs/slots/api-reference/validation.md#slotvalidator).

## Defaults and identity

- Explicit insertion content, including `[]`, overrides `defaultContent`.
- Defaults are copied only on creation. Loading, clearing or changing configuration does not refill a Slot.
- Nested default Slots receive fresh IDs; internal cross-field references are remapped.
- Copy/paste creates fresh Slot IDs and remaps references within the copied fragment. External references remain unchanged.
- Internal drag moves preserve IDs. Local cut/paste can preserve IDs when they are no longer in use.
- Missing or duplicate imported IDs are preserved and diagnosed. Use `repairSlotIds` explicitly.

## Configuration errors

Unknown keys, invalid JSON, malformed patterns and invalid counts produce configuration issues. Schema-aware checks also report unknown Node and Mark types. Use `metadata` for application-specific data.

`allowedBlocks`, `constraints.minChildren` and `constraints.maxChildren` apply only to block Slots. Using them on an inline Slot is a configuration error. Authoring commands refuse these configurations; imported documents retain them for validation diagnostics.

See [`validateSlotConfig`](https://tiptap.dev/docs/composable-docs/slots/api-reference/validation.md#validateslotconfig) to check configuration before assigning it.