Selection API

Every document with a browsing context has a unique selection associated with it.

This one selection must be shared by all the content of the document (though not by nested documents), including any editing hosts in the document.

Each selection can be associated with a single range. When there is no range associated with the selection, the selection is empty. The selection must be initially empty.

Once a selection is associated with a given range, it must continue to be associated with that same range until this specification requires otherwise.

If the selection's range is not null and is collapsed, then the caret position must be at that range's boundary point. When the selection is not collapsed, 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.

Each selection has a direction: forwards, backwards, or directionless. If the user creates a selection by indicating first one boundary point of the range and then the other (such as by clicking on one point and dragging to another), and the first indicated boundary point is after the second, then the corresponding selection must initially be backwards. If the first indicated boundary point is before the second, then the corresponding selection must initially be forwards. Otherwise, it must be directionless.

When the selection's range is mutated by scripts, e.g. via selectNode(node), direction of the selection must be preserved.

Each selections also have an anchor and a focus. If the selection's range is null, its anchor and focus are both null. If the selection's range is not null and its direction is forwards, its anchor is the range's start, and its focus is the end. Otherwise, its focus is the start and its anchor is the end.

Each document, input element, and textarea element has a boolean has scheduled selectionchange event, which is initially false.

Selection interface provides a way to interact with the selection associated with each document.

WebIDL[Exposed=Window]
interface Selection {
  readonly attribute Node? anchorNode;
  readonly attribute unsigned long anchorOffset;
  readonly attribute Node? focusNode;
  readonly attribute unsigned long focusOffset;
  readonly attribute boolean isCollapsed;
  readonly attribute unsigned long rangeCount;
  readonly attribute DOMString type;
  readonly attribute DOMString direction;
  Range getRangeAt(unsigned long index);
  undefined addRange(Range range);
  undefined removeRange(Range range);
  undefined removeAllRanges();
  undefined empty();
  sequence<StaticRange> getComposedRanges(optional GetComposedRangesOptions options = {});
  undefined collapse(Node? node, optional unsigned long offset = 0);
  undefined setPosition(Node? node, optional unsigned long offset = 0);
  undefined collapseToStart();
  undefined collapseToEnd();
  undefined extend(Node node, optional unsigned long offset = 0);
  undefined setBaseAndExtent(Node anchorNode, unsigned long anchorOffset, Node focusNode, unsigned long focusOffset);
  undefined selectAllChildren(Node node);
  undefined modify(optional DOMString alter, optional DOMString direction, optional DOMString granularity);
  [CEReactions] undefined deleteFromDocument();
  boolean containsNode(Node node, optional boolean allowPartialContainment = false);
  stringifier;
};

dictionary GetComposedRangesOptions {
  sequence<ShadowRoot> shadowRoots = [];
};

anchorNode

The attribute must return the anchor node of this, or null if the anchor is null or anchor is not in the document tree.

anchorOffset

The attribute must return the anchor offset of this, or 0 if the anchor is null or anchor is not in the document tree.

focusNode

The attribute must return the focus node of this, or null if the focus is null or focus is not in the document tree.

focusOffset

The attribute must return the focus offset of this, or 0 if the focus is null or focus is not in the document tree.

isCollapsed

The attribute must return true if and only if the anchor and focus are the same (including if both are null). Otherwise it must return false.

rangeCount

The attribute must return 0 if this is empty or either focus or anchor is not in the document tree, and must return 1 otherwise.

type

The attribute must return "None" if this is empty or either focus or anchor is not in the document tree, "Caret" if this's range is collapsed, and "Range" otherwise.

direction

The attribute must return "none" if this is empty or this selection is directionless. "forward" if this selection's direction is forwards and "backward" if this selection's direction is backwards.

getRangeAt() method

The method must throw an IndexSizeError exception if index is not 0, or if this is empty or either focus or anchor is not in the document tree. Otherwise, it must return a reference to (not a copy of) this's range.

Note

Thus subsequent calls of this method returns the same range object if nothing has removed this's range in the meantime. In particular, getSelection().getRangeAt(0) === getSelection().getRangeAt(0) evaluates to true if the selection is not empty.

addRange() method

The method must follow these steps:

1. If the root of the range's boundary points are not the document associated with this, abort these steps.
2. If rangeCount is not 0, abort these steps.
3. Set this's range to range by a strong reference (not by making a copy).

Note

Since range is added by reference, subsequent calls to getRangeAt(0) returns the same object, and any changes that a script makes to range after it is added must be reflected in the selection, until something else removes or replaces this's range. In particular, the selection will contain b as opposed to a after running the following code: var r = document.createRange(); r.selectNode(a); getSelection().addRange(r); r.selectNode(b);

Note

At Step 2, Chrome 58 and Edge 25 do nothing. Firefox 51 gives you a multi-range selection. At least they keep the exisiting range.

