JavaScript Document selectionchange Event

Beginner
5 min read
Updated: Nov 2026
3 examples
Event
Decorative image with the word SELECTIONCHANGE

Definition

In JavaScript, the browser fires the selectionchange event of the Selection API when the current Selection of a Document changes (MDN). A document selection is either a range of selected content or a collapsed caret.

Register a listener with addEventListener. Check readiness and browser support before you rely on this event.

Syntax

Listen for selectionchange. Start with this line.

JavaScript
addEventListener("selectionchange", …)
CallWhat it does
addEventListener("selectionchange", …)Primary signature.

Built into the browser. Listen with document.addEventListener("selectionchange", …) — no import required.

Library declarations
JavaScript
addEventListener("selectionchange", …)

Parameters

ParameterDescription
ListenerRequired. addEventListener or onselectionchange
getSelection()Required. Current Selection object
Event objectOptional. Generic Event — no selection fields

Return Value

Return ValueDescription
*Fires as a Document event (listener receives the Event object).

JavaScript Examples

Example 1 — Listen and Read getSelection()

MDN pattern: log the Selection whenever the document selection changes.

JavaScript
document.addEventListener("selectionchange", () => {
  const sel = document.getSelection();
  console.log(sel ? sel.toString() : "(no Selection)");
});
Try It Yourself

How It Works

  1. Listen on document. The event does not bubble, so the target must be document.
  2. Read inside the handler. The Event has no selection payload (MDN).
  3. Call getSelection(). Returns the live Selection object.
  4. Convert to text. toString() gives the highlighted string (empty for a caret).

Example 2 — onselectionchange Property

Same event via the handler property (MDN also documents this form).

JavaScript
document.onselectionchange = () => {
  const sel = document.getSelection();
  const text = sel ? sel.toString() : "";
  console.log(text ? "Selected: " + text : "No text selected");
};
Try It Yourself

How It Works

  1. Assign the property. onselectionchange is the one-handler form.
  2. Prefer addEventListener when you need multiple listeners.
  3. Still call getSelection(). The property does not change how you read state.
  4. Empty string. Means caret-only or cleared selection, not an error.

Example 3 — Collapsed Caret vs Range

Use isCollapsed to tell a caret from a real highlight.

JavaScript
document.addEventListener("selectionchange", () => {
  const sel = document.getSelection();
  if (!sel) return;

  console.log("isCollapsed:", sel.isCollapsed);
  console.log("rangeCount:", sel.rangeCount);
  console.log("length:", sel.toString().length);
});
Try It Yourself

How It Works

  1. isCollapsed. true means start and end are the same (caret).
  2. rangeCount. Usually 1 when there is a selection object.
  3. length. Zero for a caret; non-zero when text is highlighted.
  4. UI tip. Show a quote/share toolbar only when !isCollapsed and length > 0.
Compatibility

Browser Support

Document selectionchange is part of the Selection API. MDN marks it Baseline Widely available since March 2017 — safe for everyday use in modern browsers.

✓ Baseline Widely available

Document selectionchange

Fires when the Document Selection changes — read state with document.getSelection().

Wide Baseline
Google Chrome Supported · Desktop & Mobile
Full support
Mozilla Firefox Supported · Desktop & Mobile
Full support
Apple Safari Supported · macOS & iOS
Full support
Microsoft Edge Supported · Chromium
Full support
Internet Explorer No native support · Use a polyfill
Polyfill
Opera Supported · Modern versions
Full support
Samsung Internet Supported · Android
Full support
Android WebView Supported · Modern WebView
Full support
selectionchange Widely available

Bottom line: Listen on document, then call getSelection() inside the handler. Do not confuse it with the bubbling selectionchange on input/textarea controls.

Frequently Asked Questions

The browser fires selectionchange when the current Selection of a Document changes — create/clear selection, move range boundaries, or collapse to a caret (MDN).
No. MDN marks Document selectionchange as Baseline Widely available (since March 2017). It is not Deprecated, Experimental, or Non-standard.
No. MDN: the Document selectionchange event is not cancelable and does not bubble. Listen on document.
Call document.getSelection() inside the listener. The Event object does not carry the updated selection details (MDN).
Document selection uses DOM ranges via getSelection(). Input/textarea selection uses selectionStart/selectionEnd; that event fires on the control and bubbles (MDN).
Programmatic Selection changes update immediately, but selectionchange is queued as a task and runs after the current script finishes (MDN).

Next: visibilitychange

Learn when the document becomes visible or hidden in a browser tab.

visibilitychange tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

AWS Certified Developer – Associate (Credly)

10 people found this page helpful

JavaScript Document securitypolicyviolation Event JavaScript Document visibilitychange Event