Loading...
Loading...
Complete reference for all SunEditor initialization options, including plugin options.
plugins| { [x: string]: any; } | Array<{ [x: string]: any; }>Plugin configuration. Pass an array of plugin classes or an object keyed by plugin name.
import plugins, { image, link, table } from 'suneditor/src/plugins';
{ plugins: plugins,
plugins: [image, link, table],
plugins: { image, link, table }
}v2MigrationbooleanEnables migration mode for SunEditor v2.
falsemode'classic' | 'inline' | 'balloon' | 'balloon-always' | 'classic:bottom' | 'inline:bottom'Toolbar mode: classic, inline, balloon, balloon-always. Append :bottom to place toolbar at the bottom (e.g. classic:bottom, inline:bottom).
"classic"typestringEditor type. Use "document" for a document-style layout, with optional sub-types after :.
""// type
'document:header,page'themestringEditor theme.
""lang{ [x: string]: string; }Language configuration. default : EN
icons{ [x: string]: string; }Overrides the default icons.
textDirection'ltr' | 'rtl'Text direction: ltr or rtl.
"ltr"reverseCommandsindent-outdent + user's reverseButtons.toolbar_widthstringToolbar width.
"auto"toolbar_containerHTMLElement | nullContainer element for the toolbar.
toolbar_stickynumberEnables sticky toolbar with optional offset.
0toolbar_hidebooleanHides toolbar initially.
falsesubToolbar{ buttonList?: SunEditor.UI.ButtonList; mode?: 'balloon' | 'balloon-always'; width?: string; }Sub-toolbar configuration. A secondary toolbar that appears on text selection.
{}shortcutsHintbooleanDisplays shortcut hints in tooltips.
trueshortcutsDisablebooleanDisables keyboard shortcuts.
falseshortcuts{ [key: string]: Array<string> | undefined; }_ are user-defined custom shortcuts. Each value is an array of [keyCombo, hintLabel] pairs.c (Ctrl/Cmd), s (Shift), and KeyEvent.code values joined by +.$~pluginName.method to call a specific plugin method.{}{
shortcuts: {
bold: ['c+KeyB', 'B'],
_h1: ['c+s+Digit1+$~blockStyle.applyHeaderByShortcut', '']
}
}toolbar_sub_widthSub-toolbar width.
strictMode| true | { tagFilter: boolean; formatFilter: boolean; classFilter: boolean; textStyleTagFilter: boolean; attrFilter: boolean; styleFilter: boolean; }true to enable all filters (default), or an object to control individual filters.false is not supported; use the object form to disable specific filters instead.tagFilter: Filters disallowed HTML tags (elementWhitelist/elementBlacklist)formatFilter: Filters format elements (formatLine/formatBlock)classFilter: Filters disallowed CSS class names (allowedClassName)textStyleTagFilter: Filters text style tags (b, i, u, span, etc.)attrFilter: Filters disallowed HTML attributes (attributeWhitelist/attributeBlacklist)styleFilter: Filters disallowed inline styles (spanStyles/lineStyles/allUsedStyles)true// disable only attribute and style filters
{
strictMode: {
tagFilter: true,
formatFilter: true,
classFilter: true,
textStyleTagFilter: true,
attrFilter: false,
styleFilter: false
}
}scopeSelectionTagsArray<string>CONSTANTS.SCOPE_SELECTION_TAGSelementWhiteliststring"|".""{ elementWhitelist: 'mark|details|summary' }elementBlackliststring"|".""{ elementBlacklist: 'script|style|iframe' }allowedEmptyTagsstringALLOWED_EMPTY_NODE_LIST to form the final allowedEmptyTags list.CONSTANTS.ALLOWED_EMPTY_NODE_LISTattributeWhitelist{ [key: string]: string | undefined; }"*" applies to all tags.null{
attributeWhitelist: {
a: 'href|target',
img: 'src|alt',
'*': 'id|data-*'
}
}attributeBlacklist{ [key: string]: string | undefined; }"*" applies to all tags.null{ attributeBlacklist: { '*': 'onclick|onerror' } }textStyleTagsstring__textStyleTagsconvertTextTags{ [x: string]: string; }Maps text styles to specific HTML tags.
{bold: "strong", underline: "u", italic: "em", strike: "del", subscript: "sub", superscript: "sup"}{
convertTextTags: {
bold: 'b',
italic: 'i',
underline: 'u',
strike: 's'
}
}allUsedStylesstringSpecifies additional styles to the list of allowed styles. Delimiter: "|".
{ allUsedStyles: 'color|background-color|text-shadow' }tagStyles{ [x: string]: string; }Specifies allowed styles for HTML tags. Key is tag name(s), value is pipe-delimited allowed styles.
{}{
tagStyles: {
'table|td': 'border|color|background-color',
hr: 'border-top'
}
}spanStylesstringspan tag.CONSTANTS.SPAN_STYLESlineStylesstringline element (p..).CONSTANTS.LINE_STYLESfontSizeUnitsArray<string>CONSTANTS.SIZE_UNITSretainStyleMode'repeat' | 'always' | 'none'<span>, <strong>) are handled when deleting text.repeat: Styles are retained unless backspace is repeatedly pressed.none: Styles are not retained. Inline elements are immediately removed with the text.always: Styles persist indefinitely unless explicitly removed."repeat"defaultLinestringDefault line element when inserting new lines.
"p"defaultLineBreakFormat'line' | 'br'line : Line break is divided into general tags.br : Line breaks are treated as <br> on the same line. (like shift+enter)line.line by entering a line break twice in a row.line, such as Quote, still operate on a line basis.line units.br, performance may decrease when editing a lot of data."line"lineAttrResetstringLine properties that should be reset when changing lines. Delimiter: "|".
""{ lineAttrReset: 'id|name' }formatLinestringline elements beyond the default. Delimiter: "|".line list.line element also contains brLine element.__defaultFormatLine{ formatLine: 'ARTICLE|SECTION' }formatBrLinestringbrLine elements beyond the default.brLine list.brLine elements are included in the line element.brLine elements' line break is BR tag.brLine and appends line.__defaultFormatBrLine{ formatBrLine: 'CODE' }formatClosureBrLinestringclosureBrLine elements beyond the default.closureBrLine list.closureBrLine elements are included in the brLine.closureBrLine elements' line break is BR tag.__defaultFormatClosureBrLineformatBlockstringblock elements beyond the default.block list.block wraps the line and component.__defaultFormatBlockformatClosureBlockstringclosureBlock elements beyond the default.closureBlock list.closureBlock elements are included in the block.closureBlock element wraps the line and component.__defaultFormatClosureBlockallowedExtraTags{ [x: string]: boolean; }true to allow, false to disallow.CONSTANTS.EXTRA_TAG_MAP{
allowedExtraTags: {
script: false,
style: false,
mark: true
}
}closeModalOutsideClickbooleanCloses modals when clicking outside.
falsesyncTabIndentbooleanSynchronizes tab indent with spaces.
truetabDisablebooleanDisables tab key input.
falsecopyFormatKeepOnbooleanKeeps the format of the copied content.
falseautoLinkifybooleanLink plugin required)Boolean(plugins.link) β determined by whether the link plugin is enabled.historyStackDelayTimenumberDelay time for history stack updates (ms).
400printClassstringClass name for printing.
""fullScreenOffsetnumberOffset applied when entering fullscreen mode.
0previewTemplatestring | nullCustom HTML template for preview mode. Use {{ contents }} as a placeholder for editor content.
nullprintTemplatestring | nullCustom HTML template for print mode. Use {{ contents }} as a placeholder for editor content.
null{ previewTemplate: '<div class="my-preview"><h1>Preview</h1>{{ contents }}</div>' }componentInsertBehaviorSunEditor.ComponentInsertTypeselectMode:auto: Move cursor to the next line if possible, otherwise select the component.select: Always select the inserted component.line: Move cursor to the next line if possible, or create a new line and move there.none: Do nothing."auto"defaultUrlProtocolstring | nullDefault URL protocol for links.
nulltoastMessageTimeanyDuration for displaying toast messages (ms).
{copy: 1500}freeCodeViewModebooleanEnables free code view mode.
falsecodeMirrorEditorCodeMirror editor instance (frame-level). Set by _checkCodeMirror after initialization.
externalLibs{ [x: string]: any; }{
externalLibs: {
katex: window.katex,
codeMirror: { src: CodeMirror }
}
}codeMirrorCodeMirror configuration object from externalLibs.codeMirror.
hasCodeMirrorUses CodeMirror for code view.
eventsSunEditor.Event.HandlersUser event handlers configuration.
{
events: {
onChange: (content) => console.log(content),
onImageUploadBefore: (files, info) => true
}
}topStyles applied to the top container (e.g. width, z-index, etc).
frameStyles applied to the iframe container (e.g. height, min-height).
editorStyles applied to the editable content area.
statusbar_containerHTMLElement | nullContainer element for the status bar.
historyStackSizenumberMaximum number of history entries per root frame. Oldest entries are discarded when exceeded.
100finder_panelbooleantruefinder_liveSearchbooleanSearches instantly as you type (debounced). When false, search runs only on Enter.
truecodeBlock_langs[] to disable language selection UI entirely.These options can be configured individually per root in multi-root mode.
valuestringInitial value for the editor.
""placeholderstringPlaceholder text.
""editableFrameAttributes{ [x: string]: string; }Attributes for the editable frame[.sun-editor-editable].
{spellcheck: "false"}{ editableFrameAttributes: { spellcheck: 'true', autocomplete: 'on' } }widthstring | numberWidth for the editor.
"100%"minWidthstring | numberMin width for the editor.
""maxWidthstring | numberMax width for the editor.
""heightstring | numberHeight for the editor.
"auto"minHeightstring | numberMin height for the editor.
""maxHeightstring | numberMax height for the editor.
""editorStylestringStyle string of the top frame of the editor.
""{ editorStyle: 'border: 1px solid #ccc; border-radius: 4px;' }iframebooleanContent will be placed in an iframe and isolated from the rest of the page.
falseiframe_fullPagebooleanAllows the usage of HTML, HEAD, BODY tags and DOCTYPE declaration on the iframe.
falseiframe_attributes{ [x: string]: string; }Attributes of the iframe.
{}{ iframe_attributes: { 'allow-scripts': 'true', sandbox: 'allow-same-origin' } }statusbarbooleanEnables the status bar.
truestatusbar_showPathLabelbooleanDisplays the current node structure in the status bar.
truestatusbar_resizeEnablebooleanEnables resize function of the bottom status bar.
truecharCounterbooleanmaxCharCount option has a value, it becomes true.falsecharCounter_maxnumber | nullThe maximum number of characters allowed to be inserted into the editor.
nullcharCounter_labelstring | nullText to be displayed in the charCounter area of the bottom bar.
null{ charCounter_label: 'Characters :' }charCounter_type'char' | 'byte' | 'byte-html'charCounter option.char: Characters length.byte: Binary data size of characters.byte-html: Binary data size of the full HTML string."char"itemsAlign items
defaultWidthThe default width of the AUDIO tag.
defaultHeightThe default height of the AUDIO tag.
createFileInputWhether to create a file input element.
createUrlInputtrue. Always true when createFileInput is false.uploadUrlThe URL to which files will be uploaded.
uploadHeadersHeaders to include in the file upload request.
uploadSizeLimitThe total upload size limit in bytes.
uploadSingleSizeLimitThe single file size limit in bytes.
allowMultipleWhether to allow multiple file uploads.
acceptedFormatsAccepted file formats (default is "audio/*").
audioTagAttributesAdditional attributes to set on the AUDIO tag.
insertBehavioroptions.get('componentInsertBehavior')]auto: Move cursor to the next line if possible, otherwise select the component.select: Always select the inserted component.line: Move cursor to the next line if possible, or create a new line and move there.none: Do nothing.dataDirect data without server calls
urlServer request URL
headersServer request headers
thumbnailDefault thumbnail
itemsColor list.
splitNumNumber of colors per line
disableHEXInputDisable HEX input
itemscommand β "line": single line block, "br-line": br-separated block, "block": container block.outputFormatThe output format of the drawing. Options: "dataurl", "svg".
useFormatTypeWhether to enable format type selection (block vs inline).
defaultFormatTypeThe default format type, either "block" or "inline".
keepFormatTypeWhether to maintain the chosen format type after drawing.
lineWidthThe width of the drawing line.
lineReconnectWhether to reconnect lines when drawing.
lineCapThe style of the line cap ("butt", "round", or "square").
lineColorThe color of the drawing line.
canResizeWhether the modal form can be resized.
maintainRatioWhether to maintain the aspect ratio when resizing.
formSizeThe size configuration for the drawing modal form.
canResizeWhether the embed element can be resized.
showHeightInputWhether to display the height input field.
defaultWidthThe default width of the embed element (numeric value or with unit).
defaultHeightThe default height of the embed element (numeric value or with unit).
percentageOnlySizeWhether to allow only percentage-based sizing.
uploadUrlThe URL for file uploads.
uploadHeadersHeaders to include in file upload requests.
uploadSizeLimitThe total file upload size limit in bytes.
uploadSingleSizeLimitThe single file upload size limit in bytes.
iframeTagAttributesAdditional attributes to set on the IFRAME tag.
query_youtubeYouTube query parameter appended to the embed URL.
query_vimeoVimeo query parameter appended to the embed URL.
urlPatternsAdditional URL patterns to recognize as embeddable content.
embedQueryCustom embed service definitions.
controlsFigure controls.
insertBehavioroptions.get('componentInsertBehavior')]auto: Move cursor to the next line if possible, otherwise select the component.select: Always select the inserted component.line: Move cursor to the next line if possible, or create a new line and move there.none: Do nothing.apiUrlServer request URL for PDF generation
fileNameName of the generated PDF file
dataDirect data without server calls (bypasses URL fetch).
urlServer request URL
headersServer request headers
thumbnailDefault thumbnail URL or a function that returns a thumbnail URL per item.
propsAdditional tag names
dataDirect data without server calls
urlServer request URL
headersServer request headers
thumbnailDefault thumbnail
uploadUrlServer request URL for file upload
uploadHeadersServer request headers
uploadSizeLimitTotal upload size limit in bytes
uploadSingleSizeLimitSingle file size limit in bytes
allowMultipleAllow multiple file uploads
acceptedFormatsAccepted file formats.
asSpecify the default form of the file component as box or link
controlsAdditional controls to be added to the figure
insertBehavioroptions.get('componentInsertBehavior')]auto: Move cursor to the next line if possible, otherwise select the component.select: Always select the inserted component.line: Move cursor to the next line if possible, or create a new line and move there.none: Do nothing.itemsFont list
itemsColor list.
splitNumNumber of colors per line
disableHEXInputDisable HEX input
sizeUnit'px', 'pt', 'em', 'rem', 'vw', 'vh', '%' or 'text'.'text' is used, a text-based font size list is applied.showDefaultSizeLabelDetermines whether the default size label is displayed in the dropdown menu.
showIncDecControlstrue, displays increase and decrease buttons for font size adjustments.false. Always false when sizeUnit is 'text' (ignored).disableInputtrue, disables the direct font size input box.true when sizeUnit is 'text', otherwise false.unitMapOverride or extend the default unit mapping for font sizes.
itemsHR list
canResizeWhether the image element can be resized.
showHeightInputWhether to display the height input field.
defaultWidthThe default width of the image. If a number is provided, "px" will be appended.
defaultHeightThe default height of the image. If a number is provided, "px" will be appended.
percentageOnlySizeWhether to allow only percentage-based sizing.
createFileInputWhether to create a file input element for image uploads.
createUrlInputtrue. Always true when createFileInput is false.uploadUrlThe URL endpoint for image file uploads.
uploadHeadersAdditional headers to include in the file upload request.
uploadSizeLimitThe total upload size limit in bytes.
uploadSingleSizeLimitThe single file upload size limit in bytes.
allowMultipleWhether multiple image uploads are allowed.
acceptedFormatsThe accepted file formats for image uploads.
useFormatTypeWhether to enable format type selection (block or inline).
defaultFormatTypeThe default image format type ("block" or "inline").
keepFormatTypeWhether to retain the chosen format type after image insertion.
linkEnableFileUploadWhether to enable file uploads for linked images.
controlsFigure controls.
insertBehavioroptions.get('componentInsertBehavior')]selectMode:auto: Move cursor to the next line if possible, otherwise select the component.select: Always select the inserted component.line: Move cursor to the next line if possible, or create a new line and move there.none: Do nothing.dataDirect data without server calls
urlServer request URL
headersServer request headers
itemsLayout list. Each item defines a named layout template with raw HTML.
itemsLine height list
uploadUrlThe URL endpoint for file uploads.
uploadHeadersAdditional headers for file upload requests.
uploadSizeLimitThe total file upload size limit in bytes.
uploadSingleSizeLimitThe single file upload size limit in bytes.
acceptedFormatsAccepted file formats for link uploads.
titleModal title display.
textToDisplayCreate Text to display input.
openNewWindowDefault checked value of the Open in new window checkbox.
noAutoPrefixIf true, disables the automatic prefixing of the host URL to the value of the link.
relListAvailable rel attribute values shown as checkboxes in the link modal.
defaultRelDefault rel values auto-applied by condition.
enableFileUploadIf true, enables file upload.
canResizeWhether the math modal can be resized.
autoHeightWhether to automatically adjust the height of the modal.
fontSizeListA list of font size options for the math expression size selector.
onPasteA callback function to handle paste events in the math input area.
formSizeAn object specifying the dimensions for the math modal.
triggerTextThe character that triggers the mention list.
limitSizeThe number of items to display in the mention list
searchStartLengthThe number of characters to start searching for the mention list
delayTimeThe time to wait before displaying the mention list
dataStatic mention data (used instead of API).
apiUrlThe URL to call the mention list
apiHeadersThe headers to send with the API call
useCachingDataWhether to cache the mention list data
useCachingFieldDataWhether to cache the mention list data in the field
itemsParagraph item list
scrollTypeScroll type (x, y, xy)
captionPositionCaption position (top, bottom)
cellControllerPositionCell controller position (cell, table)
colorListHEX color list for the cell background color picker.
itemsTemplate list
itemsText style item list.
canResizeWhether the video element can be resized.
showHeightInputWhether to display the height input field.
defaultWidthThe default width of the video element. If a number is provided, "px" will be appended.
defaultHeightThe default height of the video element. If a number is provided, "px" will be appended.
percentageOnlySizeWhether to allow only percentage-based sizing.
createFileInputWhether to create a file input element for video uploads.
createUrlInputtrue. Always true when createFileInput is false.uploadUrlThe URL endpoint for video file uploads.
uploadHeadersAdditional headers to include in the video upload request.
uploadSizeLimitThe total upload size limit for videos in bytes.
uploadSingleSizeLimitThe single file upload size limit for videos in bytes.
allowMultipleWhether multiple video uploads are allowed.
acceptedFormatsAccepted file formats for video uploads ("video/*").
defaultRatioThe default aspect ratio for the video (height/width, e.g. 16:9 β 9/16 = 0.5625).
showRatioOptionWhether to display the ratio option in the modal.
ratioOptionsCustom ratio options for video resizing (value = height/width).
videoTagAttributesAdditional attributes to set on the VIDEO tag.
iframeTagAttributesAdditional attributes to set on the IFRAME tag.
query_youtubeAdditional query parameters for YouTube embedding.
query_vimeoAdditional query parameters for Vimeo embedding.
embedQueryCustom embed service definitions (see EmbedPluginOptions.embedQuery).
urlPatternsAdditional URL patterns for video embedding.
extensionsAdditional file extensions to be recognized for video uploads.
controlsFigure controls.
insertBehavioroptions.get('componentInsertBehavior')]auto: Move cursor to the next line if possible, otherwise select the component.select: Always select the inserted component.line: Move cursor to the next line if possible, or create a new line and move there.none: Do nothing.dataDirect data without server calls
urlServer request URL
headersServer request headers
thumbnailDefault thumbnail