@orion-front/docs

Appearance

Tiptap Panel ​

Purpose ​

Use tiptapPanel for rich-text authoring or read-only rich content, either as a standalone editor or bound to one attribute of the object selected elsewhere.

When to use ​

Use standalone mode for temporary/demo content or client-only authoring. Use object-bound mode for persistence. Use textEditorPanel only when the renderer-policy shell and legacy renderer detection are required.

Prerequisites and ownership ​

  • Standalone mode may provide initialContent and needs no selection event.
  • Object-bound mode requires both editorConfig.attributeName and request.getSelectedObjectForEventId.
  • The panel owns selection binding, object load/update, dirty/save state, and content wrapper serialization.
  • Tiptap 3 and the panel editor components own editing commands and document UI.

Capability map ​

AreaSupported behavior
TextBold, italic, underline, strike, inline code, color, highlight, sub/superscript, and links
BlocksParagraphs, headings, blockquote, lists, code block, rule, images, tables, math, and symbols
Editing UIMain toolbar, selection bubble menu, floating empty-paragraph menu, image actions, drag-handle menu, and table context controls
TablesInsert/resize, row/column/cell operations, header toggles, selection overlay, and alignment
StandaloneHTML or JSON initial content; local dirty state
Object bindingResolve selected GUID, load one projected attribute, update the same attribute
PersistenceSerializes { "renderer": "tiptap", "version": 1, "payload": ... }
SafetyLoading/no-selection/error states, read-only mode, dirty marker, save state, and browser-leave warning

Behavioral model ​

Standalone mode initializes from initialContent or an empty document. Object-bound mode watches the configured event, loads the selected object's attribute, and replaces the editor document when selection changes. Edits are compared to an independent baseline. Save updates the bound attribute; a standalone save only clears dirty state and does not persist externally.

Alternatives, defaults, and precedence ​

  • readOnly: false.
  • placeholder: localized runtime text.
  • minHeight: 400 pixels for the editable content area.
  • dataFormat: json; html is the alternative.
  • Panel editorConfig overrides a directly supplied component config.
  • initialContent applies only when no object binding is active.
  • When an object event is configured without attributeName, the wrapper shows object-bound UI but cannot load/save an attribute; always configure the pair.

Limitations ​

  • Standalone mode has no persistence backend.
  • Local fixture mode deliberately refuses save and shows a notice.
  • Images are stored as base64 data URLs.
  • Object-bound saves rewrite content to the versioned Tiptap wrapper.
  • Content wrapped for a different renderer normalizes to an empty document in the Tiptap layer; use textEditorPanel when users need an explicit warning.
  • Changing selection with unsaved edits does not provide a dedicated in-app confirmation flow.

Minimal configuration ​

json
{
  "id": "notes",
  "type": "tiptapPanel",
  "editorConfig": {
    "placeholder": "Write notes...",
    "dataFormat": "json"
  }
}

Scenario A: standalone rich document ​

json
{
  "id": "instructions-template",
  "type": "tiptapPanel",
  "editorConfig": {
    "readOnly": false,
    "placeholder": "Write instructions...",
    "minHeight": 520,
    "dataFormat": "json",
    "initialContent": {
      "type": "doc",
      "content": [
        {
          "type": "heading",
          "attrs": { "level": 2 },
          "content": [{ "type": "text", "text": "Assembly instructions" }]
        }
      ]
    }
  }
}

Scenario B: edit a selected object's attribute ​

json
{
  "id": "operation-instructions",
  "type": "tiptapPanel",
  "request": {
    "getSelectedObjectForEventId": "operations--selected"
  },
  "editorConfig": {
    "readOnly": false,
    "attributeName": "textualInstruction",
    "dataFormat": "json",
    "placeholder": "Enter work instructions...",
    "minHeight": 500
  }
}

Expected result: before selection, the panel shows the no-selection state. After selection, it loads textualInstruction; Save updates that attribute.

Runnable demos ​

Open the standalone rich-content editor Open Tiptap in a constrained resizable layout Open multiple Tiptap layouts in tabs Open read-only HTML object binding

The object API fixture is the verified readOnly: true journey; the standalone fixture intentionally uses readOnly: false.

Exact parameter reference ​

Next, choose standalone or object-bound mode, then verify load, dirty state, save, reload, and read-only behavior for the chosen data format.