At Step 3, Chrome 58 and Firefox 51 store a reference, as described here. Edge 25 stores a copy. Firefox 51 changes its selection if the range is modified.

removeRange() method

The method must make this empty by disassociating its range if this's range is range. Otherwise, it must throw a NotFoundError.

removeAllRanges() method

The method must make this empty by disassociating its range if this has an associated range.

empty() method

The method must be an alias, and behave identically, to removeAllRanges().

getComposedRanges() method

1. If this is empty, return an empty array.
2. Otherwise, let startNode be start node of the range associated with this, and let startOffset be start offset of the range.
3. While startNode is a node, startNode's root is a shadow root, and startNode's root is not a shadow-including inclusive ancestor of any of options["shadowRoots"], repeat these steps:
   1. Set startOffset to index of startNode's root's host.
   2. Set startNode to startNode's root's host's parent.
4. Let endNode be end node of the range associated with this, and let endOffset be end offset of the range.
5. While endNode is a node, endNode's root is a shadow root, and endNode's root is not a shadow-including inclusive ancestor of any of options["shadowRoots"], repeat these steps:
   1. Set endOffset to index of endNode's root's host plus 1.
   2. Set endNode to endNode's root's host's parent.
6. Return an array consisting of new StaticRange whose start node is startNode, start offset is startOffset, end node is endNode, and end offset is endOffset.

collapse() method

The method must follow these steps:

1. If node is null, this method must behave identically as removeAllRanges() and abort these steps.
2. If node is a DocumentType, throw an InvalidNodeTypeError exception and abort these steps.
3. The method must throw an IndexSizeError exception if offset is longer than node's length and abort these steps.
4. If document associated with this is not a shadow-including inclusive ancestor of node, abort these steps.
5. Otherwise, let newRange be a new range.
6. Set the start the start and the end of newRange to (node, offset).
7. Set this's range to newRange.

setPosition() method

The method must be an alias, and behave identically, to collapse().

collapseToStart() method

The method must throw InvalidStateError exception if the this is empty. Otherwise, it must create a new range, set the start both its start and end to the start of this's range, and then set this's range to the newly-created range.

Note

For collapseToStart/End, IE9 mutates the existing range, while Firefox 9.0a2 and Chrome 15 dev replace it with a new one. The spec follows the majority and replaces it with a new one, leaving the old Range object unchanged.

collapseToEnd() method

The method must throw InvalidStateError exception if the this is empty. Otherwise, it must create a new range, set the start both its start and end to the end of this's range, and then set this's range to the newly-created range.

extend() method

The method must follow these steps:

1. If the document associated with this is not a shadow-including inclusive ancestor of node, abort these steps.
2. If this is empty, throw an InvalidStateError exception and abort these steps.
3. Let oldAnchor and oldFocus be the this's anchor and focus, and let newFocus be the boundary point (node, offset).
4. Let newRange be a new range.
5. If node's root is not the same as the this's range's root, set the start newRange's start and end to newFocus.
6. Otherwise, if oldAnchor is before or equal to newFocus, set the start newRange's start to oldAnchor, then set its end to newFocus.
7. Otherwise, set the start newRange's start to newFocus, then set its end to oldAnchor.
8. Set this's range to newRange.
9. If newFocus is before oldAnchor, set this's direction to backwards. Otherwise, set it to forwards.

Note

Reverse-engineered circa January 2011. IE doesn't support it, so I'm relying on Firefox (implemented extend() sometime before 2000) and WebKit (implemented extend() in 2007). I'm mostly ignoring Opera, because gsnedders tells me its implementation isn't compatible. Firefox 12.0a1 seems to mutate the existing range. IE9 doesn't support extend(), and it's impossible to tell whether Chrome 17 dev or Opera Next 12.00 alpha mutate or replace, because getRangeAt() returns a copy anyway. Nevertheless, I go against Gecko here, to be consistent with collapse().

setBaseAndExtent() method

The method must follow these steps:

1. If anchorOffset is longer than anchorNode's length or if focusOffset is longer than focusNode's length, throw an IndexSizeError exception and abort these steps.
2. If document associated with this is not a shadow-including inclusive ancestor of anchorNode or focusNode, abort these steps.
3. Let anchor be the boundary point (anchorNode, anchorOffset) and let focus be the boundary point (focusNode, focusOffset).
4. Let newRange be a new range.
5. If anchor is before focus, set the start the newRange's start to anchor and its end to focus. Otherwise, set the start them to focus and anchor respectively.
6. Set this's range to newRange.
7. If focus is before anchor, set this's direction to backwards. Otherwise, set it to forwards

selectAllChildren() method

The method must follow these steps:

1. If node is a DocumentType, throw an InvalidNodeTypeError exception and abort these steps.
2. If node's root is not the document associated with this, abort these steps.
3. Let newRange be a new range and childCount be the number of children of node.
4. Set newRange's start to (node, 0).
5. Set newRange's end to (node, childCount).
6. Set this's range to newRange.
7. Set this's direction to forwards.

