Document.execCommand()
When an HTML document has been switched to designMode
, the document object exposes the execCommand
method which allows one to run commands to manipulate the contents of the editable region. Most commands affect the document's selection (bold, italics, etc.), while others insert new elements (adding a link) or affect an entire line (indenting). When using contentEditable
, calling execCommand()
will affect the currently active editable element.
Syntax
bool = document.execCommand(aCommandName, aShowDefaultUI, aValueArgument)
Return value
A Boolean
that is false
if the command is not supported or enabled.
Parameters
aCommandName
- A
DOMString
specifying the name of the command to execute. See Commands for a list of possible commands. aShowDefaultUI
- A
Boolean
indicating whether the default user interface should be shown. This is not implemented in Mozilla. aValueArgument
- For commands which require an input argument (such as
insertImage
, for which this is the URL of the image to insert), this is aDOMString
providing that information. Specifynull
if no argument is needed.
Commands
backColor
- Changes the document background color. In
styleWithCss
mode, it affects the background color of the containing block instead. This requires a<color>
value string to be passed in as a value argument. Note that Internet Explorer uses this to set the text background color. bold
- Toggles bold on/off for the selection or at the insertion point. Internet Explorer uses the
<strong>
tag instead of<b>
. contentReadOnly
- Makes the content document either read-only or editable. This requires a boolean true/false to be passed in as a value argument. (Not supported by Internet Explorer.)
copy
- Copies the current selection to the clipboard. Conditions of having this behavior enabled vary from one browser to another, and have evolved over time. Check the compatibility table to determine if you can use it in your case.
createLink
- Creates an anchor link from the selection, only if there is a selection. This requires the HREF URI string to be passed in as a value argument. The URI must contain at least a single character, which may be a white space. (Internet Explorer will create a link with a null URI value.)
cut
- Cuts the current selection and copies it to the clipboard. Conditions of having this behavior enabled vary from one browser to another, and have evolved over time. Check the compatibility table for knowing if you can use it in your case.
decreaseFontSize
- Adds a
<small>
tag around the selection or at the insertion point. (Not supported by Internet Explorer.) delete
- Deletes the current selection.
enableInlineTableEditing
- Enables or disables the table row and column insertion and deletion controls. (Not supported by Internet Explorer.)
enableObjectResizing
- Enables or disables the resize handles on images and other resizable objects. (Not supported by Internet Explorer.)
fontName
- Changes the font name for the selection or at the insertion point. This requires a font name string (
"Arial"
for example) to be passed in as a value argument. fontSize
- Changes the font size for the selection or at the insertion point. This requires an HTML font size (
1
-7
) to be passed in as a value argument. foreColor
- Changes a font color for the selection or at the insertion point. This requires a color value string to be passed in as a value argument.
formatBlock
- Adds an HTML block-style tag around the line containing the current selection, replacing the block element containing the line if one exists (in Firefox, BLOCKQUOTE is the exception - it will wrap any containing block element). Requires a tag-name string to be passed in as a value argument. Virtually all block style tags can be used (eg. "H1", "P", "DL", "BLOCKQUOTE"). (Internet Explorer supports only heading tags H1 - H6, ADDRESS, and PRE, which must also include the tag delimiters < >, such as "<H1>".)
forwardDelete
- Deletes the character ahead of the cursor's position. It is the same as hitting the delete key.
heading
- Adds a heading tag around a selection or insertion point line. Requires the tag-name string to be passed in as a value argument (i.e. "H1", "H6"). (Not supported by Internet Explorer and Safari.)
hiliteColor
- Changes the background color for the selection or at the insertion point. Requires a color value string to be passed in as a value argument. UseCSS must be turned on for this to function. (Not supported by Internet Explorer.)
increaseFontSize
- Adds a BIG tag around the selection or at the insertion point. (Not supported by Internet Explorer.)
indent
- Indents the line containing the selection or insertion point. In Firefox, if the selection spans multiple lines at different levels of indentation, only the least indented lines in the selection will be indented.
insertBrOnReturn
- Controls whether the Enter key inserts a br tag or splits the current block element into two. (Not supported by Internet Explorer.)
insertHorizontalRule
- Inserts a horizontal rule at the insertion point (deletes selection).
insertHTML
- Inserts an HTML string at the insertion point (deletes selection). Requires a valid HTML string to be passed in as a value argument. (Not supported by Internet Explorer.)
insertImage
- Inserts an image at the insertion point (deletes selection). Requires the image SRC URI string to be passed in as a value argument. The URI must contain at least a single character, which may be a white space. (Internet Explorer will create a link with a null URI value.)
insertOrderedList
- Creates a numbered ordered list for the selection or at the insertion point.
insertUnorderedList
- Creates a bulleted unordered list for the selection or at the insertion point.
insertParagraph
- Inserts a paragraph around the selection or the current line. (Internet Explorer inserts a paragraph at the insertion point and deletes the selection.)
insertText
- Inserts the given plain text at the insertion point (deletes selection).
italic
- Toggles italics on/off for the selection or at the insertion point. (Internet Explorer uses the EM tag instead of I.)
justifyCenter
- Centers the selection or insertion point.
justifyFull
- Justifies the selection or insertion point.
justifyLeft
- Justifies the selection or insertion point to the left.
justifyRight
- Right-justifies the selection or the insertion point.
outdent
- Outdents the line containing the selection or insertion point.
paste
- Pastes the clipboard contents at the insertion point (replaces current selection). Clipboard capability must be enabled in the user.js preference file. See [1].
redo
- Redoes the previous undo command.
removeFormat
- Removes all formatting from the current selection.
selectAll
- Selects all of the content of the editable region.
strikeThrough
- Toggles strikethrough on/off for the selection or at the insertion point.
subscript
- Toggles subscript on/off for the selection or at the insertion point.
superscript
- Toggles superscript on/off for the selection or at the insertion point.
underline
- Toggles underline on/off for the selection or at the insertion point.
undo
- Undoes the last executed command.
unlink
- Removes the anchor tag from a selected anchor link.
useCSS
- Toggles the use of HTML tags or CSS for the generated markup. Requires a boolean true/false as a value argument. NOTE: This argument is logically backwards (i.e. use false to use CSS, true to use HTML). (Not supported by Internet Explorer.) This has been deprecated; use the styleWithCSS command instead.
styleWithCSS
- Replaces the useCSS command; argument works as expected, i.e. true modifies/generates style attributes in markup, false generates formatting elements.
Example
An example of how to use it on CodePen.
Specifications
Specification | Status | Comment |
---|---|---|
HTML Editing APIs The definition of 'execCommand' in that specification. |
Editor's Draft | Initial definition |
Browser compatibility
Feature | Chrome | Firefox (Gecko) | Internet Explorer | Opera | Safari |
---|---|---|---|---|---|
Basic support | (Yes) | (Yes)[1] | ? | ? | (Yes) |
insertBrOnReturn |
No support | (Yes) | No support | No support | No support |
copy /cut |
42 | 41 (41) | 9 | 29 | 10 |
Feature | Android | Chrome for Android | Firefox Mobile (Gecko) | IE Mobile | Opera Mobile | Safari Mobile |
---|---|---|---|---|---|---|
Basic support | ? | (Yes)[1] | (Yes) | ? | ? | ? |
insertBrOnReturn |
No support | No support | (Yes) | No support | No support | No support |
copy /cut |
No support | 42 | 41.0 (41) | ? | ? | No support |
[1] Before Firefox 41, clipboard capability needed to be enabled in the user.js preference file. See A brief guide to Mozilla preferences for more information. If the command wasn't supported or enabled, execCommand
was raising an exception instead of returning false
.In Firefox 41 and later, clipboard capability are enabled by default in any event handler that is able to pop-up a window (semi-trusted scripts).
See also
HTMLElement.contentEditable
document.designMode
- Rich-Text Editing in Mozilla
- Scribe's "Browser Inconsistencies" documentation with bugs related to
document.execCommand
.?
License
© 2016 Mozilla Contributors
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-us/docs/web/api/document/execcommand