Editor widget
DocumentEditor from package:vyuh_document_editor/document_editor.dart takes three independent settings: the controller (content), the surface (where it shows) and the chrome (which controls).
dart
DocumentEditor(
extensions: DocumentEditorElements.defaults,
controller: controller, // content
surface: const DocumentSurface.field(minLines: 3, maxLines: 8),
chrome: EditorChrome.floating,
focusNode: focusNode, // optional
autofocus: true,
);Try them live: line, field, notes, pages.
Anatomy of the full editor
With every part of the chrome switched on, the editor becomes a workspace.
What the editor holds
State what the editor holds once. Either list the extensions and read the configuration from them, or pick a preset configuration and read the extensions from it. Never write both lists.
dart
// From extensions: the configuration follows.
const extensions = [...DocumentExtension.richText, ListDocumentExtension()];
final controller = DocumentController(documentConfigurationOf(extensions));
// From a preset: the extensions follow.
final extensions = DocumentEditorElements.forConfiguration(writingConfiguration);
final controller = DocumentController(writingConfiguration);The presets grow from the leanest editor to the full document:
| Preset | Adds |
|---|---|
paragraphsConfiguration | Paragraphs and marks |
writingConfiguration | Headings and lists |
notesConfiguration | Checklists, code, images, quotes, dividers, tables, page and column breaks |
documentConfiguration | Footnotes and endnotes, equations, diagrams, shapes, text boxes, contents, fields |
An element's declaration lives in one place: its canonical definition. The editor refuses to mount a configuration that names an element no installed extension serves.
Surfaces
DocumentSurface | Shows |
|---|---|
.line(onSubmit:) | One line; Enter calls onSubmit |
.field(minLines: 1, maxLines:) | Grows with its content, then scrolls |
.pageless(maxWidth:) | A continuous column |
.pages() | Physical pages, as printed (default) |
Switching between pageless and pages keeps the document, the selection, the Undo history and the line being read. Both layouts show the same document:
| In the document | On pages | In pageless |
|---|---|---|
| Header, footer, watermark, line numbers, columns | Shown | Kept, not shown |
| Sections | Each with its own page setup | One continuous column |
Page break, column break, page break before | Start a new page or column | Kept; the text follows on |
| Floating images, tables, shapes and text boxes | Placed and wrapped | Shown in the flow, in document order |
| Drop cap | Enlarged first letter | Ordinary text |
| Page number and page count fields | The page's value | Empty |
| Footnotes and endnotes | Marker and note body | Marker only |
| Table of contents | Entries with page numbers | Entries without page numbers |
Actions and properties that only have an effect on pages (insert a note, a header or a section break, page setup, a paragraph's pagination rules) are disabled in pageless and say "Available in page view". The engine refuses the same edits, and Undo and Redo are never refused.
PDF, DOCX and print always use pages. From a pageless editor, withPagedExportLayout lays the same document out on pages off-screen for the export and leaves the visible surface, its camera and its selection alone:
dart
final bytes = await withPagedExportLayout(
overlay: Overlay.of(context),
controller: controller,
canvas: canvas,
export: (paged, pagedCanvas) async {
final generation = await waitForCurrentExportLayout(
controller: paged,
canvas: pagedCanvas,
);
// Encode `generation` with the PDF or DOCX codec.
return encode(paged, generation);
},
);See Multiline input and breaks for paragraph/soft breaks, pageless indicators, typed boundary elements and source examples.
textInput: DocumentTextInputConfiguration(...) customizes native keyboard preferences. contextMenu: DocumentContextMenuConfiguration(presenter: ...) uses a host menu over the editor's targeted action rows. Both settings are independent of surface and chrome. See Behavior and configuration for complete source examples and lifecycle guarantees.
Empty documents and blocks
Placeholders are owned by block editor extensions. The paragraph extension shows “Start writing…” for a single empty body block, including while focused. Code, checklist and quote extensions supply prompts for their empty blocks. Typing, whitespace or inline content hides the corresponding hint; clearing or undoing back to empty restores it.
Default hints use a 5.2-second loop: a gesture, clipped text reveal, three trailing dots, and a reading pause. The pen follows the revealed text and returns to its slot; code draws brackets, lists and checklists draw lines, and quotes draw quote marks. The label's box stays fixed. Reduced motion and disabled tickers show the complete static hint. Labels without trailing dots keep their original text. No animation package or asset is required. The placeholder guide includes the defaults for each block, a complete extension-list example, custom widget configuration and live demos.
Choose an animated hint, plain text, a custom widget builder or null to hide hints for one block owner. Pass the configured owners through the ordered extensions list on DocumentEditor (typed API) or DocumentEditorController (host API). Replace the matching default entry instead of appending a duplicate.
Hints follow the resolved text typography, baseline, alignment and zoom. They are hidden in read-only modes and never enter saved content, clipboard payloads, undo history or exports.
Chrome
EditorChrome | Shows |
|---|---|
EditorChrome.none | The document alone (default) |
EditorChrome.floating | A format bubble over a text selection |
EditorChrome.toolbar(Toolbar([...])) | A toolbar row of typed parts |
EditorChrome(toolbar:, bubble:) | A row and a bubble |
EditorChrome.full | The whole command toolbar, with rulers over pages |
Toolbar parts
| Part | Shown when the configuration has |
|---|---|
BoldButton, ItalicButton, UnderlineButton, StrikeButton, SuperscriptButton, SubscriptButton | That mark |
LinkButton | Any mark |
HeadingButton(level:) | Heading |
ListButton(ordered:) | ListItem |
TableButton | Table |
UndoButton, RedoButton | Always |
ActionButton(id) | The registered action id has an icon |
Toolbar.formatting and Toolbar.standard are presets. A part runs the same registered action as its shortcut and the command palette. Toolbars, menus, shortcuts and paste offer only the configuration's elements.
Your own actions
Add your own actions as one more extension, and name them in a toolbar with ActionButton. A host-owned DocumentActionCatalog passed as actions: lists every action of the editor with its state and runs one by ID, for controls you build yourself. It fills in when the editor mounts.
dart
final catalog = DocumentActionCatalog();
final share = DocumentHostExtension(
id: 'app.share',
register: (registry) => registry.registerAction(shareAction),
);
DocumentEditor(
controller: controller,
extensions: [...DocumentEditorElements.defaults, share],
actions: catalog,
chrome: EditorChrome.toolbar(
const Toolbar([BoldButton(), ActionButton(AppActionId.share)]),
),
// The one comment prompt; Add comment is offered only with it.
commentComposer: (controller, selection) => askForComment(),
);See Host extensions and The action catalog.
Links
LinkButton and Command/Ctrl + K open the link dialog for the selection. Hover a link, or move the caret into it, to open, copy, edit or remove it.
Host bindings
For image resolvers, fonts, your own link dialog, review modes, PDF export or the Properties inspector, use DocumentEditorController with DocumentEditor from vyuh_document_editor.dart. The tutorial shows the switch.
Next
- Tutorial step 2: toolbar and structure.
- Toolbar: the runtime toolbar configuration.