# Superdoc React

> 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.

- **Type:** Skill
- **Install:** `agentstack add skill-superdoc-dev-agent-skills-superdoc-react`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [superdoc-dev](https://agentstack.voostack.com/s/superdoc-dev)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [superdoc-dev](https://github.com/superdoc-dev)
- **Source:** https://github.com/superdoc-dev/agent-skills/tree/main/skills/superdoc-react

## Install

```sh
agentstack add skill-superdoc-dev-agent-skills-superdoc-react
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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

```bash
npm install @superdoc-dev/react
```

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

## Quick Start

```tsx
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:

```tsx
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:

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

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

### File Upload

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

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

### Loading State

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

### View-Only Mode

```tsx

```

### With User Info

```tsx

```

## Next.js Integration

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

### App Router (Next.js 13+)

```tsx
// 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

```tsx
// 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:

```tsx
'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:

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

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

## Collaboration Setup

```tsx
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

```tsx
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](https://github.com/superdoc-dev/superdoc/tree/main/examples/getting-started/react) | File upload, mode switching, export |
| [Next.js SSR](https://github.com/superdoc-dev/superdoc/tree/main/examples/integrations/nextjs-ssr) | App Router with SSR support |

## Links

- [Documentation](https://docs.superdoc.dev/getting-started/frameworks/react)
- [Next.js Guide](https://docs.superdoc.dev/getting-started/frameworks/nextjs)
- [GitHub](https://github.com/superdoc-dev/superdoc)
- [npm](https://www.npmjs.com/package/@superdoc-dev/react)

## 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](https://github.com/superdoc-dev)
- **Source:** [superdoc-dev/agent-skills](https://github.com/superdoc-dev/agent-skills)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-superdoc-dev-agent-skills-superdoc-react
- Seller: https://agentstack.voostack.com/s/superdoc-dev
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.