JavaScript Screen orientation Property

What You’ll Learn

Screen.orientation is a read-only instance property that returns a ScreenOrientation object for the current screen orientation. Learn type and angle, the MDN landscape/portrait switch, how to listen for rotation with change, and how this differs from older APIs—with five examples and try-it labs.

Introduction

Phones and tablets rotate. Games and video UIs often want to know whether the screen is in portrait or landscape—and which way is “up.” The Screen Orientation API exposes that through window.screen.orientation.

The property itself is an object (ScreenOrientation), not a plain string. Beginners usually start with screen.orientation.type, which returns values like "landscape-primary" or "portrait-primary".

console.log(window.screen.orientation);
console.log(screen.orientation.type);

Understanding the Property

MDN: the orientation read-only property of the Screen interface returns the current orientation of the screen as a ScreenOrientation instance.

• Instance — on window.screen.
• Read-only property — you do not assign a new orientation object to it.
• Object value — use .type, .angle, and events.
• Baseline — Widely available (MDN: since March 2023).

📝 Syntax

const orient = window.screen.orientation;
// same as:
const orient2 = screen.orientation;

console.log(orient.type);
console.log(orient.angle);

Value

An instance of ScreenOrientation representing the orientation of the screen.

🎨 Common type Values

angle is a number of degrees of rotation (commonly 0, 90, 180, or 270, depending on the device).

🎯 MDN Landscape / Portrait Switch

MDN’s classic teaching example branches on screen.orientation.type:

switch (screen.orientation.type) {
  case "landscape-primary":
    console.log("That looks good.");
    break;
  case "landscape-secondary":
    console.log("Mmm… the screen is upside down!");
    break;
  case "portrait-secondary":
  case "portrait-primary":
    console.log("Mmm… you should rotate your device to landscape");
    break;
  default:
    console.log("The orientation API isn't supported in this browser :(");
}

🔄 Listening for Orientation Changes

When the user rotates the device, ScreenOrientation fires a change event. Re-read type / angle inside the handler.

if (screen.orientation) {
  screen.orientation.addEventListener("change", () => {
    console.log("now:", screen.orientation.type, screen.orientation.angle);
  });
}

Examples Gallery

Examples follow MDN Screen.orientation. Rotate a phone or resize a desktop window (when the browser reports a type) to see values change.

if (screen.orientation) {
  console.log(screen.orientation.type);
  console.log(typeof screen.orientation.type);
} else {
  console.log("screen.orientation not available");
}

landscape-primary
string

if (!screen.orientation) {
  console.log("The orientation API isn't supported in this browser :(");
} else {
  switch (screen.orientation.type) {
    case "landscape-primary":
      console.log("That looks good.");
      break;
    case "landscape-secondary":
      console.log("Mmm… the screen is upside down!");
      break;
    case "portrait-secondary":
    case "portrait-primary":
      console.log("Mmm… you should rotate your device to landscape");
      break;
    default:
      console.log("The orientation API isn't supported in this browser :(");
  }
}

That looks good.

if (!screen.orientation) {
  console.log("unsupported");
} else {
  console.log({
    type: screen.orientation.type,
    angle: screen.orientation.angle
  });
}

{
  "type": "landscape-primary",
  "angle": 0
}

function report() {
  if (!screen.orientation) {
    return "unsupported";
  }
  return screen.orientation.type + " @ " + screen.orientation.angle + "°";
}

console.log("now:", report());

if (screen.orientation) {
  screen.orientation.addEventListener("change", () => {
    console.log("changed:", report());
  });
}

now: landscape-primary @ 0°

console.log({
  type: screen.orientation ? screen.orientation.type : "(unavailable)",
  angle: screen.orientation ? screen.orientation.angle : null,
  width: screen.width,
  height: screen.height,
  availWidth: screen.availWidth,
  availHeight: screen.availHeight
});

{
  "type": "landscape-primary",
  "angle": 0,
  "width": 1920,
  "height": 1080,
  "availWidth": 1920,
  "availHeight": 1040
}

🚀 Common Use Cases

• Prompt users to rotate to landscape for video or games.
• Adjust layout hints when type is portrait vs landscape.
• Log orientation in mobile QA and device diagnostics.
• Listen for change to refresh UI after a rotate.
• Teaching ScreenOrientation as the modern alternative to old window.orientation.

🔧 How It Works

📝 Notes

• Baseline Widely available (MDN, since March 2023).
• Not Deprecated, Experimental, or Non-standard — no status banner required.
• Property is read-only; value is a ScreenOrientation object.
• Prefer screen.orientation over legacy window.orientation.
• Related: mozEnabled, height, Window hub, JavaScript hub.

💡 Best Practices