NuGet
HTML editor API reference
The Avalonia edition exposes native framework controls and awaited document services. Use the operation suited to the currently visible content and await its actual result.
| Member | Use |
|---|---|
Content | Load/export HTML, inspect elements and edit authored body style. |
Selection | Read/set the visible Source draft or rendered selection using UTF-16 positions. |
Formatting | Format editable Design content or use the six supported Source tag wrappers. |
StateQuery | Read formatting and command availability. |
Editor | Use current-view clipboard, history, deletion, scrolling, search, print and focus operations. |
Caret | Read actual offsets and available geometry; navigate the visible editing surface. |
Dialog | Open native authoring workflows and customize ten typed fresh-window factories. |
MailMerge | Insert, discover and merge template fields. |
TableAuthoringService | Create/revise tables and cells. |
Search | Find/replace in rendered content or the visible source draft. |
BodyHtml and DocumentHtml support binding. The native Border uses Child for its visual layout. Content is the replaceable awaited authoring service.
var found = await editor.Search.FindNextAsync("renewal", wholeWord: true);
var replacements = await editor.Search.ReplaceAllAsync("renewal", "extension", wholeWord: true);
string bodyCss = await editor.Content.GetBodyStyleAsync();
Next/previous search does not wrap automatically. Replace current requires the current selected match; replace all precomputes a bounded plan and reports the actual count. Read-only and preview allow search while rejecting replacement. Source replacements stay in the visible draft and source undo history.
Mode, editing entitlement, document identity and selection identity determine whether a mutation can apply. A null/blank SetAttributeValueOfAnElementAsync value removes that supported attribute; a missing element leaves the document unchanged.
Hyperlink and property APIs
SetHyperlinkAsync accepts the shared HyperLinkDialogInputs model; RemoveHyperlinkAsync removes the selected anchor while retaining its child content. HrefUrl, Bookmark, Title, InnerHtml and optional Target describe the authored hyperlink. Native file-link browsing requires an actual picker grant. ShowCtrlClickTooltipOnHyperlinks controls the shared hint when an accepted link has no title. TableAuthoringService.SetTablePropertiesAsync and SetCellPropertiesAsync apply the shared complete property models as guarded undoable changes.
Replaceable services and notifications
Content, Editor, Caret, Formatting, Selection, StateQuery and Dialog are non-null replaceable native interfaces. MailMerge, TableAuthoringService and Search are additional services. Mode, file and spelling events follow acknowledged work; Pasting performs synchronous bounded inspection before insertion. Passive element-click/mousedown notifications contain copied data, never executable DOM objects.
Content also exposes XHTML/XML export, one-undo local-image embedding and unsent email construction. Native APIs are awaited adaptations; MSHTML COM objects and arbitrary Internet Explorer commands are not part of this edition.
Related guides
Moving from WPF
Port the document workflow, then adapt the framework controls and awaited APIs. The Avalonia edition uses its own control and service interfaces. Keep representative documents in private tests and compare load, edit, Undo/Redo, Source, export and reopen before changing your application's production path.
| WPF integration | Avalonia integration | What to adapt |
|---|---|---|
WpfHtmlEditor in WPF XAML | AvaloniaHtmlEditor in Avalonia XAML | Use the Avalonia namespace, controls, brushes and application lifetime. |
BodyHtml or DocumentHtml dependency-property binding | Two-way Avalonia binding to one matching property | Use a view model that notifies changes. Await an export when saving current edits. |
| Synchronous content and editing methods | Awaited Content, Editor, Caret, Selection, Formatting, StateQuery and Dialog operations | Show the owner, await readiness, and handle cancellation or rejection. Keep the UI thread responsive. |
| Source text and mode-sensitive property access | A separate Source draft with explicit apply/discard and awaited export | Export and leaving Source apply the draft. A failed or stale apply retains it. Built-in picker Save and explicit export have distinct boundaries. |
| WPF toolbar and menu controls | Native Avalonia toolbar controls, named items and context-menu APIs | Move command policy and labels; recreate framework-specific presentation. |
| WPF dialog factories | Typed Avalonia dialog factories | Return a fresh unshown window. Let the editor manage modal ownership and selection restoration. |
| Browser-relative paths and legacy browser configuration | BaseUrl plus explicit file and external-resource policy | A base address does not grant a file read or network fetch. Preserve authored URLs separately from safe display transport. |
| WPF license entitlement | Static AvaloniaHtmlEditor.LicenseKey | Use the Avalonia entitlement before creating controls. WPF and WinForms keys do not activate this edition. |
| MSHTML COM objects, IE document mode and WPF routed events | Typed snapshots, service operations and Avalonia events | Use copied authoring data and supported operations. These platform types do not have source or binary compatibility. |
Load and export through the current facade
await editor.Ready;
await editor.Content.SetDocumentHtmlAsync("<!doctype html><html><head><title>Project update</title></head><body><p>Ready for review.</p></body></html>");
string currentHtml = await editor.Content.GetDocumentHtmlAsync();
string currentXhtml = await editor.Content.GetDocumentHtmlAsync(true);
string currentXml = await editor.Content.GetDocumentXmlAsync();
This fragment runs after the editor attaches to a visible window. Persist the returned format through your application's save workflow. Await failures before reporting success. Do not automatically repeat a mutation after a timeout: it may already have applied.
Replacing a service
Implement the interface from the exact package used by your application, and route stock commands through the replacement. A Content decorator must retain this editor's table and mail-merge subservices for the stock integration. Those nested concrete services are not arbitrary independent providers. Changing a required interface member requires updating custom implementations; matching method names alone does not establish compatibility.
Security and document checks
Imported active content is sanitized or rejected. External resources are blocked by default. Test representative head styles, images, tables, lists and Unicode in both controls; compare semantic edited output and exact unchanged-document preservation where required. Keep document CSS separate from application Light/Dark presentation.
See readiness and asynchronous operations, HTML input and external resources and runnable examples.