superdoc-react

name	superdoc-react
description	React integration guidelines for SuperDoc document editor. Use when adding document editing capabilities to React or Next.js applications, working with DOCX files, or implementing collaboration features. Triggers on tasks involving document editors, DOCX handling, or SuperDoc integration.
license	MIT
metadata	{"author":"superdoc-dev","version":"1.0.0"}

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 (
    <SuperDocEditor
      document={file}
      documentMode="editing"
      onReady={() => 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<{ name, email, image? }>	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<SuperDocRef>(null);

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

  return <SuperDocEditor ref={editorRef} document={file} />;
}

Available Methods

Method	Returns	Description
getInstance()	SuperDoc | null	Access underlying instance
setDocumentMode(mode)	void	Change mode without rebuild
export(options?)	Promise<Blob | void>	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<DocumentMode>('editing');

  return (
    <>
      <button onClick={() => setMode('viewing')}>View</button>
      <button onClick={() => setMode('editing')}>Edit</button>
      <SuperDocEditor document={file} documentMode={mode} />
    </>
  );
}

File Upload

function FileEditor() {
  const [file, setFile] = useState<File | null>(null);

  return (
    <>
      <input
        type="file"
        accept=".docx"
        onChange={(e) => setFile(e.target.files?.[0] || null)}
      />
      {file && <SuperDocEditor document={file} />}
    </>
  );
}

Loading State

<SuperDocEditor
  document={file}
  renderLoading={() => <div className="spinner">Loading...</div>}
  onReady={() => console.log('Ready!')}
/>

View-Only Mode

<SuperDocEditor
  document={file}
  documentMode="viewing"
  role="viewer"
  hideToolbar
/>

With User Info

<SuperDocEditor
  document={file}
  user={{
    name: 'John Doe',
    email: '[e-mail]',
    image: 'https://example.com/avatar.jpg'
  }}
  users={[
    { name: 'Jane Smith', email: '[e-mail]' },
    { name: 'Bob Wilson', email: '[e-mail]' },
  ]}
/>

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 (
    <SuperDocEditor
      document="/sample.docx"
      documentMode="editing"
      style={{ height: '100vh' }}
    />
  );
}

Pages Router

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

export default function EditorPage() {
  return (
    <SuperDocEditor
      document="/sample.docx"
      documentMode="editing"
      style={{ height: '100vh' }}
    />
  );
}

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: () => <div>Loading editor...</div>
  }
);

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 (
    <html>
      <body>{children}</body>
    </html>
  );
}

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 (
    <SuperDocEditor
      document={file}
      modules={{
        collaboration: { ydoc, provider },
      }}
    />
  );
}

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