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.6. The text selection APIs

Every browsing context has a selection. The selection may be empty, and the selection may have more than one range (a disjointed selection). The user should be able to change the selection. User agents are not required to let the user select more than one range, and may collapse multiple ranges in the selection to a single range when the user interacts with the selection. (But, of course, the user agent may let the user create selections with multiple ranges.)

This one selection must be shared by all the content of the browsing context (though not by nested browsing contexts), including any editing hosts in the document. (Editing hosts that are not inside a document cannot have a selection.)

If the selection is empty (collapsed, so that it has only one segment and that segment's start and end points are the same) then the selection's position should equal the caret position. When the selection is not empty, this specification does not define the caret position; user agents should follow platform conventions in deciding whether the caret is at the start of the selection, the end of the selection, or somewhere else.

On some platforms (such as those using Wordstar editing conventions), the caret position is totally independent of the start and end of the selection, even when the selection is empty. On such platforms, user agents may ignore the requirement that the cursor position be linked to the position of the selection altogether.

Mostly for historical reasons, in addition to the browsing context's selection, each textarea and input element has an independent selection. These are the text field selections.

The datagrid and select elements also have selections, indicating which items have been picked by the user. These are not discussed in this section.

This specification does not specify how selections are presented to the user. The Selectors specification, in conjunction with CSS, can be used to style text selections using the ::selection pseudo-element. [SELECTORS] [CSS21]

5.6.1. APIs for the browsing context selection

The getSelection() method on the Window interface must return the Selection object representing the selection of that Window object's browsing context.

For historical reasons, the getSelection() method on the HTMLDocument interface must return the same Selection object.

interface Selection {
  readonly attribute Node anchorNode;
  readonly attribute long anchorOffset;
  readonly attribute Node focusNode;
  readonly attribute long focusOffset;
  readonly attribute boolean isCollapsed;
  void collapse(in Node parentNode, in long offset);
  void collapseToStart();
  void collapseToEnd();
  void selectAllChildren(in Node parentNode);
  void deleteFromDocument();
  readonly attribute long rangeCount;
  Range getRangeAt(in long index);
  void addRange(in Range range);
  void removeRange(in Range range);
  void removeAllRanges();
  DOMString toString();
};

The Selection interface is represents a list of Range objects. The first item in the list has index 0, and the last item has index count-1, where count is the number of ranges in the list. [DOM2RANGE]

All of the members of the Selection interface are defined in terms of operations on the Range objects represented by this object. These operations can raise exceptions, as defined for the Range interface; this can therefore result in the members of the Selection interface raising exceptions as well, in addition to any explicitly called out below.

The anchorNode attribute must return the value returned by the startContainer attribute of the last Range object in the list, or null if the list is empty.

The anchorOffset attribute must return the value returned by the startOffset attribute of the last Range object in the list, or 0 if the list is empty.

The focusNode attribute must return the value returned by the endContainer attribute of the last Range object in the list, or null if the list is empty.

The focusOffset attribute must return the value returned by the endOffset attribute of the last Range object in the list, or 0 if the list is empty.

The isCollapsed attribute must return true if there are zero ranges, or if there is exactly one range and its collapsed attribute is itself true. Otherwise it must return false.

The collapse(parentNode, offset) method must raise a WRONG_DOCUMENT_ERR DOM exception if parentNode's ownerDocument is not the HTMLDocument object with which the Selection object is associated. Otherwise it is, and the method must remove all the ranges in the Selection list, then create a new Range object, add it to the list, and invoke its setStart() and setEnd() methods with the parentNode and offset values as their arguments.

The collapseToStart() method must raise an INVALID_STATE_ERR DOM exception if there are no ranges in the list. Otherwise, it must invoke the collapse() method with the startContainer and startOffset values of the first Range object in the list as the arguments.

The collapseToEnd() method must raise an INVALID_STATE_ERR DOM exception if there are no ranges in the list. Otherwise, it must invoke the collapse() method with the endContainer and endOffset values of the last Range object in the list as the arguments.

The selectAllChildren(parentNode) method must invoke the collapse() method with the parentNode value as the first argument and 0 as the second argument, and must then invoke the selectNodeContents() method on the first (and only) range in the list with the parentNode value as the argument.

The deleteFromDocument() method must invoke the deleteContents() method on each range in the list, if any, from first to last.

The rangeCount attribute must return the number of ranges in the list.

The getRangeAt(index) method must return the indexth range in the list. If index is less than zero or greater or equal to the value returned by the rangeCount attribute, then the method must raise an INDEX_SIZE_ERR DOM exception.

The addRange(range) method must add the given range Range object to the list of selections, at the end (so the newly added range is the new last range). Duplicates are not prevented; a range may be added more than once in which case it appears in the list more than once, which (for example) will cause toString() to return the range's text twice.

The removeRange(range) method must remove the first occurrence of range in the list of ranges, if it appears at all.

The removeAllRanges() method must remove all the ranges from the list of ranges, such that the rangeCount attribute returns 0 after the removeAllRanges() method is invoked (and until a new range is added to the list, either through this interface or via user interaction).

The toString() method must return a concatenation of the results of invoking the toString() method of the Range object on each of the ranges of the selection, in the order they appear in the list (first to last).

In language bindings where this is supported, objects implementing the Selection interface must stringify to the value returned by the object's toString() method.

In the following document fragment, the emphasised parts indicate the selection.

<p>The cute girl likes the <cite>Oxford English Dictionary</cite>.</p>

If a script invoked window.getSelection().toString(), the return value would be "the Oxford English".

The Selection interface has no relation to the DataGridSelection interface.

5.6.2. APIs for the text field selections

When we define HTMLTextAreaElement and HTMLInputElement we will have to add the IDL given below to both of their IDLs.

The input and textarea elements define four members in their DOM interfaces for handling their text selection:

  void select();
           attribute unsigned long selectionStart;
           attribute unsigned long selectionEnd;
  void setSelectionRange(in unsigned long start, in unsigned long end);

These methods and attributes expose and control the selection of input and textarea text fields.

The select() method must cause the contents of the text field to be fully selected.

The selectionStart attribute must, on getting, return the offset (in logical order) to the character that immediately follows the start of the selection. If there is no selection, then it must return the offset (in logical order) to the character that immediately follows the text entry cursor.

On setting, it must act as if the setSelectionRange() method had been called, with the new value as the first argument, and the current value of the selectionEnd attribute as the second argument, unless the current value of the selectionEnd is less than the new value, in which case the second argument must also be the new value.

The selectionEnd attribute must, on getting, return the offset (in logical order) to the character that immediately follows the end of the selection. If there is no selection, then it must return the offset (in logical order) to the character that immediately follows the text entry cursor.

On setting, it must act as if the setSelectionRange() method had been called, with the current value of the selectionStart attribute as the first argument, and new value as the second argument.

The setSelectionRange(start, end) method must set the selection of the text field to the sequence of characters starting with the character at the startth position (in logical order) and ending with the character at the (end-1)th position. Arguments greater than the length of the value in the text field must be treated as pointing at the end of the text field. If end is less than or equal to start then the start of the selection and the end of the selection must both be placed immediately before the character with offset end. In UAs where there is no concept of an empty selection, this must set the cursor to be just before the character with offset end.

To obtain the currently selected text, the following JavaScript suffices:

var selectionText = control.value.substring(control.selectionStart, control.selectionEnd);

...where control is the input or textarea element.

Characters with no visible rendering, such as U+200D ZERO WIDTH JOINER, still count as characters. Thus, for instance, the selection can include just an invisible character, and the text insertion cursor can be placed to one side or another of such a character.

When these methods and attributes are used with input elements that are not displaying simple text fields, they must raise an INVALID_STATE_ERR exception.