Superdoc React

SuperDoc React Integration

Official React wrapper for SuperDoc - the document editing and rendering library for the web. Provides component-based API with proper lifecycle management and React Strict Mode compatibility.

When to Apply

Reference these guidelines when:

• Adding document editing to a React application
• Integrating SuperDoc with Next.js
• Implementing DOCX file upload/export
• Setting up real-time collaboration
• Building document viewers or editors

Installation

npm install @superdoc-dev/react

> superdoc is included as a dependency - no separate installation needed.

Quick Start

import { SuperDocEditor } from '@superdoc-dev/react';
import '@superdoc-dev/react/style.css';

function App() {
  return (
     console.log('Editor ready!')}
    />
  );
}

Component API

Document Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | document | File \| Blob \| string \| object | required | Document to load | | documentMode | 'editing' \| 'viewing' \| 'suggesting' | 'editing' | Editing mode | | role | 'editor' \| 'viewer' \| 'suggester' | 'editor' | User permissions |

User Props

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

UI Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | id | string | auto-generated | Custom container ID | | hideToolbar | boolean | false | Hide the toolbar | | rulers | boolean | - | Show/hide rulers | | className | string | - | CSS class for wrapper | | style | CSSProperties | - | Inline styles | | renderLoading | () => ReactNode | - | Custom loading UI |

Event Callbacks

| Prop | Type | Description | |------|------|-------------| | onReady | ({ superdoc }) => void | Editor 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 |

Advanced Props

| Prop | Type | Description | |------|------|-------------| | modules | object | Configure collaboration, AI, comments |

Ref API

Access SuperDoc methods via ref:

import { useRef } from 'react';
import { SuperDocEditor, SuperDocRef } from '@superdoc-dev/react';

function Editor() {
  const editorRef = useRef(null);

  const handleExport = async () => {
    await editorRef.current?.getInstance()?.export({ triggerDownload: true });
  };

  return ;
}

Available Methods

| Method | Returns | Description | |--------|---------|-------------| | getInstance() | SuperDoc \| null | Access underlying instance | | setDocumentMode(mode) | void | Change mode without rebuild | | export(options?) | Promise | Export as DOCX | | getHTML(options?) | string[] | Get document as HTML | | focus() | void | Focus the editor | | search(text) | SearchResult[] | Search document | | goToSearchResult(match) | void | Navigate to result | | setLocked(locked) | void | Lock/unlock editing | | toggleRuler() | void | Toggle ruler visibility |

Common Patterns

Document Mode Switching

The component handles documentMode prop changes efficiently without rebuilding:

function Editor() {
  const [mode, setMode] = useState('editing');

  return (
    <>
       setMode('viewing')}>View
       setMode('editing')}>Edit
      
    
  );
}

File Upload

function FileEditor() {
  const [file, setFile] = useState(null);

  return (
    <>
       setFile(e.target.files?.[0] || null)}
      />
      {file && }
    
  );
}

Loading State

 Loading...}
  onReady={() => console.log('Ready!')}
/>

View-Only Mode

With User Info

Next.js Integration

The React wrapper handles SSR automatically (renders null or renderLoading() on server, initializes after hydration).

App Router (Next.js 13+)

// app/editor/page.tsx
'use client';

import { SuperDocEditor } from '@superdoc-dev/react';
import '@superdoc-dev/react/style.css';

export default function EditorPage() {
  return (
    
  );
}

Pages Router

// pages/editor.tsx
import { SuperDocEditor } from '@superdoc-dev/react';
import '@superdoc-dev/react/style.css';

export default function EditorPage() {
  return (
    
  );
}

With Dynamic Import (Optional)

For custom loading UI during SSR:

'use client';

import dynamic from 'next/dynamic';

const SuperDocEditor = dynamic(
  () => import('@superdoc-dev/react').then(mod => mod.SuperDocEditor),
  {
    ssr: false,
    loading: () => Loading editor...
  }
);

CSS Import in Layout

Import styles once in your layout:

// app/layout.tsx
import '@superdoc-dev/react/style.css';

export default function RootLayout({ children }) {
  return (
    
      {children}
    
  );
}

Collaboration Setup

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

function CollaborativeEditor() {
  const ydoc = useMemo(() => new Y.Doc(), []);
  const provider = useMemo(
    () => new WebsocketProvider('wss://your-server.com', 'doc-id', ydoc),
    [ydoc]
  );

  return (
    
  );
}

Props That Trigger Rebuild

These props trigger a full instance rebuild when changed:

| Prop | Reason | |------|--------| | document | New document to load | | user | User identity changed | | users | Users list changed | | modules | Module configuration changed | | role | Permission level changed | | hideToolbar | Toolbar DOM structure changed |

Other props like documentMode and callbacks are handled efficiently without rebuild.

TypeScript

import type {
  SuperDocEditorProps,
  SuperDocRef,
  DocumentMode,
  UserRole,
  SuperDocUser,
  SuperDocModules,
  SuperDocConfig,
  SuperDocInstance,
} from '@superdoc-dev/react';

Types are extracted from the superdoc package, ensuring they stay in sync.

Requirements

| Requirement | Version | |-------------|---------| | React | 16.8.0+ | | Node.js | 16+ |

Examples

| Example | Description | |---------|-------------| | React + TypeScript | File upload, mode switching, export | | Next.js SSR | App Router with SSR support |

Links

• Documentation
• Next.js Guide
• GitHub
• npm

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: superdoc-dev
• Source: superdoc-dev/agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.