Chrome and toolbars
Use the built-in ribbon or build your own toolbar.
All UI the SDK draws around the document is optional. Every control's action is also available from the handle.
Optional chrome#
| Chrome | Prop | Default | Drive it yourself with |
|---|---|---|---|
| Tab strip | showTabs | off | documents |
| Title bar | showTitleBar | on | view |
| Ribbon | toolbarMode | "native" | toolbar |
| Editing/Suggesting toggle | showDocumentModeToggle | off | view.setDocumentMode() |
| Comments panel | None | None | view.setCommentsOpen() |
The comments panel has no built-in button. Comment chips render next to the page, and your UI opens or closes the panel.
Ribbon modes#
toolbarMode | What it renders |
|---|---|
"native" | The full ribbon. |
"compact" | The everyday-formatting subset, centered, for narrow fixed-width hosts (about 760px): undo and redo, font, size, styles, paragraph, links, indents, lists, Find, and Export. |
"floating" | The full ribbon as a centered card over the canvas, as in the Revise app. |
"none" | No toolbar. Build your own (below). |
Custom toolbar#
Set toolbarMode="none", subscribe to toolbar state, and render your own
controls:
const [state, setState] = useState<ReviseToolbarState | null>(null);
const editor = useRef<ReviseEditorHandle | null>(null);
<ReviseEditor
initialDocuments={docs}
toolbarMode="none"
showTitleBar={false}
onReady={(handle) => {
editor.current = handle;
handle.toolbar.subscribe(setState);
}}
/>;
<button
aria-pressed={state?.formatting.bold ?? false}
disabled={!state?.ready}
onClick={() => editor.current?.toolbar.toggleBold()}
>
Bold
</button>;ReviseToolbarState includes:
ready, readOnly, documentMode, hasSelection, canUndo/canRedo, the
formatting marks at the caret, heading, alignment, lineSpacing,
fontSizePt, the current blockType, and a review summary.
Subscribe once and call the returned unsubscribe function on unmount. State is published on every selection change.
Toolbar commands#
Clipboard and history
undo, redo, copy, copyAs("plaintext" | "markdown" | "html"), cut,
paste, pasteTextOnly, pasteFormattingOnly
Inline formatting
toggleBold, toggleItalic, toggleUnderline, toggleStrikethrough,
toggleDoubleStrikethrough, toggleSmallCaps, toggleAllCaps,
toggleCode, toggleLatex, toggleSuperscript, toggleSubscript,
clearFormatting, setFontFamily, setFontSize, setLetterSpacing,
setTextColor, setHighlightColor
Paragraph and block
setHeading, setAlignment, setLineSpacing, toggleList, createLink,
increaseIndent, decreaseIndent
Insertion
insertTable, insertImage, insertContainer, insertCodeBlock,
insertMathBlock, insertDiagram, insertFootnote, insertPageNumber,
insertPageBreak, insertSectionBreak
Review
openReview, closeReview, reviewPrevious, reviewNext,
acceptCurrent, rejectCurrent, acceptAll, rejectAll,
setShowRemovals, setSuggestionViewMode
A command returns false when it cannot apply, for example in a read-only
document, with no selection, or with nothing to undo.
View controller#
The view controller sets the title, document mode, and panels:
const { title, documentMode, commentsOpen, reviewOpen, reviewTargetCount } =
editor.view.getState();
editor.view.setTitle("Master Services Agreement");
editor.view.setDocumentMode("suggesting");
editor.view.setReviewOpen(true);
editor.view.setCommentsOpen(true);An Editing/Suggesting toggle:
const suggesting = view?.documentMode === "suggesting";
<button
data-active={suggesting}
onClick={() =>
editor.current?.view.setDocumentMode(suggesting ? "editing" : "suggesting")
}
>
{suggesting ? "Suggesting" : "Editing"}
</button>;Narrow hosts#
The editor lays out real pages, so on a phone-width host the choice is between
a whole page that is small and a readable page you pan across. Measured in
Chromium with toolbarMode="compact" and a Letter page:
| Host width | Page at fit width (default) | With the comments panel open | At zoom.setZoom(1) |
|---|---|---|---|
| 390px | 350px wide (43%) | 150px (18%) | 816px, pans horizontally |
| 420px | 380px (47%) | 180px (22%) | 816px, pans horizontally |
| 768px | 728px (89%) | 405px (50%) | 816px, pans horizontally |
What works below about 600px:
- Keep the built-in comments panel closed. It keeps at least 200px beside
the page, which leaves the page a third of its closed width. Render threads
in your own sheet instead:
review.getState().commentThreadslists them,review.subscribe()keeps the list current, andreview.selectComment(thread.root.id, { openPanel: false })puts the caret at a thread's text and makes it the active thread without opening the panel. - Offer a reading zoom.
zoom.setZoom(1)(or1.25) gives full-size text; the page scrolls horizontally inside the editor.zoom.fitWidth()returns to the whole page.zoom.subscribe()reportsscalefor your zoom control. - Use
toolbarMode="compact"from about 760px down, and"none"with your own controls on phones. The compact ribbon does not wrap; on a host narrower than its controls, the trailing ones are clipped. - Put your own sheets and modals above the editor with any z-index. The editor is its own stacking context, so its comment cards and other inline layers never cover host UI outside it. Its dialogs and menus render in a portal root at the top of the page, above host content, while they are open.
This is a paginated editor at a small scale, not a reflowing mobile layout. Touch gestures (pinch zoom, long-press selection), on-screen keyboards and screen readers are not covered by these measurements.
Built-in tabs#
Turn on the built-in document tabs with showTabs:
<ReviseEditor
showTabs
onNewTab={() => openBlankDocument()}
initialDocuments={docs}
/>The + button renders only when you pass onNewTab.
Focus#
The editor takes keyboard focus when a document becomes active. To focus it
only on click, for example in a preview or split view, set autoFocus={false}:
<ReviseEditor autoFocus={false} initialDocuments={docs} />