JavaScript Document selectionchange Event

What You’ll Learn

The Document selectionchange event fires when the document’s current Selection changes—selected text across DOM nodes, or a collapsed caret. Learn to listen on document, read document.getSelection(), and practice with five try-it labs.

Introduction

When you drag to highlight text on a page—or click so the caret moves—the browser updates the document Selection. Each time that happens, Document selectionchange fires.

The event object itself does not carry the new selection. Inside the handler, call document.getSelection() (or window.getSelection()) to read the current Selection object.

Understanding Document selectionchange

A standard Document event that answers: “Did the page’s text selection (or caret) just change?”

• Fires when the current Selection of a Document changes (MDN).
• Includes creating/clearing a selection, moving range ends, replacing a range, or collapsing to a caret.
• Not cancelable and does not bubble — listen on document.
• Event type — a generic Event.
• Handler — document.onselectionchange or addEventListener("selectionchange", ...).
• Status — Baseline Widely available since March 2017 (MDN).

📝 Syntax

Use the event name with addEventListener, or set the handler property:

addEventListener("selectionchange", (event) => {});

onselectionchange = (event) => {};

Event type

A generic Event. Not cancelable and does not bubble.

MDN-style handlers

// addEventListener version
document.addEventListener("selectionchange", () => {
  console.log(document.getSelection());
});

// onselectionchange version
document.onselectionchange = () => {
  console.log(document.getSelection());
};

When it fires (MDN)

⚖️ Document vs input selectionchange

Examples Gallery

Examples follow MDN Document: selectionchange event. In try-it labs, select text on the page (not only inside an input) to fire the Document event, then inspect document.getSelection().

document.addEventListener("selectionchange", () => {
  console.log(document.getSelection());
});

Selection { … }  // or the selected string in some consoles

const out = document.getElementById("out");

document.onselectionchange = () => {
  const sel = document.getSelection();
  out.textContent = sel && sel.toString()
    ? "Selection active (" + sel.toString().length + " chars)"
    : "No text selected (caret or empty)";
};

Selection active (12 chars)

const out = document.getElementById("out");

document.addEventListener("selectionchange", () => {
  const text = String(document.getSelection() || "");
  out.textContent = text
    ? 'Selected: "' + text + '"'
    : "(nothing selected)";
});

Selected: "Hello world"

const out = document.getElementById("out");

document.addEventListener("selectionchange", () => {
  const sel = document.getSelection();
  if (!sel) {
    out.textContent = "No Selection object";
    return;
  }
  out.textContent =
    "isCollapsed: " + sel.isCollapsed +
    " | rangeCount: " + sel.rangeCount +
    " | text length: " + sel.toString().length;
});

isCollapsed: true | rangeCount: 1 | text length: 0
isCollapsed: false | rangeCount: 1 | text length: 18

const preview = document.getElementById("preview");

document.addEventListener("selectionchange", () => {
  const text = String(document.getSelection() || "").trim();
  preview.textContent = text
    ? "You selected: " + text
    : "Select any text on this page…";
});

You selected: Selection API

🚀 Common Use Cases

• Showing a floating toolbar when the user highlights text.
• Building “quote this” or share-selection features.
• Teaching how Document Selection differs from input caret APIs.
• Logging selection analytics (lightly—the event fires frequently).
• Syncing a live preview of the current highlight.

🔧 How It Works

📝 Notes

• Baseline Widely available (since March 2017)—no Deprecated / Experimental / Non-standard banner.
• Not cancelable and does not bubble—listen on document.
• Always call document.getSelection() inside the handler for the current Selection.
• Do not confuse with input/textarea selectionchange (different model; those bubble).
• Related learning: visibilitychange, securitypolicyviolation, JavaScript hub.

💡 Best Practices

❓ Frequently Asked Questions