Note

Based mostly on Firefox 9.0a2. It has a bug that I didn't reproduce, namely that if you pass a Document as the argument, the end offset becomes 1 instead of the number of children it has. It also throws a RangeException instead of DOMException, because its implementation predated their merging.

IE9 behaves similarly but with glitches. It throws "Unspecified error." if the node is detached or display:none, and apparently in some random other cases too. It throws "Invalid argument." for detached comments (only!). Finally, if you pass it a comment, it seems to select the whole comment, unlike with text nodes.

Chrome 16 dev behaves as you'd expect given its Selection implementation. It refuses to select anything that's not visible, so it's almost always wrong. Opera 11.50 just does nothing in all my tests, as usual.

The new range replaces any existing one, doesn't mutate it. This matches IE9 and Firefox 12.0a1. (Chrome 17 dev and Opera Next 12.00 alpha can't be tested, because getRangeAt() returns a copy anyway.)

modify() method

The method must follow these steps:

1. If alter is not ASCII case-insensitive match with "extend" or "move", abort these steps.
2. If direction is not ASCII case-insensitive match with "forward", "backward", "left", or "right", abort these steps.
3. If granularity is not ASCII case-insensitive match with "character", "word", "sentence", "line", "paragraph", "lineboundary", "sentenceboundary", "paragraphboundary", "documentboundary", abort these steps.
4. If this selection is empty, abort these steps.
5. Let effectiveDirection be backwards.
6. If direction is ASCII case-insensitive match with "forward", set effectiveDirection to forwards.
7. If direction is ASCII case-insensitive match with "right" and inline base direction of this selection's focus is ltr, set effectiveDirection to forwards.
8. If direction is ASCII case-insensitive match with "left" and inline base direction of this selection's focus is rtl, set effectiveDirection to forwards.
9. Set this selection's direction to effectiveDirection.
10. If alter is ASCII case-insensitive match with "extend", set this selection's focus to the location as if the user had requested to extend selection by granularity.
11. Otherwise, set this selection's focus and anchor to the location as if the user had requested to move selection by granularity.

Note

We need to more precisely define what it means to extend or move selection by each granularity.

deleteFromDocument() method

The method must invoke deleteContents() on this's range if this is not empty and both focus and anchor are in the document tree. Otherwise the method must do nothing.

Note

This is the one method that actually mutates the range instead of replacing it. This matches IE9 and Firefox 12.0a1. (Chrome 17 dev and Opera Next 12.00 alpha can't be tested, because getRangeAt() returns a copy anyway.)

containsNode() method

The method must return false if this is empty or if node's root is not the document associated with this.

Otherwise, if allowPartialContainment is false, the method must return true if and only if start of its range is before or visually equivalent to the first boundary point in the node and end of its range is after or visually equivalent to the last boundary point in the node.

If allowPartialContainment is true, the method must return true if and only if start of its range is before or visually equivalent to the last boundary point in the node and end of its range is after or visually equivalent to the first boundary point in the node.

stringifier

The stringification must return the string, which is the concatenation of the rendered text if there is a range associated with this.

If the selection is within a textarea or input element, it must return the selected substring in its value.

All of the members of the Selection interface are defined in terms of operations on the range object (if any) represented by the 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 above.

This specification extends several interfaces to provide entry points to the interfaces defined in this specification.

WebIDLpartial interface Document {
  Selection? getSelection();
};

WebIDLpartial interface Window {
  Selection? getSelection();
};

WebIDLpartial interface mixin GlobalEventHandlers {
  attribute EventHandler onselectstart;
  attribute EventHandler onselectionchange;
};

When the user agent is to replace data or substring data on CharacterData, the user agent must update the range associated with selection of the node document of the CharacterData as if it's a live range.

When the user agent is to split a Text node, the user agent must update the range associated with selection of the node document of the Text as if it's a live range.

When the user agent is to run steps for normalize() method, the user agent must update the range associated with selection of the node document of this as if it's a live range.

When the user agent is to remove or insert a node, the user agent must update the range associated with selection of the node document of the node as if it's a live range.

The user agent should allow the user to change the selection associated with the active document. If the user makes any modification to a selection, the user agent must create a new range with suitable start and end of the range and associate the selection with this new range (not modify the existing range), and set update selection's direction to forwards if the start is before or equal to the end, backwards if if the end is before the start, or directionless if the start and the end cannot be ordered due to the platform convention.

The user agent must not make a selection empty if it was not already empty in response to any user actions (e.g. clicking on a non-editable region).

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

This specification defines conformance criteria that apply to a single product: the user agent that implements the interfaces that it contains.

There are no known security considerations for this standard.

To mitigate potential privacy risks of exposing user's use of assistive technologies, for example, user agent may elect to emulate mouse and keyboard events typically associated with selectstart or selectionchange events when the user opts to modify the selection of a document.