Skip to content
Tutorials Center
My learning

Topics

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().

JavaScript
const selection = window.getSelection();
console.log(selection.toString());

const range = document.createRange();
range.selectNodeContents(paragraph);

Try it

Read the user's selection
Create ranges from code

Syntax

JavaScript
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 throw InvalidStateError when the range splits a non-text node. Use extractContents() and insertNode() yourself for complex cases.
  • Inputs are different. window.getSelection().toString() may be empty for text inside <input> and <textarea> in some browsers. Use input.selectionStart, input.selectionEnd and input.value.slice(start, end), or input.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 on document whenever the selection changes. It does not bubble from elements; attach it to document.
  • 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.