Range module methods and properties

DOM Level 2 Traversal and Range modules define an interface called Range which is used to select a section of document structure regardless of node boundaries. This section can be used to read the document's content as well as to manipulate the DOM's structure. The DOM Range can thus be used to select specific parts of the document object; for instance:

<div id=”one”><ul><li>item1</li><li>item2</li></ul></div>

The bolded section in the above HTML code snippet can be a range. Once range is created and the positions are set, variety of manipulations are possible of the underlying DOM tree.

Creating a Range

createRange()

DOM Range object is created in a DOM-compliant browser using createRange() method of the document object. Thus created range is related to the current document object and cannot be used in other documents.

Syntax for createRange()

var curRange = document.createRange();

DOM Range selection

Following methods of the Range object provide a simple way to select a range.

selectNode(node)

The selectNode(node) method selects the entire node including its children of the given node.

selectNodeContents(node)

The selectNodeContents(node) method selects only the nodes children.

Example with Range selection methods

<!DOCTYPE html>
<html>

<style>
    p {
        color:#222; font-size:1.2em; font-family:Calibri; 
        background-color:lightblue; text-shadow:0px 1px 1px #eee; 
  }
</style>

<body><p id="message"><b>My message</b></p>
    <script>
    
        var r1 = document.createRange();
        var r2 = document.createRange();

        var elem = document.getElementById("message");

        // Range here is <p id="message"><b>My message</b></p>
        r1.selectNode(elem);  
                                 
        // Range here is < b>My message</b> 
        r2.selectNodeContents(elem);                               

        elem.innerHTML += "<br /><br />selectNode: " + r1;
    </script>
</body>

</html>

Properties of Range interface

startContainer

The startContainer property selects the node within which the Range begins. In the above example startContainer value for both selectNode() and selectNodeContents() methods are <body> and <p> tags respectively.

endContainer

The endContainer property selects node within which the Range ends. In the above example endContainer value for both selectNode() and selectNodeContents() methods are </body> and </p> tags respectively.

startOffset

The startOffset property selects the offset within the starting node of the Range. The offset is the index of the first child node in the Range.

endOffset

The endOffset property selects the offset within the ending node of the Range. When selectNode() is used to select a Range, endOffset is always startOffset+1, as there is only one node selected between the selected node tags. When selectNodeContents() is used, endOffset is startOffset + number of nodes till the ending node, as all the children are selected.

In the below example endOffset is 3 because it has three nodes inside the <p> tag.

<p id="message"><b>My message</b><br><b>Message content</b></p>

commonAncestorContainer

The deepest node in the document that has both startContainer and endContainer as descendants.

Example of selectNodeContents method

<!DOCTYPE html>
<html>

<style>
    p {
        color:#222; font-size:0.9em; font-family:Calibri; 
        background-color:#e0e0e0; text-shadow:0px 1px 1px #eee; 
    }
</style>

<body><p id="message"><b>My message</b><br><b>Message content</b></p>
    <script>
        var r1 = document.createRange();
        var elem = document.getElementById("message");

        r1.selectNodeContents(elem);
                              // Range : <b>My message</b><br><b>Message content</b>


        elem.innerHTML += "<br /><br />startContainer: " + r1.startContainer.tagName + "<br />";
        elem.innerHTML += "startOffset: " + r1.startOffset + "<br />";
        elem.innerHTML += "endOffset: " + r1.endOffset + "<br />";
        elem.innerHTML += "endContainer: " + r1.endContainer.tagName + "<br />";
        elem.innerHTML += "commonAncestorContainer: " + r1.commonAncestorContainer.tagName;
    </script>
</body>

</html>

Example of selectNode method

<!DOCTYPE html>
<html>

<style>
    p {
        color:#222; font-size:0.9em; font-family:Calibri; 
        background-color:#e0e0e0; text-shadow:0px 1px 1px #eee;
  }
</style>

