JavaScript Reference ยท DOM: Document and Elements
Selection and Range
Reference for the Selection and Range APIs: window.getSelection(), toString(), createRange(), setStart(), surroundContents(), input selection and the selectionchange event.
Two linked APIs describe text selection on a page. A Range is a contiguous slice of the document, from one point (a node and an offset) to another. A Selection is the user's current highlighted text, and it holds one or more ranges. window.getSelection() returns the selection object; document.createRange() makes new ranges you can select, measure or modify.
Text inside <input> and <textarea> is handled separately with selectionStart, selectionEnd and setSelectionRange().
const selection = window.getSelection(); console.log(selection.toString()); const range = document.createRange(); range.selectNodeContents(paragraph);
Try it
Syntax
const selection = window.getSelection(); // or document.getSelection() const range = document.createRange();
Selection members
| Name | Description |
|---|---|
toString() |
The selected text as the user would copy it. |
rangeCount |
Number of ranges (0 or 1 in most browsers). |
getRangeAt(i) |
The range at that index; throws IndexSizeError if out of range. |
addRange(range) / removeAllRanges() / removeRange(range) |
Change what is selected. |
isCollapsed |
true for a caret with no selected text. |
anchorNode, anchorOffset, focusNode, focusOffset |
Where the selection started and ended (the focus can come before the anchor). |
selectAllChildren(node) |
Selects all content of a node. |
collapse(node, offset) / collapseToStart() / collapseToEnd() |
Place the caret. |
setBaseAndExtent(aNode, aOffset, fNode, fOffset) |
Select between two points. |
Range members
| Name | Description |
|---|---|
setStart(node, offset) / setEnd(node, offset) |
Set the boundaries. For text nodes the offset counts characters; for elements it counts child nodes. |
selectNode(node) / selectNodeContents(node) |
Cover the node itself, or only its content. |
collapse(toStart) |
Make the range a single point. |
cloneContents(), extractContents(), deleteContents() |
Copy, move or delete the covered content. |
surroundContents(node) |
Wrap the range in a node (fails if the range partially covers a non-text node). |
insertNode(node) |
Insert a node at the start of the range. |
getBoundingClientRect() / getClientRects() |
Measure the range on screen. |
toString() |
The text in the range. |
Return value
getSelection() returns a Selection (or null in rare cases, such as a hidden iframe in some browsers); createRange() returns an empty Range positioned at the start of the document.
Usage notes
- Offsets are positions between nodes or characters. In a text node, offset 3 sits between the third and fourth characters. In an element, offset 2 sits before its third child.
surroundContents()can throwInvalidStateErrorwhen the range splits a non-text node. UseextractContents()andinsertNode()yourself for complex cases.- Inputs are different.
window.getSelection().toString()may be empty for text inside<input>and<textarea>in some browsers. Useinput.selectionStart,input.selectionEndandinput.value.slice(start, end), orinput.setSelectionRange(start, end). - Clicking a button clears the selection in many browsers, because it takes focus. The first example stops that by canceling
mousedown. - Listen with
selectionchange. It fires ondocumentwhenever the selection changes. It does not bubble from elements; attach it todocument. - Live ranges. A range updates when the DOM changes; deleting its boundary nodes collapses it.
- Highlights without changing the DOM. The CSS Custom Highlight API can paint ranges using
::highlight()styles, avoiding wrapper elements. - Copying. Reading selected text is allowed; writing to the clipboard needs a user gesture and the Clipboard API, which may be unavailable in sandboxed frames.
Browser support
Selection and Range are supported in all current browsers, with small differences in edge cases (multiple ranges, selection inside form controls, shadow DOM). The CSS Custom Highlight API is newer, so check a compatibility table.