Selection API

The Selection API provides functionality for reading and manipulating the range of text selected by the user.

Concepts and usage

To retrieve the current text range the user has selected, you can use the Window.getSelection() or Document.getSelection() method, storing the return value — a Selection object — in a variable for futher use.

Once your selection is in a variable, you perform a variety of operations on it, for example copying the selection to a text string using Selection.toString(), adding a range (as represented by a standard Range object) to the selection (or removing one) with Selection.addRange()/Selection.removeRange(), or changing the selection to be the entire contents of a DOM node using Selection.selectAllChildren().

You can run code in response to the selection being changed, or a new selection being started, using the GlobalEventHandlers.onselectionchange and GlobalEventHandlers.onselectstart event handlers.

Selection API interfaces

Selection
Represents the range of text selected by the user or the current position of the caret.

Extensions to other interfaces

Window.getSelection(), Document.getSelection()
Returns a Selection object representing the range of text selected by the user or the current position of the caret. Document.getSelection() is basically an alias of Window.getSelection().
GlobalEventHandlers.onselectstart
Represents the event handler that is called when a selectstart event is fired on the current object (i.e. when a new range of text is about to be selected by the user).
GlobalEventHandlers.onselectionchange
Represents the event handler that is called when a selectionchange event is fired on the current object (i.e. when the selected text range changes).

Specifications

Specification Status Comment
Selection API
The definition of 'Selection' in that specification.
Working Draft The Selection API specification is based on the HTML Editing APIs specification and focuses on the Selection-related functionality.
HTML Editing APIs
The definition of 'Selection' in that specification.
Editor's Draft Initial (older) definition, which is now outdated.

Browser compatibility

Feature Chrome Edge Firefox (Gecko) Internet Explorer Opera Safari (WebKit)
Basic support (Yes) (Yes) (Yes)
52 (52)[1]
9 (Yes) (Yes)
modify() (Yes) ? 4.0 (2) ? ? (Yes)
setBaseAndExtent() ? ? 53 (53) ? ? ?
collapse() and extend() offset parameter is optional; collapse() node parameter is nullable; containsNode() partialContainment parameter is optional. (Yes) ? 55 (55) No support (Yes) (Yes)
deleteFromDocument() ? (Yes) 55 (55) ? ? ?
empty() and setPosition() as aliases of removeAllRanges() and collapse() (Yes) ? 55 (55) ? (Yes) (Yes)
Feature Android Edge Firefox Mobile (Gecko) IE Phone Opera Mobile Safari Mobile
Basic support ? (Yes)

(Yes)
52.0 (52)[1]

? ? (Yes)
modify() ? ? 4.0 (2) ? ? (Yes)
setBaseAndExtent() ? ? 53.0 (53) ? ? ?
collapse() and extend() offset parameter is optional; collapse() node parameter is nullable; containsNode() partialContainment parameter is optional. ? ? 55.0 (55) ? ? (Yes)
deleteFromDocument() ? (Yes) 55.0 (55) ? ? ?
empty() and setPosition() as aliases of removeAllRanges() and collapse() ? ? 55.0 (55) ? (Yes) (Yes)

[1] The GlobalEventHandlers.onselectionchange and GlobalEventHandlers.onselectstart event handlers are suported as of Firefox 52.

See also

Document Tags and Contributors

 Contributors to this page: chrisdavidmills
 Last updated by: chrisdavidmills,