Enabling in-browser editing of HTML content.
This specification is an experimental breakup of the HTML specification. You can see the full list on the index page and take part in the discussion in the repository.
contenteditable
content attribute[NoInterfaceObject] interface ElementContentEditable { attribute DOMString contentEditable; readonly attribute boolean isContentEditable; };
The contenteditable
content attribute is an
enumerated attribute whose keywords are the empty string, true
,
and false
. The empty string and the true
keyword map
to the true state. The false
keyword maps to the false state.
In addition, there is a third state, the inherit state, which is the missing value default (and the invalid value default).
The true state indicates that the element is editable. The inherit state indicates that the element is editable if its parent is. The false state indicates that the element is not editable.
contentEditable
[ = value ]Returns "true
", "false
", or "inherit
", based on the state of the contenteditable
attribute.
Can be set, to change that state.
Throws a SyntaxError
exception if the new value isn't one of those strings.
isContentEditable
Returns true if the element is editable; otherwise, returns false.
The contentEditable
IDL attribute, on
getting, must return the string "true
" if the content attribute is set to
the true state, "false
" if the content attribute is set to the false state,
and "inherit
" otherwise. On setting, if the new value is an ASCII
case-insensitive match for the string "inherit
" then the content
attribute must be removed, if the new value is an ASCII case-insensitive match for
the string "true
" then the content attribute must be set to the string
"true
", if the new value is an ASCII case-insensitive match for
the string "false
" then the content attribute must be set to the string
"false
", and otherwise the attribute setter must throw a
SyntaxError
exception.
The isContentEditable
IDL attribute, on
getting, must return true if the element is either an editing host or
editable, and false otherwise.
designMode
IDL attributeDocuments have a designMode
, which can be either enabled or
disabled.
designMode
[ = value ]Returns "on
" if the document is editable, and "off
" if it isn't.
Can be set, to change the document's current state. This focuses the document and resets the selection in that document.
The designMode
IDL attribute on the
Document
object takes two values, "on
" and "off
". On setting, the new value must be compared in an ASCII
case-insensitive manner to these two values; if it matches the "on
"
value, then designMode
must be enabled, and if it
matches the "off
" value, then designMode
must be disabled. Other values must be
ignored.
On getting, if designMode
is enabled, the IDL
attribute must return the value "on
"; otherwise it is disabled, and the
attribute must return the value "off
".
The last state set must persist until the document is destroyed or the state is changed.
Initially, documents must have their designMode
disabled.
When the designMode
changes from being disabled to
being enabled, the user agent must immediately reset the document's active range's
start and end boundary points to be at the start of the Document
and then run the
focusing steps for the root element of the Document
, if any.
Authors are encouraged to set the 'white-space' property on editing hosts and on markup that was originally created through these editing mechanisms to the value 'pre-wrap'. Default HTML whitespace handling is not well suited to WYSIWYG editing, and line wrapping will not work correctly in some corner cases if 'white-space' is left at its default value.
As an example of problems that occur if the default 'normal' value is used instead, consider the case of the user typing "yellow␣␣ball", with two spaces (here represented by "␣") between the words. With the editing rules in place for the default value of 'white-space' ('normal'), the resulting markup will either consist of "yellow ball" or "yellow ball"; i.e., there will be a non-breaking space between the two words in addition to the regular space. This is necessary because the 'normal' value for 'white-space' requires adjacent regular spaces to be collapsed together.
In the former case, "yellow⍽" might wrap to the next line ("⍽" being used here to represent a non-breaking space) even though "yellow" alone might fit at the end of the line; in the latter case, "⍽ball", if wrapped to the start of the line, would have visible indentation from the non-breaking space.
When 'white-space' is set to 'pre-wrap', however, the editing rules will instead simply put two regular spaces between the words, and should the two words be split at the end of a line, the spaces would be neatly removed from the rendering.
The definition of the terms active range, editing host, and
editable, the user interface requirements of elements that are editing hosts or editable, the
execCommand()
,
queryCommandEnabled()
,
queryCommandIndeterm()
,
queryCommandState()
,
queryCommandSupported()
, and
queryCommandValue()
methods, text selections, and the delete the selection algorithm are defined in the
HTML Editing APIs specification. [[!EDITING]]
User agents can support the checking of spelling and grammar of editable text, either in form
controls (such as the value of textarea
elements), or in elements in an editing
host (e.g. using contenteditable
).
For each element, user agents must establish a default behaviour, either through defaults or through preferences expressed by the user. There are three possible default behaviours for each element:
The spellcheck
attribute is an enumerated
attribute whose keywords are the empty string, true
and false
. The empty string and the true
keyword map to the
true state. The false
keyword maps to the false state. In
addition, there is a third state, the default state, which is the missing value default (and the invalid value default).
The true state indicates that the element is to have its spelling and
grammar checked. The default state indicates that the element is to act according to a
default behaviour, possibly based on the parent element's own spellcheck
state, as defined below. The false state
indicates that the element is not to be checked.
spellcheck
[ = value ]Returns true if the element is to have its spelling and grammar checked; otherwise, returns false.
Can be set, to override the default and set the spellcheck
content attribute.
forceSpellCheck
()Forces the user agent to report spelling and grammar errors on the element (if checking is enabled), even if the user has never focused the element. (If the method is not invoked, user agents can hide errors in text that wasn't just entered by the user.)
The spellcheck
IDL attribute, on getting, must
return true if the element's spellcheck
content attribute is
in the true state, or if the element's spellcheck
content attribute is in the default state and the element's default behaviour is true-by-default, or if the element's spellcheck
content attribute is in the default state and the
element's default behaviour is inherit-by-default and the element's parent
element's spellcheck
IDL attribute would return true;
otherwise, if none of those conditions applies, then the attribute must instead return false.
The spellcheck
IDL attribute is not affected
by user preferences that override the spellcheck
content
attribute, and therefore might not reflect the actual spellchecking state.
On setting, if the new value is true, then the element's spellcheck
content attribute must be set to the literal string
"true
", otherwise it must be set to the literal string "false
".
User agents must only consider the following pieces of text as checkable for the purposes of this feature:
input
elements whose type
attributes are in the Text, Search,
URL, or E-mail states and that are mutable (i.e. that do not have the readonly
attribute specified and that are not disabled).textarea
elements that do not
have a readonly
attribute and that are not disabled.Text
nodes that are children of editing
hosts or editable elements.For text that is part of a Text
node, the element with which the text is
associated is the element that is the immediate parent of the first character of the word,
sentence, or other piece of text. For text in attributes, it is the attribute's element. For the
values of input
and textarea
elements, it is the element itself.
To determine if a word, sentence, or other piece of text in an applicable element (as defined above) is to have spelling- and grammar-checking enabled, the UA must use the following algorithm:
spellcheck
content attribute, then: if that attribute is in the
true state, then checking is enabled; otherwise, if that attribute is in the false
state, then checking is disabled.spellcheck
content attribute that is not in the default
state, then: if the nearest such ancestor's spellcheck
content attribute is in the true state, then checking is enabled; otherwise, checking is
disabled.If the checking is enabled for a word/sentence/text, the user agent should indicate spelling
and grammar errors in that text. User agents should take into account the other semantics given in
the document when suggesting spelling and grammar corrections. User agents may use the language of
the element to determine what spelling and grammar rules to use, or may use the user's preferred
language settings. UAs should use input
element attributes such as pattern
to ensure that the resulting value is valid, where
possible.
If checking is disabled, the user agent should not indicate spelling or grammar errors for that text.
Even when checking is enabled, user agents may opt to not report spelling or grammar errors in
text that the user agent deems the user has no interest in having checked (e.g. text that was
already present when the page was loaded, or that the user did not type, or text in controls that
the user has not focused, or in parts of e-mail addresses that the user agent is not confident
were misspelt). The forceSpellCheck()
method,
when invoked on an element, must override this behaviour, forcing the user agent to consider all
spelling and grammar errors in text in that element for which checking is enabled to be of
interest to the user.
The element with ID "a" in the following example would be the one used to determine if the word "Hello" is checked for spelling errors. In this example, it would not be.
<div contenteditable="true"> <span spellcheck="false" id="a">Hell</span><em>o!</em> </div>
The element with ID "b" in the following example would have checking enabled (the leading
space character in the attribute's value on the input
element causes the attribute
to be ignored, so the ancestor's value is used instead, regardless of the default).
<p spellcheck="true"> <label>Name: <input spellcheck=" false" id="b"></label> </p>
This specification does not define the user interface for spelling and grammar checkers. A user agent could offer on-demand checking, could perform continuous checking while the checking is enabled, or could use other interfaces.