Please note, this is a STATIC archive of website developer.mozilla.org from 03 Nov 2016, cach3.com does not collect or store any user information, there is no "phishing" involved.

Managing screen orientation

This is an experimental technology
Because this technology's specification has not stabilized, check the compatibility table for usage in various browsers. Also note that the syntax and behavior of an experimental technology is subject to change in future versions of browsers as the specification changes.

Summary

Screen orientation is something slightly different than device orientation. Even if a device doesn't have the capacity to detect its own orientation, a screen always has one. And if a device is able to know its orientation, it's good to have the ability to control the screen orientation in order to preserve or adapt the interface of a web application.

There are several ways to handle screen orientation, both with CSS and JavaScript. The first is the orientation media query. This lets content adjust its layout using CSS, based on whether the browser window is in landscape mode (that is, its width is greater than its height) or portrait mode (its height is greater than its width).

The second way is the JavaScript Screen orientation API that can be used to get the current orientation of the screen itself and eventually lock it.

Adjusting layout based on the orientation

One of the most common cases for orientation changes is when you want to revise the layout of your content based on the orientation of the device. For example, perhaps you want a button bar to stretch along the longest dimension of the device's display. By using a media query, you can do this easily and automatically.

Let's have an example with the following HTML code

<ul id="toolbar">
  <li>A</li>
  <li>B</li>
  <li>C</li>
</ul>

<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Duis lacinia nisi nec sem viverra vitae fringilla nulla ultricies. In ac est dolor, quis tincidunt leo. Cras commodo quam non tortor consectetur eget rutrum dolor ultricies. Ut interdum tristique dapibus. Nullam quis malesuada est.</p>

CSS relies on the orientation media query to handle specific styles based on the screen orientation

/* First let's define some common styles */

html, body {
  width : 100%;
  height: 100%;
}

body {
  border: 1px solid black;

  -moz-box-sizing: border-box;
  box-sizing: border-box;
}

p {
  font   : 1em sans-serif;
  margin : 0;
  padding: .5em;
}

ul {
  list-style: none;

  font   : 1em monospace;
  margin : 0;
  padding: .5em;

  -moz-box-sizing: border-box;
  box-sizing: border-box;

  background: black;
}

li {
  display: inline-block;
  margin : 0;
  padding: 0.5em;
  background: white;
}

Once we have some common styles we can start defining a special case for the orientation

/* For portrait, we want the tool bar on top */

@media screen and (orientation: portrait) {
  #toolbar {
    width: 100%;
  }
}

/* For landscape, we want the tool bar stick on the left */

@media screen and (orientation: landscape) {
  #toolbar {
    position: fixed;
    width: 2.65em;
    height: 100%;
  }

  p {
    margin-left: 2em;
  }

  li + li {
    margin-top: .5em;
  }
}

And here's the result

Portrait Landscape

Note: The orientation media query actually applies based on the orientation of the browser window (or iframe) not the orientation of the device.

Locking the screen orientation

Warning: This API is experimental and currently available on Firefox OS and Firefox for Android with a moz prefix, and for Internet Explorer on Windows 8.1 and above  with a ms prefix.

Some devices (mainly mobile devices) can dynamically change the orientation of the screen based on their own orientation to make sure that the user will always be able to read what's on the screen. If this behavior is perfectly suited for text content, there is some content that can suffer such a change. For example, games based on the orientation of the device could be messed up by such a change of the orientation.

The Screen Orientation API is exactly made to prevent or handle such a change.

Listening orientation change

The orientationchange event is triggered each time the device change the orientation of the screen and the orientation itself can be read with the Screen.orientation property.

screen.addEventListener("orientationchange", function () {
  console.log("The orientation of the screen is: " + screen.orientation);
});

Preventing orientation change

Any web application can lock the screen to suits its own needs. The screen is locked using the Screen.lockOrientation() method and unlocked using the Screen.unlockOrientation().

The Screen.lockOrientation() accepts a string (or series of strings) to define the kind of lock to apply. Accepted values are: portrait-primary, portrait-secondary, landscape-primary, landscape-secondary, portrait, landscape (See Screen.lockOrientation  to know more about each of those values).

screen.lockOrientation('landscape');

Note: A screen lock is web application dependent. If application A is locked to landscape and application B is locked to portrait, switching from application A to B or B to A will not fire an orientationchange event because both applications will keep the orientation they had.

However, locking the orientation can fire an orientationchange event if the orientation had to be changed to satisfy the lock requirements.

Firefox OS and Android: Orientation lock using the manifest

For a Firefox OS and Firefox Android (soon to work on Firefox desktop too) specific way to lock orientation, you can set the orientation field in app's your manifest file, for example:

"orientation": "portrait"

See also

Document Tags and Contributors

 Contributors to this page: JohnRiv, AaronPope, chrisdavidmills, teoli, dstorey, Jeremie, williamr
 Last updated by: JohnRiv,