Editor Options Reference

WinForms HTML Editor Property Grid showing the IEditorOptions categories fully expanded at design time in Visual Studio

This page is the canonical reference for every public property on IEditorOptions (and its concrete implementation UserOption) that you reach through editor.Options. Most properties are surfaced through the WinForms Property Grid at design time; you can also set them in code at any point after construction. Properties are grouped by behaviour so you can find the knob you want without scanning the whole list.

using SpiceLogic.HtmlEditor.Abstractions;using SpiceLogic.HtmlEditor.Abstractions.Options;// All options live under editor.Options. Defaults are sensible for// most apps; tweak only the ones you need.editor.Options.EnterKeyResponse = EnterKeyResponses.Paragraph;editor.Options.AutoResizeLargeImages = true;editor.Options.MaxPastedImageWidth  = 1024;

Paste behaviour

Before and after comparison of AutoDetectWordPaste cleaning up Microsoft Word clipboard payload in the WinForms HTML Editor

bool AutoDetectWordPaste — automatically detects MS Word / Outlook / OneNote / Excel / PowerPoint clipboard payloads and applies the Paste from Word cleanup without requiring the user to click that toolbar button. Supports Office 2007–2025+. Default: true.

bool MsIePasteBehavior — when true, the control uses MSIE’s native paste behaviour (the Pasting event still fires but cannot rewrite the pasted HTML); when false, the editor uses the managed paste path that lets handlers set HtmlBeingPasted in the event args. Default: true in WinForms (the default ctor sets it explicitly).

ImageStorage PasteImageFromClipboardBehavior — controls what happens when the user pastes an image from the clipboard. Values: Base64 (inline data URI), LocalBaseUrlFolderIfDefined (write to the local folder pointed to by BaseUrl when it is a real directory), or None (suppress clipboard image paste). Default: Base64.

URL and link handling

bool UrlEncodeHyperlinkHRefs — URL-encodes the href value written by the Hyperlink dialog. Leave this on to avoid broken links with spaces / non-ASCII characters. Default: true.

bool ConvertFileUrlsToLocalPaths — rewrites URLs that start with file:/// back to native Windows paths (so file:///D:/My%20Folder/pic.jpg becomes D:\My Folder\pic.jpg). Default: true.

bool ConvertAbsoluteUrlsToRelativeUrls — rewrites absolute URLs into relative URLs when they live underneath BaseUrl. Has no effect unless BaseUrl is set. Default: true.

bool ConvertHyperlinkTargetsToBlankBeforePreview — before switching to Preview Mode the editor rewrites every <a> to target="_blank" so previewed links open in the external browser rather than navigating away from the host. Default: true.

bool ShowCtrlClickTooltipOnHyperlinks — when true, the Hyperlink dialog defaults the HTML title attribute to "Ctrl+Click to view" when the user leaves the Title field blank, surfacing as a native browser tooltip. Default: false.

bool DisableLocalResourceSelection — hides the "browse local file" entry points in the Image and Hyperlink dialogs (useful for kiosk / cloud-only editors). Default: false.

Performance

bool SacrificeOptimizationForLongHtml — opts out of the editor’s incremental rendering pipeline. Set to true only when you load very large HTML and need correctness over speed. Default: false.

bool FormatHtmlSource — indent the HTML when switching from WYSIWYG to source mode. On long documents this costs a few hundred milliseconds; turn it off if your customers paste 100 KB of HTML and complain about the mode switch latency. Default: true.

bool UpdateFooterTagNavigator — keeps the footer tag-navigator bar in sync with the caret position. Setting to false trims a small per-caret-move cost on dense documents. Default: true.

Font and typography

bool KeepTextSelectedAfterFontChange — preserves the selection after applying a font / size / color so the user can chain formatting clicks. Default: true.

FontSizeUnit DefaultFontSizeUnit — CSS unit emitted by the font-size dropdown when the user picks a value. Pt emits values like "12pt" (historical behaviour); Px emits "16px". Default: FontSizeUnit.Pt.

Font? FooterTagNavigatorFont — font used for the tag breadcrumbs in the footer toolbar. Default: null (system default).

Color FooterTagNavigatorTextColor — foreground color of the footer tag-navigator items. Default: Color.Teal.

Table editing

ShowZeroBorderGuideline rendering dashed CSS guidelines around a zero border table inside the WinForms HTML Editor design surface

bool EnableTableCellMerge — enables the Merge / Split commands in the table context menu. Setting to false raises PropertyChanged so toolbars can rebuild and hide the affected buttons. Default: true.

bool ShowZeroBorderGuideline — draws dashed CSS guidelines around tables whose border attribute is 0 so the user can still see the layout while editing. Saved HTML is unaffected. Default: true.

