Quick Start

Learn how to install and set up SuperDoc, the modern collaborative document editor for the web.

SuperDoc is a powerful document editor that brings Microsoft Word-level capabilities to your web applications. With real-time collaboration, extensive formatting options, and seamless integration capabilities, SuperDoc makes document editing on the web better for everyone.

Introduction

SuperDoc is an open source document editor bringing Microsoft Word capabilities to the web with real-time collaboration, extensive formatting options, and easy integration.

Key Features

• Document Compatibility: View and edit DOCX and PDF (view only) documents directly in the browser
• Microsoft Word Integration: Full support for importing/exporting, advanced formatting, comments, and tracked changes
• Real-time Collaboration: Built-in multiplayer editing, live updates, commenting, sharing, and revision history
• Framework Agnostic: Seamlessly integrates with Vue, React, or vanilla JavaScript
• Extensible Architecture: Modular design makes it easy to extend and customize
• Dual License: Available under AGPLv3 for community use and Commercial license for enterprise deployments

Installation

Package Installation

npm install @harbour-enterprises/superdoc

CDN Usage

You can also use SuperDoc directly from a CDN:

<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/@harbour-enterprises/superdoc/dist/style.css" />
<script
  src="https://cdn.jsdelivr.net/npm/@harbour-enterprises/superdoc/dist/superdoc.es.js"
  type="module"></script>

Basic Usage

import '@harbour-enterprises/superdoc/style.css';
import { SuperDoc } from '@harbour-enterprises/superdoc';

const superdoc = new SuperDoc({
  selector: '#superdoc',
  toolbar: '#superdoc-toolbar',
  document: '/sample.docx', // URL, File or document config
  documentMode: 'editing',
  pagination: true,
  rulers: true,
  onReady: (event) => {
    console.log('SuperDoc is ready', event);
  },
  onEditorCreate: (event) => {
    console.log('Editor is created', event);
  },
})

Configuration Options

const config = {
  // Optional: Give the superdoc an id
  superdocId: 'my-superdoc-id',

  // Optional: SuperDoc title
  title: 'My SuperDoc',

  // Required: A DOM element ID to render superdoc into
  selector: '#superdoc',

  // Optional: Initial document mode: viewing, suggesting,editing. Defaults to editing
  documentMode: 'editing',

  // Optional: User role: editor, suggester, viewer. Defaults to editor
  role: 'editor',

  // Required: URL, File or document config
  document: '/sample.docx',

  // Optional: For enterprise users, set the license key
  licenseKey: 'community-and-eval-agplv3',

  // Optional: Enable telemetry to help us improve SuperDoc
  telemetry: {
    enabled: true,
  },

  // Optional: The current user
  user: {
    name: 'Superdoc User',
    email: 'superdoc@example.com',
    image: 'image-url.jpg',
  },

  // Optional: A DOM element ID to render the toolbar into
  toolbar: 'superdoc-toolbar',

  // Optional: modules
  modules: {
    // The collaboration module
    collaboration: {
      url: 'wss://your-collaboration-server.com', // Required: Path to your collaboration backend
      token: 'your-auth-token', // Required: Your auth token
    },
    
    // Toolbar config, overrides the 'toolbar' key, if provided, above
    toolbar: {
      selector: 'superdoc-toolbar',
    },

    // More coming soon
  },

  // Optional: pagination
  pagination: true,

  // Optional: rulers
  rulers: true,

  // Optional: events - pass in your own functions for each
    onEditorBeforeCreate: () => null,
    onEditorCreate: () => null,
    onEditorDestroy: () => null,
    onContentError: () => null,
    onReady: () => null,
    onPdfDocumentReady: () => null,
    onException: () => null,
};

Document Modes and Roles

SuperDoc supports different document modes and user roles to control editing capabilities:

Document Modes

• editing - Full document editing capabilities
• viewing - Read-only mode with no editing allowed
• suggesting - Track changes mode where edits are shown as suggestions

