Developer guide

Embed a Word editor in React and Next.js

Build a React editing workflow with acknowledged saves, unsaved-change state and cleanup on unmount. Use the same component in a Next.js client boundary.

Run the complete React example

Open the React editor demo. Open a local DOCX, edit it, choose Save in this browser, then Open saved copy to restore it. Clear saved copy removes persisted bytes. The standard ribbon also downloads Word or PDF. The browser copy is manual storage, not automatic crash recovery or a server account.

git clone https://github.com/onodocs/onodocs.git
cd onodocs
npm install
npm start

Open the printed sample hub and choose React Word editor. Source: complete application.

Reuse the existing lifecycle component

Copy Editor.jsx and its sibling mount.js into your application. TypeScript applications can use mount.ts. The mount helper imports the browser editor after mounting and returns immediate cancellation and disposal, including during React Strict Mode.

npm install @onodocs/editor react react-dom
import { useMemo, useCallback, useRef } from "react";
import { Editor } from "./Editor.jsx";

export function DocumentEditor({ input, persist, onEvent, onError }) {
  const session = useRef();
  const options = useMemo(() => ({ input, persist, onEvent }), [input, persist, onEvent]);
  const onReady = useCallback(application => { session.current = application; }, []);
  return <>
    <button onClick={() => session.current?.save().catch(onError)}>Save</button>
    <div className="editor-host"><Editor options={options} onReady={onReady} /></div>
  </>;
}
.editor-host > div { height: 80vh; min-height: 28rem; }

Supply stable bytes and callbacks from the parent. Keep options and onReady stable so an ordinary render does not replace the document. The complete demo disables controls while opening/saving and displays errors and unsaved state. React owns the surrounding controls; the editor owns its empty host.

Connect real storage

persist(bytes, signal) must acknowledge successful storage and reject failures. Replace the demo IndexedDB callback with your authenticated endpoint; enforce authorization and conflicts on the server. See the GET/PUT integration. A 409/412 requires an explicit reload, save-as or conflict choice.

Default autosave debounces changes for 1000 ms. Use autosaveDelay: false for manual saving. Show onEvent state for dirty/saving and errors. Changes during a save remain dirty until their own revision succeeds. Ribbon downloads do not acknowledge application storage.

Recovery and document replacement

The optional recovery store checkpoints when saving begins. Scope it to user and document identity; ask before restoring a draft against newer stored content. Disposal cancels work without flushing it. Await saving or confirm discarding before replacing input or navigating away; a beforeunload warning cannot guarantee an asynchronous save.

Use a new session when identity changes. Direct editor open/new operations bypass application session tracking; keep its default restriction and replace the component input instead. Avoid restoring shared-device drafts across accounts and clear them under your retention policy.

Use a Next.js client boundary

Place the component and event callbacks in a module beginning with "use client". The helper defers browser imports until the effect; never mount during SSR. Fetch DOCX with cancellation, check response status, then place bytes in client state. Keep local File objects and functions in the client boundary.

The existing Next.js application shell demonstrates framework setup. For read-only rendering, use the React viewer guide.

Extend the application

Configure the ribbon, commands and theme, add forms or optional Agent assistance, or use collaborative sessions for shared records. Test representative files against the compatibility reference.