This is a snapshot of an early working draft and has therefore been superseded by the HTML standard.

This document will not be further updated.

HTML 5

Call For Comments — 27 October 2007

5.2. The contenteditable attribute

The contenteditable attribute is a common attribute. User agents must support this attribute on all HTML elements.

The contenteditable 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, which is also the invalid value default. There is no missing value default.

If an HTML element has a contenteditable attribute set to the true state, or if its nearest ancestor with the contenteditable attribute set has its attribute set to the true state, or if it has no ancestors with the contenteditable attribute set but the Document has designMode enabled, then the UA must treat the element as editable (as described below).

Otherwise, either the HTML element has a contenteditable attribute set to the false state, or its nearest ancestor with the contenteditable attribute set is not editable, or it has no ancestor with the contenteditable attribute set and the Document itself has designMode disabled, and the element is thus not editable.

The contentEditable DOM attribute, on getting, must return the string "inherit" if the content attribute isn't set, "true" if the attribute is set and has the true state, and "false" otherwise. On setting, if the new value is case-insensitively equal to the string "inherit" then the content attribute must be removed, if the new value is case-insensitively equal to the string "true then the content attribute must be set to the string "true, if the new value is case-insensitively equal to the string "false then the content attribute must be set to the string "false, and otherwise the attribute setter must raise a SYNTAX_ERR exception.

If an element is editable and its parent element is not, or if an element is editable and it has no parent element, then the element is an editing host. Editable elements can be nested. User agents must make editing hosts focusable (which typicially means they enter the tab order). An editing host can contain non-editable sections, these are handled as described below. An editing host can contain non-editable sections that contain further editing hosts.

When an editing host has focus, it must have a caret position that specifies where the current editing position is. It may also have a selection.

How the caret and selection are represented depends entirely on the UA.

5.2.1. User editing actions

There are several actions that the user agent should allow the user to perform while the user is interacting with an editing host. How exactly each action is triggered is not defined for every action, but when it is not defined, suggested key bindings are provided to guide implementors.

Move the caret

User agents must allow users to move the caret to any position within an editing host, even into nested editable elements. This could be triggered as the default action of keydown events with various key identifiers and as the default action of mouseydown events.

Change the selection

User agents must allow users to change the selection within an editing host, even into nested editable elements. This could be triggered as the default action of keydown events with various key identifiers and as the default action of mouseydown events.

Insert text

This action must be triggered as the default action of a textInput event, and may be triggered by other commands as well. It must cause the user agent to insert the specified text (given by the event object's data attribute in the case of the textInput event) at the caret.

If the caret is positioned somewhere where inline-level content is not allowed (e.g. because the element accepts "both block-level and inline-level content but not both", and the element already contains block-level content), then the user agent must not insert the text directly at the caret position. In such cases the behaviour is UA-dependent, but user agents must not, in response to a request to insert text, generate a DOM that is less conformant than the DOM prior to the request.

User agents should allow users to insert new paragraphs into elements that only contain block-level content.

For example, given the markup:

<section>
 <dl>
  <dt> Ben </dt>
  <dd> Goat </dd>
 </dl>
</section>

...the user agent should allow the user to insert p elements before and after the dl element, as children of the section element.

Break block

UAs should offer a way for the user to request that the current block be broken at the caret, e.g. as the default action of a keydown event whose identifier is the "Enter" key and that has no modifiers set.

The exact behaviour is UA-dependent, but user agents must not, in response to a request to break a block, generate a DOM that is less conformant than the DOM prior to the request.

Insert a line separator

UAs should offer a way for the user to request an explicit line break at the caret position without breaking the block, e.g. as the default action of a keydown event whose identifier is the "Enter" key and that has a shift modifier set. Line separators are typically found within a poem verse or an address. To insert a line break, the user agent must insert a br element.

If the caret is positioned somewhere where inline-level content is not allowed (e.g. because the element accepts "both block-level and inline-level content but not both", and the element already contains block-level content), then the user agent must not insert the br element directly at the caret position. In such cases the behaviour is UA-dependent, but user agents must not, in response to a request to insert a line separator, generate a DOM that is less conformant than the DOM prior to the request.

Delete

UAs should offer a way for the user to delete text and elements, e.g. as the default action of keydown events whose identifiers are "U+0008" or "U+007F".

Five edge cases in particular need to be considered carefully when implementing this feature: backspacing at the start of an element, backspacing when the caret is immediately after an element, forward-deleting at the end of an element, forward-deleting when the caret is immediately before an element, and deleting a selection whose start and end points do not share a common parent node.

In any case, the exact behaviour is UA-dependent, but user agents must not, in response to a request to delete text or an element, generate a DOM that is less conformant than the DOM prior to the request.

Insert, and wrap text in, semantic elements

UAs should offer a way for the user to mark text as having stress emphasis and as being important, and may offer the user the ability to mark text and blocks with other semantics.

UAs should similarly offer a way for the user to insert empty semantic elements (such as, again, em, strong, and others) to subsequently fill by entering text manually.

UAs should also offer a way to remove those semantics from marked up text, and to remove empty semantic element that have been inserted.

The exact behaviour is UA-dependent, but user agents must not, in response to a request to wrap semantics around some text or to insert or remove a semantic element, generate a DOM that is less conformant than the DOM prior to the request.

Select and move non-editable elements nested inside editing hosts

UAs should offer a way for the user to move images and other non-editable parts around the content within an editing host. This may be done using the drag and drop mechanism. User agents must not, in response to a request to move non-editable elements nested inside editing hosts, generate a DOM that is less conformant than the DOM prior to the request.

Edit form controls nested inside editing hosts

When an editable form control is edited, the changes must be reflected in both its current value and its default value. For input elements this means updating the defaultValue DOM attribute as well as the value DOM attribute; for select elements it means updating the option elements' defaultSelected DOM attribute as well as the selected DOM attribute; for textarea elements this means updating the defaultValue DOM attribute as well as the value DOM attribute. (Updating the default* DOM attributes causes content attributes to be updated as well.)

User agents may perform several commands per user request; for example if the user selects a block of text and hits Enter, the UA might interpret that as a request to delete the content of the selection followed by a request to break the block at that position.

5.2.2. Making entire documents editable

Documents have a designMode, which can be either enabled or disabled.

The designMode DOM attribute on the Document object takes takes two values, "on" and "off". When it is set, the new value must be case-insensitively compared 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.

When designMode is enabled, the DOM attribute must return the value "on", and when it is disabled, it 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.

Enabling designMode causes scripts in general to be disabled and the document to become editable.

When the Document has designMode enabled, event listeners registered on the document or any elements owned by the document must do nothing.