Toolbar shapes
Configure the compact toolbar through DocumentEditorConfiguration.toolbar: one or two rows, docked or floating, collapsible or not. On pages the toolbar always docks above the rulers; only a pageless editor floats it.
dart
import 'package:vyuh_document_editor/vyuh_document_editor.dart';
DocumentEditor buildToolbar(DocumentEditorController controller) =>
DocumentEditor(
controller: controller,
configuration: DocumentEditorConfiguration(
toolbar: DocumentToolbarConfiguration(
rows: DocumentWorkspaceToolbarRows.doubleRow,
placement: DocumentToolbarPlacement.floating,
collapsible: true,
initiallyExpanded: false,
actionIds: {
HistoryActionId.undo,
HistoryActionId.redo,
MarkActionId.bold,
MarkActionId.italic,
MarkActionId.underline,
},
),
),
);Choose visible controls
The toolbar shows installed actions. actionIds and groups narrow them, and menus gather some into a single trigger.
Action IDs are typed: each owner declares its own set (HistoryActionId.undo, MarkActionId.bold, TableActionId.insert, KatexActionId.insert), so a toolbar can only name an action that exists. See Typed identifiers.
Hiding is not removing. To remove an action from every surface, unregister it from a host extension; to give a key a new meaning, register an action with that chord or a key handler there.
Group related actions
DocumentToolbarConfiguration.menus takes DocumentToolbarMenuConfigurations. Each picks action IDs or groups, a label and a placement group; useActiveLabel shows the selected action on the trigger. An action in a menu is not also a button, and an empty menu disappears.
The default menu, DocumentToolbarMenuConfiguration.paragraphStyle, holds the paragraph and heading actions and previews each level's typography. Pass menus: const [] for one button per action.
Toolbar surface
decoration draws the toolbar's own surface. Every kind keeps the same insets, so tools never move when you switch.
| Decoration | Draws | Use it |
|---|---|---|
DocumentToolbarDecoration.divider() | One rule under the tools | Inside a bordered card (docked default) |
DocumentToolbarDecoration.filled(radius:) | A quiet tone fill | Docked on a plain background |
DocumentToolbarDecoration.elevated(radius:) | A card with one soft shadow | Floating (floating default) |
DocumentToolbarDecoration.outlined(radius:) | A card with a hairline outline | Standalone on a plain background |
DocumentToolbarDecoration.none() | Nothing | A host that frames the tools itself |
Pass the host's corner radius as radius to match it.
dart
DocumentEditorConfiguration(
toolbar: DocumentToolbarConfiguration(
collapsible: true,
// Inside a rounded card: no second outline beside the card's own border.
decoration: const DocumentToolbarDecoration.divider(),
),
)Your own controls
A host can drive the editor from its own buttons and palettes instead of the built-in toolbar. Turn the toolbar off with DocumentToolbarConfiguration.disabled() and build your controls over controller.actionCatalog: it lists every registered action with its label, icon, enabled and active state and shortcut, runs one by ID, and notifies when a state changes, so the host re-derives nothing. Your own actions join the same catalog through a host extension. The catalog fills in when the editor mounts. Try it live.
With the typed DocumentEditor, pass a DocumentActionCatalog as actions: for the same catalog, and name any registered action in a toolbar with ActionButton(id).
Choose your own order and grouping with Toolbar.grouped. These groups control presentation; the configured schema and current permissions still decide which actions are available. Duplicate actions appear once, at their first position, and empty groups disappear.
dart
const chrome = EditorChrome.toolbar(Toolbar.grouped([
ToolbarSection('History', [UndoButton(), RedoButton()]),
ToolbarSection('Text', [BoldButton(), ItalicButton(), LinkButton()]),
]));Use catalog.describe() for a JSON-compatible description of the mounted actions, including visibility, enablement, active state, shortcuts and refusal reasons. Before mounting it reports mounted: false and an empty action list. An agent should discover capabilities through configuration.describe() and the action catalog, then execute the same commands as the UI.
dart
import 'package:vyuh_document_editor_elements/vyuh_document_editor_elements.dart';
import 'package:flutter/services.dart';
import 'package:material_ui/material_ui.dart';
import 'package:vyuh_document_editor/document_editor_extensions.dart';
import 'package:vyuh_document_editor/vyuh_document_editor.dart';
// The host's tools: registered action IDs. Label, glyph, enabled and active
// state come from the controller's action catalog; the host keeps none.
final tools = <EditorActionId>[
MarkActionId.bold,
HeadingActionId.level(1),
ListActionId.bullet,
HistoryActionId.undo,
];
class HostDrivenEditor extends StatefulWidget {
const HostDrivenEditor({super.key});
@override
State<HostDrivenEditor> createState() => _HostDrivenEditorState();
}
enum HostActionId with EditorActionKey implements EditorActionId {
palette('host-command-palette');
const HostActionId(this.key);
@override
final String key;
}
class _HostDrivenEditorState extends State<HostDrivenEditor> {
// The host is an extension: its palette action takes Cmd/Ctrl+K from the
// editor's link action, because it registers after the starter kit.
late final controller = DocumentEditorController(
layoutMode: DocumentEditorLayoutMode.pageless,
extensions: [
...DocumentEditorElements.defaults,
DocumentHostExtension(
id: 'host-commands',
register: (registry) => registry.registerAction(
EditorAction(
id: HostActionId.palette,
label: 'Command palette',
group: ToolbarGroup.review,
activators: const [
SingleActivator(LogicalKeyboardKey.keyK, meta: true),
SingleActivator(LogicalKeyboardKey.keyK, control: true),
],
transactionKind: DocumentCanonicalTransactionKind.none,
execute: (_) => openPalette(context),
),
),
),
],
);
String status = 'No command run yet.';
DocumentActionCatalog get catalog => controller.actionCatalog;
void run(EditorActionId id) {
final label = catalog.stateOf(id)?.label ?? id.key;
final before = controller.document;
final ran = catalog.invoke(id); // the action's own admission and history
setState(
() => status = !ran
? '$label: not available here'
: identical(before, controller.document)
? '$label: document unchanged'
: '$label: applied',
);
}
@override
void dispose() {
controller.dispose();
super.dispose();
}
@override
Widget build(BuildContext context) => Column(
children: [
// Rebuilds when an action's state changes: the buttons follow the
// caret. Empty until the editor below mounts and installs its actions.
ListenableBuilder(
listenable: catalog,
builder: (context, _) => Row(
children: [
for (final id in tools)
if (catalog.stateOf(id) case final state?)
IconButton(
tooltip: state.label,
icon: Icon(state.icon),
isSelected: state.active ?? false,
onPressed: state.enabled ? () => run(id) : null,
),
],
),
),
// No built-in toolbar: disabled() is the default.
Expanded(child: DocumentEditor(controller: controller)),
Text(status),
],
);
// A text field over `catalog.actions`, filtered by label; runs the chosen
// one with `run(state.id)`.
Future<void> openPalette(BuildContext context) async {
/* … */
}
}Text colour reads back in three states:
selectionTextColor | selectionTextColorIsMixed | The selection has |
|---|---|---|
null | false | Automatic colour: none set |
DocumentColor.hex('#000000') | false | That colour, set explicitly |
null | true | Several colours |
Show automatic as its own choice: text with no colour follows the page and theme, which isn't the same as explicit black. setSelectionTextColor(color) sets a colour and clearSelectionCharacterProperties({CharacterFormatProperty.color}) returns the selection to automatic, leaving bold, italic and every other format as they are. The same command clears any direct character property: clear fontFamily to follow the style's font, highlightColor for no highlight, or several at once. A cleared property reads back as unset, never as an explicit value (try it live). Colours are DocumentColor values, not strings: see Typed values. Try it live.
Keyboard editing
| Action | Shortcut |
|---|---|
| Bold / italic / underline | Command or Ctrl + B / I / U |
| Undo / redo | Command or Ctrl + Z / Shift + Z |
| Link | Command or Ctrl + K |
| Extend selection | Shift + arrow keys |
| Paragraph / line break | Enter / Shift + Enter |
Focus
Formatting actions keep typing focus. Set DocumentEditor(autofocus: true) to start ready to type, or pass your own focusNode and restore it after your dialogs. The link action needs a link request handler.