superdoc-dev/superdoc-core

SuperDoc Core

SuperDoc is a document editing and rendering library for the web. It provides full DOCX support with real-time collaboration capabilities.

When to Apply

Reference these guidelines when:

• Adding document editing to a vanilla JS application
• Integrating SuperDoc with Vue, Svelte, or Angular
• Configuring SuperDoc options
• Understanding the core API
• Setting up collaboration or AI features

Installation

npm install superdoc

Quick Start

import { SuperDoc } from 'superdoc';
import 'superdoc/style.css';

const superdoc = new SuperDoc({
  selector: '#editor',
  document: file, // File, Blob, URL, or config object
  documentMode: 'editing',
  onReady: ({ superdoc }) => {
    console.log('Editor ready!');
  }
});

Configuration

Required Options

| Option | Type | Description | |--------|------|-------------| | selector | string \| HTMLElement | Container element | | document | File \| Blob \| string \| object | Document to load |

Mode & Role

| Option | Type | Default | Description | |--------|------|---------|-------------| | documentMode | 'editing' \| 'viewing' \| 'suggesting' | 'editing' | Editing mode | | role | 'editor' \| 'viewer' \| 'suggester' | 'editor' | User permissions |

User Options

| Option | Type | Description | |--------|------|-------------| | user | { name, email?, image? } | Current user info | | users | Array<{ name, email, image? }> | All users (for @-mentions) |

UI Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | toolbar | string \| HTMLElement \| false | auto | Toolbar container | | rulers | boolean | true | Show rulers | | pagination | boolean | true | Enable pagination |

Event Callbacks

| Option | Type | Description | |--------|------|-------------| | onReady | ({ superdoc }) => void | Instance initialized | | onEditorCreate | ({ editor }) => void | ProseMirror editor created | | onEditorDestroy | () => void | Editor destroyed | | onEditorUpdate | ({ editor }) => void | Content changed | | onContentError | (event) => void | Document parsing error | | onException | ({ error }) => void | Runtime error |

Instance Methods

Document Mode

// Change editing mode
superdoc.setDocumentMode('viewing');
superdoc.setDocumentMode('editing');
superdoc.setDocumentMode('suggesting');

Export

// Export as DOCX blob
const blob = await superdoc.export({ triggerDownload: false });

// Export and trigger download
await superdoc.export({ triggerDownload: true });

// Export as HTML
const htmlArray = superdoc.getHTML();

Editor Control

// Focus the editor
superdoc.focus();

// Lock/unlock editing
superdoc.setLocked(true);
superdoc.setLocked(false);

// Toggle rulers
superdoc.toggleRuler();

// High contrast mode
superdoc.setHighContrastMode(true);

Search

// Search for text
const results = superdoc.search('keyword');
const regexResults = superdoc.search(/pattern/gi);

// Navigate to result
superdoc.goToSearchResult(results[0]);

Track Changes

// Set track changes preferences
superdoc.setTrackedChangesPreferences({
  mode: 'review', // 'review' | 'original' | 'final'
  enabled: true
});

Cleanup

// Destroy instance
superdoc.destroy();

Document Modes

| Mode | Description | Use Case | |------|-------------|----------| | editing | Full editing capabilities | Default editing | | viewing | Read-only presentation | Document preview | | suggesting | Track changes mode | Collaborative review |

User Roles

| Role | Can Edit | Can Suggest | Can View | |------|----------|-------------|----------| | editor | Yes | Yes | Yes | | suggester | No | Yes | Yes | | viewer | No | No | Yes |

Framework Integration

Vue 3

<script setup>
import { ref, onMounted, onUnmounted } from 'vue';
import { SuperDoc } from 'superdoc';
import 'superdoc/style.css';

const containerRef = ref(null);
let superdoc = null;

const props = defineProps({
  document: { type: [File, String, Object], required: true }
});

onMounted(async () => {
  superdoc = new SuperDoc({
    selector: containerRef.value,
    document: props.document,
    documentMode: 'editing'
  });
});

onUnmounted(() => {
  superdoc?.destroy();
});
</script>

<template>
  <div ref="containerRef" style="height: 700px" />
</template>

Svelte

<script>
  import { onMount, onDestroy } from 'svelte';
  import { SuperDoc } from 'superdoc';
  import 'superdoc/style.css';

  export let document;

  let container;
  let superdoc;

  onMount(() => {
    superdoc = new SuperDoc({
      selector: container,
      document,
      documentMode: 'editing'
    });
  });

  onDestroy(() => {
    superdoc?.destroy();
  });
</script>

<div bind:this={container} style="height: 700px" />

Vanilla JavaScript (Dynamic Import)

async function initEditor(container, document) {
  const { SuperDoc } = await import('superdoc');

  return new SuperDoc({
    selector: container,
    document,
    documentMode: 'editing',
    onReady: ({ superdoc }) => {
      console.log('Ready!');
    }
  });
}

Collaboration Setup

import * as Y from 'yjs';
import { WebsocketProvider } from 'y-websocket';
import { SuperDoc } from 'superdoc';

const ydoc = new Y.Doc();
const provider = new WebsocketProvider(
  'wss://your-server.com',
  'document-id',
  ydoc
);

const superdoc = new SuperDoc({
  selector: '#editor',
  document: file,
  modules: {
    collaboration: {
      ydoc,
      provider
    }
  }
});

AI Integration

const superdoc = new SuperDoc({
  selector: '#editor',
  document: file,
  modules: {
    ai: {
      apiKey: 'your-api-key',
      endpoint: 'https://api.example.com/ai'
    }
  }
});

Comments Module

const superdoc = new SuperDoc({
  selector: '#editor',
  document: file,
  user: { name: 'John', email: '[email protected]' },
  users: [
    { name: 'Jane', email: '[email protected]' },
    { name: 'Bob', email: '[email protected]' }
  ],
  modules: {
    comments: {
      enabled: true
    }
  }
});

Error Handling

const superdoc = new SuperDoc({
  selector: '#editor',
  document: file,
  onContentError: (event) => {
    console.error('Failed to parse document:', event);
  },
  onException: ({ error }) => {
    console.error('Runtime error:', error);
  }
});

Architecture Notes

SuperDoc has two rendering systems:

| Mode | System | Description | |------|--------|-------------| | Editing | super-editor | ProseMirror-based rich text editing | | Viewing | layout-engine | Virtualized DOM rendering for presentation |

Both systems work together to provide seamless editing and viewing experiences.

Requirements

| Requirement | Version | |-------------|---------| | Node.js | 16+ | | Modern browser | ES2020 support |

Examples

| Example | Description | |---------|-------------| | React + TypeScript | React wrapper usage | | Next.js SSR | Next.js App Router |

For React/Next.js projects, prefer @superdoc-dev/react wrapper over core package.

Links

• Documentation
• Configuration
• Methods
• GitHub
• npm