DOM Range

DOM Range
Name	DOM Range
Developer	World Wide Web Consortium; implementations by Mozilla Foundation, Google, Apple Inc., Microsoft
Released	2004
Programming language	C++,[ [JavaScript
Platform	Web browser
License	Varies

DOM Range

DOM Range is a web API that represents a contiguous portion of a Document Object Model tree between two boundary points and provides methods to inspect, manipulate, and extract document fragments. It was specified through discussions and drafts in the context of web standards by the World Wide Web Consortium and implemented across engines maintained by organizations such as the Mozilla Foundation, Google, Apple Inc., and Microsoft. The API interacts with nodes, offsets, and selection primitives common to rich-text editing, accessibility tooling, and serialization workflows in browsers like Firefox, Chromium, and WebKit.

Overview

A Range object encapsulates a start and end boundary expressed as a pair of a reference to a Node and an integer offset, enabling operations on document subtrees, text nodes, and element children. Ranges are distinct from the Selection API used for user-driven highlights but are often combined with selections in editors such as TinyMCE and CKEditor and platforms like Gmail and Google Docs where programmatic content manipulation is required. Ranges allow creation of document fragments compatible with APIs used by HTML5 parsing, XML manipulation, and serialization libraries. Early motivations came from feature requests in browsers during the mid-2000s and associated specification work in bodies like the WHATWG and W3C.

API and Methods

Core instance methods include createRange-producing constructors in host environments and operations such as setStart, setEnd, setStartBefore, setEndAfter, cloneRange, detach, collapse, selectNode, selectNodeContents, and compareBoundaryPoints. Range methods that produce node collections or serialized output include cloneContents, extractContents, and insertNode, which interact with DocumentFragment and NodeList return types. Text-specific utilities include surroundContents and createContextualFragment for parsing HTML snippets within a Document context. There are also boundary-comparison helpers such as comparePoint and comparesBoundaryPoints to order ranges relative to nodes, inspired by algorithms used in text layout engines developed by teams at Mozilla Foundation and Apple Inc..

Use Cases and Examples

Common use cases include implementing rich-text editors in projects like CKEditor and ProseMirror, creating accessibility tools for screen readers like NVDA and VoiceOver that require precise text-region extraction, performing programmatic copy/cut/paste flows in webmail clients such as Outlook.com and Gmail, and producing diffs or highlights in collaborative platforms like Confluence and SharePoint. Developers use cloneContents to obtain a DocumentFragment for transient operations, extractContents to remove selected DOM ranges when implementing delete or cut semantics in editors such as Quill and Draft.js, and insertNode to inject elements during annotation workflows used by services like Hypothesis. Examples in code-oriented projects often pair Range with the Selection API to translate user caret positions into programmatic edits in environments like Stack Overflow's post editor or GitHub's comment boxes.

Events and Compatibility

Range operations themselves do not dispatch DOM events, but they are frequently used in implementations that trigger event sequences such as input, mutation, or custom events in applications built with React (web framework), Angular (application platform), and Vue.js. Because Range manipulations can produce mutations observable through the MutationObserver interface standardized by the W3C, developers must consider sequencing with event loops in environments like Node.js when using server-side DOM emulation libraries such as jsdom. Compatibility concerns historically arose from differences in boundary semantics and text node splitting behavior among engines in Gecko, Blink, and WebKit; these were addressed via conformance tests and updates to specifications maintained by WHATWG and W3C working groups.

Security and Performance Considerations

Using Range for DOM insertion or HTML parsing (e.g., createContextualFragment) requires the same sanitization discipline as innerHTML: untrusted content must be sanitized to mitigate Cross-site scripting risks exploited in attack vectors similar to those discussed in OWASP guidance. Performance considerations include avoiding excessive cloneContents on large subtrees to prevent memory pressure in browsers like Firefox or Chrome, and batching DOM updates in frameworks such as React (web framework) or Svelte to reduce reflow and repaint costs. Range operations that split text nodes or move large fragments interact with layout engines and compositor threads, where optimizations used by teams at Apple Inc. and Google can mitigate jank by deferring synchronous reflows.

Implementations and Browser Support

Range is implemented broadly across modern browsers and engines: Gecko (used by Firefox), Blink (used by Chrome and Chromium-based browsers such as Microsoft Edge), and WebKit (used by Safari). Polyfills and server-side implementations are available in projects like jsdom and adapter libraries used in frameworks including Ember.js and Backbone.js. Differences in older versions prompted interoperability work by the W3C and browser vendors to harmonize behaviors such as boundary normalization, node cloning, and text node splitting; current implementations report high conformance on test suites maintained by community projects and standards bodies.

Category:Web APIs