Skip to content

Web component API cheat sheet

You can use the SciFlow web components without knowing Lit. Import the bundle once and interact with plain DOM properties and events.

Elements

  • <sciflow-editor> — main editor host
  • <sciflow-formatbar> — toolbar; set for to the editor id
  • <sciflow-selection-editor> — sidebar selection inspector; set for to the editor id. With a figure selected it edits the image address and the alt text; with a table selected it edits the table's attributes. All of its writes are withheld while the bound view is not editable.
  • <sciflow-reference-list> — renders references and supports drag/drop/highlight

Inputs (props/attributes)

  • doc (object) — ProseMirror JSON document, or { doc, files, references, selection, version } for atomic updates
  • features (array) — list of editor features (for example, citationFeature, footnoteFeature, headingFeature)
  • sync (SyncStrategy | null, property only) — your own load/persist/collaboration implementation. Unset (the default) means the built-in in-memory strategy: the document stays in the page and nothing is persisted. See Binding the element to your own sync strategy and Custom Sync Strategies
  • doc-id / docId (string) — stable identifier of the document, handed to the strategy's load() and bind(). Defaults to a fresh random id per mount, which is only meaningful for the built-in strategy
  • part-id / partId (string) — the part within the document this editor is bound to, for backends whose concurrency unit is narrower than a document (one document holding several parts, each with its own version counter and change log). Forwarded to the strategy's bind(); the editor never interprets it
  • client-id / clientID (string | number) — stable per-client identifier. Setting it activates step-based concurrency, so remote changes rebase local edits instead of replacing the document. Keep it stable across reloads of the same client (for example, one id per browser tab)
  • shadowStyles (string | string[] | CSSStyleSheet | CSSStyleSheet[]) — CSS injected into the shadow root (for chrome overrides: border, focus ring, :host vars); can be set before or after initialization. To style editor content (.ProseMirror, decorations), use global CSS targeting .sf-editable-surface .ProseMirror instead — the editable is in the light DOM.
  • for (string, formatbar/selection-editor) — editor element id to bind to
  • hidden-groups (string, formatbar) — space- or comma-separated list of command-metadata group names to omit from the toolbar (for example, hidden-groups="align"). This is purely a rendering filter. The suppressed commands stay schema-legal and remain reachable via editor.commands and the command runner's available(); only their toolbar buttons disappear. Use it to suppress capabilities that aren't representable in a structured export content model (for example, free paragraph alignment ahead of a JATS-based export pipeline) without a schema change.
  • citationSourceAdapter (selection-editor) — custom UI for editing citation source (CSL citation items); when unset, uses the default schema-aware form
  • references (reference-list) — array of CSL-like reference objects
  • highlightedIds (reference-list) — array of ids to highlight; can also call highlight(ids)
  • empty-text (reference-list) — message when no references exist

Events

See Web Components Basics for the full event table and payload shapes.

Theming (global)

See Web Components Basics for setSciFlowThemeStyles() usage and examples.

Selection editor custom properties

  • --sciflow-selection-editor-danger — text colour of the destructive Delete control. The default is derived from the host's color-scheme, so it darkens on a light panel and lightens on a dark one; set it on the host (or via setSciFlowThemeStyles()) to use your own status colour. Keep it at 4.5:1 against your panel background.

Usage

<!-- In a bundler: import '@sciflow/editor-start/bundle'; -->
<script type="module" src="/node_modules/@sciflow/editor-start/dist/bundle/sciflow-editor.js"></script>
<sciflow-editor id="editor"></sciflow-editor>
<sciflow-formatbar for="editor"></sciflow-formatbar>
<sciflow-selection-editor for="editor"></sciflow-selection-editor>
<sciflow-reference-list id="refs"></sciflow-reference-list>

<script type="module">
  const editor = document.getElementById('editor');
  const refs = document.getElementById('refs');
  editor.features = [citationFeature, footnoteFeature, headingFeature];
  editor.addEventListener('editor-change', (e) => {
    const { doc, files, references } = e.detail;
    // persist doc/files/references
  });
  refs.references = myReferences;
  refs.highlight(['ref-1']);

  // Style editor content via global CSS — the editable is in the light DOM:
  // .sf-editable-surface .ProseMirror { font-family: "Inter", system-ui; line-height: 1.5; }
  // .sf-editable-surface .ProseMirror h1 { letter-spacing: -0.01em; }
  // Add decoration styles the same way: .sf-editable-surface .my-decoration { … }

  // Use shadowStyles / setShadowStyles() for chrome overrides (border, focus ring, :host vars):
  editor.shadowStyles = `:host { --sciflow-editor-border: #4f46e5; }`;

  // setShadowStyles() applies immediately (recommended for dynamic updates)
  editor.setShadowStyles(`:host { --sciflow-editor-focus-ring: #e11d48; }`);
</script>

Advanced APIs

  • document (getter) — Read-only ProseMirror document for traversal
  • positions.coordsAtPos(pos) — Get screen coordinates for a position
  • positions.resolve(pos) — Resolve position with context
  • plugins.getState(key) — Get plugin state by PluginKey
  • plugins.dispatchMeta(key, meta) — Update plugin state
  • dom.getBoundingRect() — Get editor bounding rectangle
  • dom.dispatchEvent(event) — Dispatch custom events
  • setShadowStyles(styles) — Immediately apply shadow-root chrome styles (sync); accepts string, string[], or CSSStyleSheet. For content styles (.ProseMirror, decorations) use global CSS targeting .sf-editable-surface instead.
  • editorView (getter) — Advanced: Direct ProseMirror access (unstable)

Citation source editor

For the full adapter API and example, see Adding Custom ProseMirror Plugins. You can also set selectionEditor.citationSourceAdapter per element instance.