JavaScript Screen change Event

What You’ll Learn

The change event of the Screen interface fires on a specific screen when key geometry or display facts update. Learn which properties trigger it, how MDN listens via getScreenDetails(), how onchange compares to addEventListener, and how it differs from screen.orientation change—with five examples and try-it labs.

Introduction

Multi-monitor apps sometimes need to know when a display’s size, available area, color depth, or orientation changes—for example after docking a laptop or rotating a tablet used as a second screen.

The Window Management API exposes a change event on Screen objects for that. MDN’s examples usually get screens from window.getScreenDetails(), then listen on a specific screen in screens.

// Idea only — needs permission / supporting browser
// const details = await window.getScreenDetails();
// details.screens[0].addEventListener("change", () => { /* … */ });

Understanding the Event

MDN: the change event of the Screen interface is fired on a specific screen when one or more of the following properties change on it:

• width
• height
• availWidth
• availHeight
• colorDepth
• orientation

The event is a generic Event. Inside the handler, re-read the screen object (for example firstScreen.width) to see the updated values.

📝 Syntax

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

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

onchange = (event) => { };

Event type

A generic Event.

Parameters

The handler receives a normal Event. There is no dedicated “ScreenChangeEvent” with size fields—read properties on the Screen you subscribed to.

⚖️ Screen change vs orientation change

💻 Listening with getScreenDetails()

MDN’s example awaits window.getScreenDetails(), then attaches change to screens[0]. That call is permission-gated and may reject. Pair it with screen.isExtended when deciding whether a multi-screen UI is worth trying.

const firstScreen = (await window.getScreenDetails()).screens[0];
firstScreen.addEventListener("change", (event) => {
  console.log("The first screen has changed.", event, firstScreen);
});

Examples Gallery

Examples follow MDN Screen: change event. Labs mostly feature-detect and explain availability—firing a real change often needs a supporting browser, permission, and a physical display change.

console.log({
  isSecureContext,
  hasGetScreenDetails: typeof window.getScreenDetails === "function",
  hasOnchangeProp: "onchange" in screen,
  tip: "Screen change is experimental Window Management — feature-detect first."
});

{
  "isSecureContext": true,
  "hasGetScreenDetails": true,
  "hasOnchangeProp": true,
  "tip": "Screen change is experimental Window Management — feature-detect first."
}

async function listenFirstScreenChange() {
  if (typeof window.getScreenDetails !== "function") {
    console.log("getScreenDetails not supported");
    return;
  }
  try {
    const firstScreen = (await window.getScreenDetails()).screens[0];
    firstScreen.addEventListener("change", (event) => {
      console.log("The first screen has changed.", event, firstScreen);
    });
    console.log("Listening for change on screens[0]");
  } catch (err) {
    console.log("getScreenDetails failed:", err.name);
  }
}

listenFirstScreenChange();

getScreenDetails not supported
// or: getScreenDetails failed: NotAllowedError
// or: Listening for change on screens[0]

async function attachOnchange() {
  if (typeof window.getScreenDetails !== "function") {
    console.log("Cannot attach onchange — getScreenDetails missing");
    return;
  }
  try {
    const firstScreen = (await window.getScreenDetails()).screens[0];
    firstScreen.onchange = (event) => {
      console.log("onchange fired", event.type);
    };
    console.log("Attached firstScreen.onchange");
  } catch (err) {
    console.log("attach failed:", err.name);
  }
}

attachOnchange();

Cannot attach onchange — getScreenDetails missing

// Properties MDN lists as change triggers — read them after a change fires
console.log({
  width: screen.width,
  height: screen.height,
  availWidth: screen.availWidth,
  availHeight: screen.availHeight,
  colorDepth: screen.colorDepth,
  orientationType: screen.orientation ? screen.orientation.type : "(none)",
  note: "Re-read these inside a Screen change handler"
});

{
  "width": 1920,
  "height": 1080,
  "availWidth": 1920,
  "availHeight": 1040,
  "colorDepth": 24,
  "orientationType": "landscape-primary",
  "note": "Re-read these inside a Screen change handler"
}

if (screen.orientation && typeof screen.orientation.addEventListener === "function") {
  screen.orientation.addEventListener("change", () => {
    console.log("orientation change:", screen.orientation.type, screen.orientation.angle);
  });
  console.log("Listening on screen.orientation (not Screen change)");
} else {
  console.log("ScreenOrientation change not available");
}

Listening on screen.orientation (not Screen change)

🚀 Common Use Cases

• Re-layout multi-window UIs after a monitor is docked or undocked.
• Refresh cached screen width/height for Window Management apps.
• React when available work area changes (taskbar / dock).
• Teaching the difference between Screen and ScreenOrientation events.
• Pairing with isExtended before multi-screen flows.

🔧 How It Works

📝 Notes

• Experimental and Limited availability (MDN)—experimental banner shown above.
• Not Deprecated or Non-standard on MDN.
• Secure context required in supporting browsers.
• Different from screen.orientation change.
• Related: orientationchange, isExtended, orientation, unlockOrientation(), Window hub.

💡 Best Practices