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. This minimal example uses
public/sample.docx from the Quickstart:
import { SuperDocEditor } from '@superdoc/react';
import '@superdoc/react/style.css';
export default function App() {
return <SuperDocEditor document='/sample.docx' onReady={() => console.log('Document ready')} />;
}
Wait for onReady before enabling actions that depend on the document.
Show application loading UI
The following are standalone alternatives in the Quickstart project, using the same public/sample.docx.
In React, replace src/App.tsx below. renderLoading replaces 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='/sample.docx'
renderLoading={() =>
loadFailed ? (
<p role='alert'>Could not open the document. Reload the page to retry.</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.
Replace the body content in index.html below, keeping the script that loads /src/main.ts:
<label>Open another DOCX <input id="document-file" type="file" accept=".docx" disabled /></label>
<p id="document-status" role="status">Opening document…</p>
<div id="editor" hidden></div>
Replace src/main.ts:
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');
const fileInput = requireElement<HTMLInputElement>('#document-file');
let hasOpened = false;
let replacing = false;
function showLoading() {
fileInput.disabled = true;
editor.hidden = true;
status.hidden = false;
status.textContent = 'Opening document…';
}
function showEditor() {
hasOpened = true;
fileInput.disabled = replacing;
status.hidden = true;
editor.hidden = false;
}
function showError(error: unknown) {
console.error('Could not open the document.', error);
fileInput.disabled = !hasOpened || replacing;
editor.hidden = true;
status.hidden = false;
status.textContent = hasOpened
? 'Could not open the document. Choose another DOCX to retry.'
: 'Could not open the document. Reload the page to retry.';
}
const superdoc = new SuperDoc({
selector: editor,
document: '/sample.docx',
ui: { loading: false },
onReady: showEditor,
onContentError: ({ error }) => showError(error),
onException: (payload) => {
const runtimeOnly = 'itemName' in payload || 'source' in payload || 'diagnosticCode' in payload;
if (!hasOpened && !runtimeOnly) showError(payload.error);
else console.error('SuperDoc reported an exception.', payload);
},
});
async function replaceDocument(file: File) {
if (replacing) return;
replacing = true;
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);
} finally {
replacing = false;
fileInput.disabled = !hasOpened;
}
}
fileInput.addEventListener('change', () => {
const file = fileInput.files?.[0];
if (file) void replaceDocument(file);
fileInput.value = '';
});
window.addEventListener('beforeunload', () => superdoc.destroy());
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.
Reload to see the initial loading message. In Vanilla, choose another DOCX with the file picker and confirm the message returns while it opens. If a replacement fails, choose another DOCX to retry. If the initial document fails to open, reload the page. Unrelated runtime exceptions are logged without hiding a ready 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.