string ZeroBorderTableGuidelineCss — the CSS rule used to render those guidelines. Override if the default dashed grey clashes with your editor theme. Default: module-level ZeroBorderTableGuidelineCss constant.

Image handling

AutoResizeLargeImages downscaling a pasted six thousand pixel phone photo to the MaxPastedImageWidth ceiling at runtime

bool AutoResizeLargeImages — aspect-preserving down-scale of images wider than MaxPastedImageWidth when pasted or inserted via the Image dialog. Stops a 6000×4000 phone photo from blowing out the page. Default: true.

int MaxPastedImageWidth — ceiling (in pixels) applied when AutoResizeLargeImages is on. Height scales proportionally. Default: 720.

bool UseInlineStyleForImageDimensions — when true, the Image dialog writes style="width:240px;height:120px" instead of the legacy width= / height= attributes. Default: false.

Enter key and tab key

EnterKeyResponse comparison showing paragraph mode versus line break mode HTML output in the WinForms HTML Editor source view

EnterKeyResponses EnterKeyResponse — whether pressing Enter inserts a <br> (LineBreak) or a new <p> (Paragraph). Default: EnterKeyResponses.LineBreak.

bool ContinueSameStyleAfterEnterKey — when false, hitting Enter starts a fresh formatting context (no inherited font color / size / background). Useful when users complain that "everything turns red after I pressed Enter once". Default: true.

bool InsertSpaceOnTabKey — when true, the Tab key inserts spaces inside the editor; when false, Tab moves focus to the next control in the host form’s tab order. Default: false.

int TabWidth — number of space characters inserted when InsertSpaceOnTabKey is on. Default: 1.

HTML output and DOCTYPE

DOCTYPEOverrideOptions producing HTML5 versus HTML4 transitional document output in the WinForms HTML Editor saved source view

HtmlContentTypes DefaultHtmlType — whether editor.Content getters return body-only HTML (BodyHtml) or the full document (DocumentHtml) when the caller does not specify. Default: HtmlContentTypes.BodyHtml.

DocTypes DOCTYPEOverrideOptions — controls which DOCTYPE the editor prepends to saved document HTML. Values: None, Html401Transitional, Html5, Custom, DoNotOverride. Default: DocTypes.DoNotOverride.

bool UseHtml5DocType — when DOCTYPEOverrideOptions = DoNotOverride, controls whether the resolved DOCTYPE is HTML5 (<!DOCTYPE html>) or HTML 4.01 Transitional. Default: true.

string CustomDOCTYPE — literal DOCTYPE string emitted when DOCTYPEOverrideOptions = Custom. Default: null / empty.

bool OutputMetaGenerator — emits a <meta name="generator"> tag in the saved document head. Default: false.

string DefaultCSSFileLinkNameAttribute — the value the editor writes to the name attribute on <link rel="stylesheet"> entries it owns, so subsequent saves can find and update the right tag. Default: module-level constant.

string YouTubeVideoIFrameDefaultCSS — default inline style applied to <iframe> wrappers inserted via the YouTube dialog. Default: module-level constant.

Context menu and right-click behaviour

bool ShowDefaultContextMenu — when false, the built-in right-click menu is suppressed and you are expected to wire ContextMenuShowing to your own ContextMenuStrip. Default: true.

bool DisableEditorRightClick — when true, suppresses the browser right-click menu entirely (no event, no fallback). Default: false.

bool DoNotShowContextMenuInPreviewMode — suppress the editor context menu while the control is in Preview mode (so the document feels like a static page). Default: false.

Element-level event filtering

HtmlElementTypes FireHtmlElementClickEventFor — restricts HtmlElementClicked to a specific element type (Hyperlink, Image, Table, Paragraph, Span, Div, Input, or All). Default: HtmlElementTypes.All.

HtmlElementTypes FireHtmlElementMouseDownEventFor — same idea for HtmlElementMouseDown. Default: HtmlElementTypes.All.

Localization

EditorLanguage EditorLanguage — UI language for tooltips, menus, dialogs, and status text. Setting this property routes through LocalizationManager.CurrentLanguage, so every live editor instance and the shared resource cache refresh at the same time. The spell checker’s SpellCheckLanguage defaults to SameAsEditorLanguage and follows this value unless you set it explicitly. Default: EditorLanguage.EnglishUs.

Listening for option changes

UserOption implements INotifyPropertyChanged and raises PropertyChanged for the three properties that the toolbar needs to react to at runtime: ShowZeroBorderGuideline, EnableTableCellMerge, and DoNotShowContextMenuInPreviewMode. Subscribe if your host UI needs to mirror these toggles in its own chrome.