Choose a document loading UI
Keep SuperDoc's progress overlay or replace it with an application-owned loading state.
SuperDoc shows document progress while the Editor opens. Keep this default unless your application needs to own the entire loading experience.
Try the built-in overlay
Select Replay loading. SuperDoc opens the document again and keeps the existing content covered until the replacement is ready.
The document loading UI is loading.
Keep the built-in progress overlay
No configuration is required. The overlay follows real document progress and stays visible until the Editor is ready.
It also appears when replaceFile() opens another DOCX.
In React, omit renderLoading so the built-in overlay remains visible:
import { SuperDocEditor } from '@superdoc/react';
import '@superdoc/react/style.css';
export default function App() {
return <SuperDocEditor document='/contract.docx' onReady={() => console.log('Document ready')} />;
}
Wait for onReady before enabling actions that depend on the document.
Show application loading UI
In React, pass renderLoading to replace the initial loading experience. The wrapper hides the Editor until onReady:
'use client';
import { SuperDocEditor } from '@superdoc/react';
import '@superdoc/react/style.css';
import { useState } from 'react';
export default function App() {
const [loadFailed, setLoadFailed] = useState(false);
return (
<SuperDocEditor
document='/contract.docx'
renderLoading={() =>
loadFailed ? <p role='alert'>Could not open the document.</p> : <p role='status'>Opening document…</p>
}
onContentError={() => setLoadFailed(true)}
onException={() => setLoadFailed(true)}
/>
);
}
This fallback also appears when changing the document prop. It does not run for an imperative replaceFile() call;
the built-in overlay still covers that operation.
For Vanilla, set ui.loading: false only when your application covers both the initial open and every file replacement:
<p id="document-status" role="status">Opening document…</p>
<div id="editor" hidden></div>
import { SuperDoc } from 'superdoc';
import 'superdoc/style.css';
function requireElement<ElementType extends HTMLElement>(selector: string) {
const element = document.querySelector<ElementType>(selector);
if (!element) throw new Error(`${selector} not found.`);
return element;
}
const editor = requireElement<HTMLElement>('#editor');
const status = requireElement<HTMLElement>('#document-status');
function showLoading() {
editor.hidden = true;
status.hidden = false;
status.textContent = 'Opening document…';
}
function showEditor() {
status.hidden = true;
editor.hidden = false;
}
function showError(error: unknown) {
console.error('Could not open the document.', error);
editor.hidden = true;
status.hidden = false;
status.textContent = 'Could not open the document. Try again.';
}
const superdoc = new SuperDoc({
selector: editor,
document: '/contract.docx',
ui: { loading: false },
onReady: showEditor,
onContentError: ({ error }) => showError(error),
});
async function replaceDocument(file: File) {
showLoading();
try {
const result = await superdoc.replaceFile(file);
const state = result && typeof result === 'object' ? (result as { state?: unknown }).state : undefined;
const replaced = state === undefined || state === null || state === 'review-ready' || state === 'editing-ready';
if (!replaced) throw new Error('SuperDoc could not replace the document.');
showEditor();
} catch (error) {
showError(error);
}
}
export { replaceDocument };
Keep the application state visible until onReady. Around replaceFile(), keep it visible until the call returns a
ready state. If opening fails, replace the loading message with an error instead of revealing an incomplete Editor.
Configure the overlay
Choose the field to see its generated TypeScript signature and copy a focused configuration fragment.
loadingChoose whether SuperDoc renders the document loading overlay.
API details
Built-in loading overlay shown while a document opens. Enabled by default. Set to `false` to show your own loading UI instead. This only decides whether SuperDoc draws the overlay. It does not change how long a document takes to open, and it does not affect loading UI the host renders (such as `renderLoading` in `@superdoc/react`). The built-in overlay also masks the document while it opens. Turning it off hands that responsibility to your UI: keep yours up until `onReady`, and around a replacement await `superdoc.replaceFile(...)`.
1 field · generated from UIConfig
This reference covers the core Config option. React's renderLoading is a SuperDocEditor prop, so it remains in the
React example above.
Continue to custom UI
Use Custom UI when your application should own loading alongside the toolbar, comments, review controls, and other Editor chrome.