This specification defines allowed values and expected behaviors for the contenteditable attribute. This specification builds on HTML5.
This section is not normative.
This spec seeks to alleviate the problem by providing a simple way for web developers prevent all browser default handling of editing operations at different levels without having to preventDefault each of them.
This section is not normative.
contenteditable=truecurrently creates caret placement issues in several browsers.
All positions in which the caret can be placed programmatically. The placement is restricted to the following positions. Implementations MUST be able to place the caret in all of the following positions:
There are some exceptions to these rules:
The following items are defined in the CSS Cascading and Inheritance Level 3 specification [[!css-cascade-3]]
The contenteditable attribute is an enumerated attribute whose keywords
are the empty string (""), "events", "caret", "typing", "plaintext-only",
"true", and "false". There is one additional state, the
inherit state, which is the missing value default (and the
invalid value default).
The empty string and the "true" keyword map to the
state. The other keywords map to their respective states.
false state indicates that the element is not editable.
inherit state indicates that the element has the state
of its parent.
The contentEditable IDL attribute, on getting, must return the string
"true" if the content attribute is set to the
"typing" if the content attribute is set to the
"caret" if the content attribute is set to the
"events" if the content attribute is set to the
"false" if the content attribute is set to the
"plaintext-only" if the content attribute is set to the
plaintext-only state, and
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 a string matching the name of a state, then the content attribute must be set to the name of that state, 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.
The states "events", "caret", "typing" and "true" are hierarchically ordered, so that the state "caret" also includes the features of the "events" state, the "typing" state includes the features of the "caret" state, and the "true" state includes all the features of the "typing" state.
The "events" state means that beforeinput events are triggered when the user asks for an editing operation. The "caret" state adds default browser controlled movement of the caret. The "typing" state adds handling of text input through IME and keyboard, and deletion within an IME composition. The "true" state adds handling of deletion of content for keyboard input as well as deletion of non-textual content and editing commands through the execCommand command.
The states "events", "caret" and "typing" are defined in this document.
The state "true" is currently not well-defined and its usage is discouraged. An initial attempt has been made to specify the behavior of the "true" state in the contentEditable=True spec.
The state "plaintext-only" is deprecated and its usage is discouraged.
In a focused editing host that is in the events state, a caret MUST be drawn if the selection is collapsed, and it MUST be possible to place the caret in all of the Legal Caret Positions programmatically.
All user editing intentions initiated while an editing host that is in the events state is focused, MUST trigger a `beforeinput` event.
A focused editing host that is in the caret state MUST behave like an editing host in the events state. Additionally, the default action of the `beforeSelectionChange` event in such an editing host must be to move the caret in the indicated direction, if movement in that direction seems possible.
Notice the planned beforeSelectionChange event.
A focused editing host that is in the typing state MUST behave like an editing host in the caret state, and additionally, it MUST handle text insertion by keyboard at the position of the caret if the caret is placed within a text node or it is possible to place a text node at the place of the caret. It must by default also handle composition by IME, both insertion as well as deletion of text input.
Within an editing host that is in the "events", "caret" or "typing" state, cutting and pasting is disabled. However, `cut` and `paste` events are still triggered.
A caret is drawn in any editing host that is focused, that does not hold any other selections. Under such conditions, the caret represents a collapsed selection.
It MUST be possible to put the caret in any of the Legal Caret Positions programatically and for the caret to be visible in these in any editing host that is in the "events", "caret" or "typing" state.
Carets are initially placed at the first possible position within the editing host.
The specific location that the caret is moved to by default in an editing host in the "caret" and "typing" state, is out of scope for this specification, but later versions of this specification or specifications covering other contentEditable specifications may further specify the movement patterns of the caret.
When the user indicates the wish to replace part of the contents of a editing host, by means of a browser-builtin spell checker or alike, a `beforeinput` input with `inputType` set to `replaceText` or `replaceContent` is triggered. No part of the DOM is being changed by default in an editing host that is in the "events", "caret" or "typing" state.
Content is not removed automatically through user input in an editing host that is in the "events" or "caret" state. Instead, Del/Backspace key presses, etc. trigger user `beforeinput` events with `inputType` set to `deleteContentForward` or `deleteContentBackward`. The same is true for any editing host that is in the "typing" state, unless it is currently in the composition mode, in which case it will remove characters from the DOM if they are part of the composition.
An implementation CAN provide spell check, grammar check and other advanced functionality that are not defined through a specification for any editing host. These features MUST be disabled by default.
If the implementation provides a `context menu`, this `context menu` SHOULD contain items for editing operations such as `paste`, `cut`, `copy`, `delete` and CAN contain items for spellchecking for any editing host. Triggering any of `context menu` items MUST NOT by default cause any change to the DOM, `paste`, `cut` and `beforeinput` events SHOULD be triggered. Menu items in a `context menu` that do not cause DOM changes by default SHOULD function as in any other editing context.
Thanks to: Michael Aufreiter, Adrian Bateman, Robin Berjon, Oliver Buchtala, Enrica Casucci, Olivier Forget, Aryeh Gregor, Marijn Haverbeke, Yoshifumi Inoue, Koji Ishii, Gary Kacmarcik, Frederico Caldeira Knabben, Takayoshi Kochi, Piotrek Koszuliński, Travis Leithead, Grisha Lyukshin, Chaals McCathie Nevile, Masayuki Nakano, Ryosuke Niwa, Julie Parent, Ben Peters, Florian Rivoal, Hallvord R. M. Steen, Johan Sörlin, Cristian Talau, Ojan Vafai, Xiaoqian Wu, Chong Zhang, Joanmarie, and everyone in the Editing Taskforce for their input and feedback.