JavaScript Screen change Event

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

Definition

The change event on a Screen fires when one or more of these properties change on that screen (MDN): width, height, availWidth, availHeight, colorDepth, or orientation.

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

Syntax

Listen for change. Start with this line.

JavaScript
screen.addEventListener("change", handler)
CallWhat it does
screen.addEventListener("change", handler)Primary signature.

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

Library declarations
JavaScript
screen.addEventListener("change", handler)

Parameters

ParameterDescription
TargetRequired. A Screen (often from getScreenDetails)
Secure contextRequired. HTTPS / localhost

Return Value

Return ValueDescription
*Fires as a Screen event (listener receives the event).

JavaScript Examples

Example 1 — Feature Detect

Check Window Management entry points before showing multi-screen UI.

JavaScript
const hasApi = typeof window.getScreenDetails === "function";
const secure = window.isSecureContext;

console.log(hasApi);
console.log(secure);

if (!hasApi || !secure) {
  console.log("Screen change API unavailable here");
}
Try It Yourself

How It Works

  1. Check getScreenDetails. MDN examples start from this method.
  2. Check secure context. Window Management needs HTTPS / localhost.
  3. Gate the feature. Hide multi-screen listeners when either check fails.
  4. Limited availability. Detection is required — not Baseline.

Example 2 — Listen (MDN Pattern)

Request screen details, then attach change on the first screen.

JavaScript
async function watchFirstScreen() {
  if (typeof window.getScreenDetails !== "function") {
    console.log("unavailable");
    return;
  }
  try {
    const details = await window.getScreenDetails();
    const first = details.screens[0];
    first.addEventListener("change", (event) => {
      console.log("screen changed", event.type, first.width);
    });
    console.log("listening");
  } catch (err) {
    console.log(err.name);
  }
}

watchFirstScreen();
Try It Yourself

How It Works

  1. Detect. Exit early if the method is missing.
  2. Await details. May prompt for window-management permission.
  3. Pick a screen. MDN uses screens[0] as the first display.
  4. Subscribe. change fires later when that screen’s metrics update.

Example 3 — Re-read Properties in the Handler

The event is generic — read the Screen object for current values.

JavaScript
function onScreenChange(screenObj) {
  console.log(screenObj.width + "x" + screenObj.height);
  console.log(screenObj.availWidth + "x" + screenObj.availHeight);
  console.log(screenObj.colorDepth);
  if (screenObj.orientation) {
    console.log(screenObj.orientation.type);
  }
}

// After getScreenDetails():
// first.addEventListener("change", () => onScreenChange(first));
Try It Yourself

How It Works

  1. Generic Event. No payload fields for the new size (MDN).
  2. Re-read the Screen. Width, height, avail*, colorDepth, orientation.
  3. Orientation object. Use orientation.type when present.
  4. Wire after listen. Call this helper from your change listener.
Compatibility

Browser Support

Screen change is part of the Window Management API. MDN marks it Experimental and Limited availability (not Baseline). Requires a secure context.

✓ Experimental · Limited

Screen: change

Best support in Chromium-based browsers with Window Management permission. Missing in Firefox and Safari — always feature-detect.

Limited Not Baseline
Google Chrome Window Management (secure)
Yes
Microsoft Edge Window Management (secure)
Yes
Opera Chromium-based (check version)
Partial
Mozilla Firefox Not supported
No
Apple Safari Not supported
No
Internet Explorer Not supported
No
Screen change Feature-detect required

Bottom line: Treat as progressive enhancement. See the MDN Screen change event reference.

Frequently Asked Questions

It is an experimental Window Management API event fired on a specific Screen when one or more of width, height, availWidth, availHeight, colorDepth, or orientation change on that screen (MDN).
MDN marks Screen: change as Experimental and Limited availability (not Baseline). It is not Deprecated or Non-standard. It requires a secure context (HTTPS) in supporting browsers.
Use addEventListener("change", handler) or the onchange property on a Screen object—typically one from (await window.getScreenDetails()).screens.
A generic Event. Re-read the Screen properties you care about inside the handler; the event object has no special payload for the new values.
No. Screen orientationchange is a different (legacy) event. ScreenOrientation also has its own change event. Screen change is broader and part of Window Management.
The API needs permission and may be blocked by Permissions-Policy window-management. The Promise can reject with NotAllowedError. Always feature-detect and catch errors.

Next: orientationchange

Learn the Screen orientationchange event and how it differs from change.

orientationchange 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)

11 people found this page helpful

JavaScript Screen unlockOrientation() Method JavaScript Screen orientationchange Event