# Build a custom UI

> Keep SuperDoc's DOCX canvas while your application renders task-specific controls.



Build a custom UI when your product needs focused controls or workflows around a DOCX document. SuperDoc continues to
render the document and handle editing. Your application renders the toolbar, panels, and other controls it needs.

> **Diagram: the custom UI ownership boundary**
>
> SuperDoc renders the document, layout, selection, and editing behavior. The application renders the controls around it — a toolbar above, panels beside. Reactive state (selection, command state, comments) flows out of the editor to those controls, and commands and document operations flow back in.


You can replace one surface or the complete interface. For example, keep the built-in toolbar while rendering your own
comments panel, or set `ui: false` and render every control yourself.

## Choose the right surface [#choose-the-right-surface]

| You need to                                | Use           |
| ------------------------------------------ | ------------- |
| Choose which built-in surfaces render      | `Config.ui`   |
| Observe UI state and run Editor actions    | `superdoc.ui` |
| Read or mutate an explicit document target | `editor.doc`  |
| Decide which interactions are allowed      | `interaction` |

These surfaces work together. Setting `ui: { comments: false }` removes SuperDoc's comments interface, but your custom
panel can still use `superdoc.ui.comments`. The `interaction` configuration decides whether that panel may read, write,
or resolve comments.

`superdoc.ui` is the controller. Import its types from `superdoc/ui`. React applications use the provider and hooks from
`superdoc/ui/react`, and Vue applications use the composables from `superdoc/ui/vue`. Each binding exposes the same
controller.

## Try one custom control [#try-one-custom-control]

Select text in the document, then choose **Bold**. The application-owned button observes the command's live state and
executes the action through the same controller as SuperDoc's built-in toolbar.

> **Live example: one custom control on a real document**
>
> A Bold button rendered by the application, running against a real Editor. It reads `enabled` and `active` from the `bold` command handle, sets `disabled` and `aria-pressed` from those values rather than inspecting the selection, and reports the outcome from what `executeAsync()` resolves with. `CommandExecutionResult` is `boolean | receipt`, so both shapes are handled.


The control follows one reusable pattern: observe state, render it, execute the action, and inspect the result. The
[custom UI example](https://go.superdoc.dev/examples/custom-ui) contains the complete runnable project.

## Follow the core path [#follow-the-core-path]

If this is your first custom UI, read these guides in this order:

1. [Build your first custom control](/editor/custom-ui/controller-setup) and move Bold into your application.
2. [Keep commands and controls in sync](/editor/custom-ui/commands-and-state) as the selection changes.
3. [Build a custom toolbar](/editor/custom-ui/formatting-controls) with a toggle and value pickers.
4. [Add document controls](/editor/custom-ui/zoom-and-document-state) for zoom and DOCX download.

Only the first guide is a prerequisite. It establishes the controller setup the rest build on, so you can stop after
any step. Step 2 explains how command state stays in sync and asks you to change nothing; steps 3 and 4 each replace
that setup's Editor code rather than the guide before it.

Steps 3 and 4 take the toolbar in different directions and are alternatives rather than a sequence: the custom toolbar
owns the toolbar markup outright, while document controls keep SuperDoc's toolbar and remove only Zoom. Read both before
combining them.

## Choose a workflow [#choose-a-workflow]

After the first control, choose only the workflows your product needs. These guides are independent unless a page names
a prerequisite.

| Your application needs to                                    | Guide                                                              |
| ------------------------------------------------------------ | ------------------------------------------------------------------ |
| Own the comment thread list and actions                      | [Comments](/editor/custom-ui/comments)                             |
| Own the queue for accepting or rejecting revisions           | [Track changes](/editor/custom-ui/tracked-changes)                 |
| Navigate and edit structured document fields                 | [Content controls](/editor/custom-ui/content-controls)             |
| Own a visual find and replace session                        | [Search](/editor/custom-ui/search)                                 |
| Replace the menu shown for a pointer or keyboard interaction | [Context menu](/editor/custom-ui/context-menus)                    |
| Show table actions that follow the active cell               | [Tables](/editor/custom-ui/tables)                                 |
| Position an AI prompt beside selected text                   | [Selection and position](/editor/custom-ui/selection-and-viewport) |
| Turn an application finding into a tracked suggestion        | [Review findings](/editor/custom-ui/review-highlights)             |
| Share one application action across multiple controls        | [Custom commands](/editor/custom-ui/custom-commands)               |

Use [Dialogs and surfaces](/editor/dialogs-and-surfaces) when your application only needs content in a SuperDoc-managed
layer. Use [Theming](/editor/theming) to apply product colors to SuperDoc UI.