# 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 [#try-the-built-in-overlay]

Select **Replay loading**. SuperDoc opens the document again and keeps the existing content covered until the
replacement is ready.

> **Interactive editor: Try document loading**
>
> Sample: [open the fixture](/fixtures/loading-sample.docx).
>
> Preset: `loading`.
>
> Loading behavior available in the interactive Editor:
>
> - **Built-in overlay — `ui.loading`:** enabled by default. It reports real document progress and stays visible until the Editor is ready.
> - **Replay loading:** opens the fixture again through `replaceFile()` so the same overlay covers a document replacement.
>
> Local DOCX selection: disabled.


## Keep the built-in progress overlay [#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:

```tsx
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 [#show-application-loading-ui]

In React, pass `renderLoading` to replace the initial loading experience. The wrapper hides the Editor until `onReady`:

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

```html
<p id="document-status" role="status">Opening document…</p>
<div id="editor" hidden></div>

```

```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');

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 [#configure-the-overlay]

Choose the field to see its generated TypeScript signature and copy a focused configuration fragment.

### Overlay

| Field | Type | Default | Status | Summary | API details | Guide |
| --- | --- | --- | --- | --- | --- | --- |
| `loading` | `boolean` | `true` | Optional | Choose whether SuperDoc renders the document loading overlay. | 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(...)`. | — |


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 [#continue-to-custom-ui]

Use [Custom UI](/editor/custom-ui/overview) when your application should own loading alongside the toolbar, comments,
review controls, and other Editor chrome.