User Roles

• editor - Users with full editing capabilities who can access all document modes
• suggester - Users who can only make suggestions (track changes) but cannot directly edit
• viewer - Users with read-only access who can only view the document

The user's role restricts which document modes they can access. For example, a user with the "viewer" role will always be in viewing mode regardless of the requested document mode.

Project Structure

SuperDoc consists of two main packages:

/packages/super-editor  // Core editor component
/packages/superdoc      // Main SuperDoc package

SuperDoc Package

This is the main package (published to npm). It includes SuperEditor and provides the complete document editing experience.

cd packages/superdoc
npm install && npm run dev

This will run SuperdocDev.vue, with a Vue 3 based example of how to instantiate SuperDoc.

SuperEditor Package

This is the core DOCX editor and renderer (including the toolbar). It is included inside SuperDoc but can be used independently for advanced use cases.

cd packages/super-editor
npm install && npm run dev

Event Handling

SuperDoc provides a robust event system to handle various document interactions:

const superdoc = new SuperDoc({
  selector: '#superdoc',
  document: '/sample.docx',
});


// Remove event listeners
superdoc.off('ready', myReadyHandler);

Document Operations

// Export the document as DOCX
await superdoc.export();

// Switch between viewing, suggesting, and editing modes
superdoc.setDocumentMode('viewing');
superdoc.setDocumentMode('suggesting');
superdoc.setDocumentMode('editing');

// Get a list of HTML strings (one per DOCX editor)
superdoc.getHTML()

Accessibility

SuperDoc is built with accessibility in mind, providing comprehensive support for screen readers and keyboard navigation.

High contrast mode

You can enable/disable high contrast mode at any point after the editor is ready by calling the setHighContrastMode() function on the superdoc instance.

const config = {
  // ...
  onReady: (event) => {
    // Initialize high contrast mode
    event.superdoc.setHighContrastMode(true);
  },
  // ...
};

const editor = new SuperDoc(config);
// Or at any point later (if the editor is ready)
editor.setHighContrastMode(true);

ARIA Attributes

In order to give screen readers the contextual information about elements we use ARIA attributes for Toolbar and Editor components.

• role=application - Main app container.
• role=presentation - Editor wrapper.
• role=document - Prosemirror editor.
• role=textarea - Use it for header/footer editors.
• role=group - Grouped item's wrapper.
• role=toolbar - Super Toolbar component.

We use role=button for toolbar item on desktop and role=menuitem for overflow items. Meanwhile, we use role=menu for dropdown items (including overflow button).

• role=separator - Toolbar separator
• aria-label - used to provide information about the current focused item.
• aria-description - used to provide additional information about the current selected item.

We use semantic markup for elements like tables which are accessible by default.

Keyboard navigation

We allow users to navigate in SuperDoc using the keyboard, benefiting users with motor disabilities, those who prefer keyboard navigation, and others relying on assistive technologies. Once you open the page, you can Tab through until you reach the toolbar. The toolbar is separated in 3 groups and you can navigate between them by using Tab as well.

• When you're focused on a group, you can navigate using arrow keys.
• To select a toolbar item, press Enter. Depending on the item, it will either toggle it or open the dropdown in case there's an extra required action. For example, if you hit Enter on the "Bold" item, it will simply toggle it. But if it's a color picker, it will open the dropdown so you can select the color.
• If the selected item has a dropdown, you can navigate inside the dropdown also using arrow keys.
• To get back to the editor, you can simply tab through until the end of the toolbar and the next item will be the editor.
• To navigate back to the toolbar, you can use the following shortcut:
  • Windows: Ctrl + Shift + Alt + M
  • MacOS: Cmd + Shift + Option + M

Next Steps

• See Integration for framework-specific integration guides
• Explore Components for detailed component reference
• Check out Resources for examples, FAQ, and community resources