This specification defines allowed values and expected behaviors for the contenteditable attribute. This specification builds on HTML5.

Problems solved

This section is not normative.

Creating a webbased texteditor requires a considerable amount of JavaScript on top of the browser code, among other things because:

1. Browsers do not handle all editing operations the same way.
2. Browsers are often buggy in the way they handle certain editing operations.
3. Individual sites may have custom preferences for how they want to handle certain editing operations.
4. The development of hihg-level text editing features in browsers has not followed the principles laid out in the Extensible Web Manifesto in that development of these features has not always been in coordination with the needs of the web developer community.

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.

Use cases

This section is not normative.

1. Creating a JavaScript text editor in which the <strong>-tag is used instead of the <b>-tag to mark text that the user marks as bold, using any browser-builtin way to mark a text as bold, without having access to all existing browsers.
2. Creating a JavaScript text editor which works with a data model in the background where JavaScript takes care of rendering changes to the edited text to the DOM.
3. Creating a JavaScript editor which only allows a subset of richtext editing (for example: bold is allowed, but italic not).
4. Creating a collaborative editor in which JavaScript is used to render changes to the DOM, based on user intentions with users using different browsers with different ways of expressing specific intentions.
5. Creating a JavaScript editor with different user access options, where some users only can add or delete text and other users only can add or remove certain types of formatting.
6. Creating a JavaScript editor in which carte movement is handled differently from the default.
7. Creating a JavaScript editor with advanced elements, such as non-editable regions, inline SVGs, canvas-elements and other elements for which contenteditable=true currently creates caret placement issues in several browsers.

Terminology

editing host

An editing host is a node that is an HTML element with a contenteditable attribute set to something else than the `false` state.

contentEditable=false element

Any element that has the contentEditable attribute set to `false`.

Inline elements

All element nodes for whom the used value of the `display` property resolves to the value `inline`.

Block elements

All element nodes for whom the used value of the `display` property resolves to the value `block`.

Stub elements

All element nodes that are void elements OR root elements using a different namespace than their parent elements (such as SVGs).

Invisible elements

All element nodes for whom the used value of the `display` property resolves to the value `none`.

Legal Caret Positions

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:

1. Before or after any character in any text node.
2. After inline elements that do not have a `nextSibling` which is a text node.
3. Before inline elements that that do not have a `previousSibling`.
4. Inside empty inline elements and block elements that are not stub elements.
5. Inside empty text nodes.
6. Before or after block elements that are also stub elements.
7. Before or after comment nodes.
8. In the editing hostitself, if it is empty.

There are some exceptions to these rules:

1. Within a table, the caret can only be placed inside `TH`, `TD` and `CAPTION` elements.
2. The caret cannot be placed inside invisible elements.
3. The caret cannot be placed inside elements who's contentEditable attribute returns `false`.

The following items are defined in the CSS Cascading and Inheritance Level 3 specification [[!css-cascade-3]]

• used value

contenteditable

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 true state. The other keywords map to their respective states.

The false state indicates that the element is not editable. The 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 true state, "typing" if the content attribute is set to the typing state, "caret" if the content attribute is set to the caret state, "events" if the content attribute is set to the events state, "false" if the content attribute is set to the false state, "plaintext-only" if the content attribute is set to the plaintext-only 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 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.

Meaning of states

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.

contentEditable states

Cutting and pasting

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.

Caret drawing and movement