<body><p id="message"><b>My message</b><br><b>Message content</b></p>
    <script>
        var r1 = document.createRange();
        var elem = document.getElementById("message");
        r1.selectNode(elem);
                // Range: <p id="message"><b>My message</b><br><b>Message content</b></p>

        elem.innerHTML += "<br /><br />startContainer: " + r1.startContainer.tagName + "<br />";
        elem.innerHTML += "startOffset: " + r1.startOffset + "<br />";
        elem.innerHTML += "endOffset: " + r1.endOffset + "<br />";
        elem.innerHTML += "endContainer: " + r1.endContainer.tagName + "<br />";
        elem.innerHTML += "commonAncestorContainer: " + r1.commonAncestorContainer.tagName;
    </script>
</body>
</html>

Other Methods for Range selection

setStartBefore(node)

The setStartBefore(node) method makes the Range starting from the node given. As the starting point of the range will be set just before the node given by this function.

setStartAfter(node)

The setStartAfter(node) method makes the Range starting after the given node. The starting point of the range will be set after the given node. Next sibling of the parent node will be the first node in the selection.

setEndBefore(node)

The setEndBefore(node) method sets the ending point of the Range before the given node, so that the range ends with previous sibling of the given node.

setEndAfter(node)

The setEndAfter(node) method makes the Range ending after the given node. The given node thus becomes the last node of the collection.

The example below shows an HTML Range with the nodes after selectNodeContents:

<b>One</b><div id="break"></div><b>Two</b><div id="testDiv"></div>

node 1: <b>One</b>

node 2: <div id="break"></div>

node 3: <b>Two</b>

node 4: <div id="testDiv"></div>

Example of Range interface startBefore() and startAfter() methods

<!DOCTYPE HTML>
<html>

<style>
    div {
        color:#222; font-size:0.9em; font-family:Calibri; 
        background-color:#e0e0e0; text-shadow:0px 1px 1px #eee; 
  }
</style>

<body>
    <div id="message"><b>One</b>
        <div id="break"></div><b>Two</b><div id="testDiv"></div>
    </div>
    <script>
        var r1 = document.createRange();
        var elem = document.getElementById("message");

        r1.selectNodeContents(elem);
 // Range: <b>One</b><br id="break"><b>Two</b><div id="testDiv"></div>

        var brk = document.getElementById("break");
        r1.setStartBefore(brk); 

        var end = document.getElementById("testDiv");
        r1.setEndAfter(end); 
  // Range: <br id="break"><b>Two</b><div id="testDiv"></div>
    
    </script>
</body>

</html>

setStart(startNode, startOffset)

The setStart(startNode, startOffset) method sets the start position of a Range specified by starting point through a start node and start offset from the start of start node.

startNode: where the range should start
startOffset: For Text, Comment, startOffset is the number if characters from the start of startNode and for HTML nodes, startOffset is number of child nodes after the start node.

setEnd(endNode, endOffset)

The setEnd(endNode, endOffset) method sets the end position of a Range specified by end node and end offset.

endNode: the node where Range should end
endOffset: the offset for the end of Range from the start of end node. For Text, Comments, endOffset is the number of characters from the start of endNode and for HTML nodes, it is the number of child nodes from the endNode.

In the following example we are trying to make part of the text displayed as bold.

Example of Range interface setStart() and setEnd() methods

<!DOCTYPE html>
<html>

<style>
    p {
        color:#222; font-size:0.9em; font-family:Calibri; 
        background-color:#e0e0e0; text-shadow:0px 1px 1px #eee; 
  }
</style>

<body>
    <div id="message">Hi Bweb<br />Good Day!</div>
    <p>HI JS Good was changed to bold</p>
    <script>
        var r1 = document.createRange();
        var elem = document.getElementById("message");

        r1.setStart(elem, 0);
        r1.setEnd(elem.childNodes[2], 4);
        var boldNode = document.createElement("b");

        r1.surroundContents(boldNode);

        // Now HI JS Good is bold

    </script>
</body>

</html>

Range.START_TO_START: Compares start boundary point of first range to start boundary point of second range
Range.END_TO_END: Compares end boundary-point of the first range with end boundary point of second range
Range.START_TO_END: Compares start boundary point of first range with end boundary point of second range
Range.END_TO_START: Compares the end boundary point of the first range with end boundary point of second range

Detach()

When done using a Range, the detach() method can be called on the range to safely cleanup after usage. Once detach is called the range can be no longer be approached and used.

›› go to examples ››