Introducing the Screen Orientation API

Everyone uses the web in a different way. There are people who use it to chat, others use it to watch movies, and others use it to play games. For those of you who access the internet to play games on their mobile device, I have a question: have you ever played a game that asks you to rotate the screen to start? I bet the answer is yes.

The reason you have to rotate the screen is that the UI has been developed for a specific mode, portrait or landscape. If your web application has the same need, or you are developing one of these games, I have a JavaScript API for you: the Screen Orientation API. In this article I’ll discuss what it is and what it is good for.

What is the Screen Orientation API?

The Screen Orientation APIprovides the ability to read the screen orientation state, to be informed when this state changes, and to be able to lock the screen orientation to a specific state. In other words, you are now able to detect the orientation of a user’s device (in terms of portrait and landscape) and lock in the mode you need. Doing so, you don’t need to show your users weird animations and labels to specify the orientation needed. In fact, you can now set the device’s screen in the orientation needed so that the user will understand how to rotate the device.

--ADVERTISEMENT--

The Screen Orientation API is at a very early stage, as it’s a W3C Working Draft. The current specifications may be superseded in a few months by a newer version that is currently in progress. The new version is slightly different from the old one because it introduces a new property and a different return type for one of the methods.

It’s also worth noting that to lock the screen, the web page must be in full-screen mode (you can achieve this using the Fullscreen API).

Now that you know what the Screen Orientation API is, let’s discover more about its properties and methods.

Properties and Events

The Screen Orientation API extends the screen object of window with a property, orientation, and two methods, lockOrientation() and unlockOrientation().

The orientation property returns a string representing the orientation of the screen. Its value can be one of the followings:

portrait-primary: The orientation is in the primary portrait mode. For a smartphone this values means that it’s in a vertical position with the buttons at the bottom.

portrait-secondary: The orientation is in the secondary portrait mode. For a smartphone this value means that it’s in a vertical position with the buttons at the top (the device is down under)

landscape-primary: The orientation is in the primary landscape mode. For a smartphone this value means that it’s in a horizontal position with the buttons at the right.

landscape-secondary: The orientation is in the secondary landscape mode. For a smartphone this value means that it’s in a horizontal position with the buttons at the left.

The lockOrientation() and unlockOrientation() methods are complementary in what they do. The first method locks the device’s screen as if the device was physically rotated in a certain position, as shown in the figure below. It returns a Boolean which is true in case of success of the operation and false otherwise.

The Screen Orientation API in action. The device is physically in portrait mode but the screen acts as if it was in landscape.

lockOrientation() accepts one or more strings to specify the orientations we want to lock the screen at. The strings must be one of the previously mentioned values of the orientation property, portrait to specify the orientation can be either portrait-primary and portrait-secondary, or landscape to indicate the orientation can be either landscape-primary and landscape-secondary.

An example of code that uses this method and passes one string is shown below:

The unlockOrientation() method is used to release a previously set lock and allows the screen to rotate again in every position.

The API also provides an event named onorientationchange that is fired every time the screen orientation changes. We can use this event to detect changes of the orientation and update the UI or the business logic of our website accordingly.

Browser Compatibility

The support for the Screen Orientation API is very good, although some browsers still use the prefixed version. The API is supported by Firefox 18+ using its vendor prefix (moz), Internet Explorer 11+ using its vendor prefix (ms), Chrome 38+ (currently in beta), and Opera 25+ (currently in beta). Unfortunately, just like many other really interesting and useful APIs, Safari doesn’t have any support.

As you can see, with the next release of Chrome and Opera, you’ll have almost every major browser supporting this API. So, you can really use it in your next project. Even without support, we’ve learned to develop our projects based on feature detection. To test if the API is implemented your browser, you can write:

So far, we’ve covered the properties and the events exposed by the API as well as the API’s use cases. In the next section, we’re going to create a simple web page to see the Screen Orientation API in action.

Demo

The demo we’re going to develop consists of an HTML page that displays text indicating the current orientation of the screen. Then, we have a select box to specify the orientation we want to lock the screen at. Finally, we have two buttons: one to lock the screen and the other to unlock it.

Inside the JavaScript code we detect if the browser supports this API or not, and what prefix it uses, if any. If the API isn’t implemented in the browser we display the message “API not supported” and the buttons will be disabled. If the API is supported we attach a handler to the correct event (the name varies because of the prefixes) where we update the text of the paragraph to show the current orientation.

Finally, we create other two handlers. In the first we set the page in full-screen mode and lock the screen in the orientation specified by the select box. In the second we remove the lock and exit full-screen mode.

Important note: While developing and testing this demo I’ve found a couple of bugs in Firefox. The browser crashes with any value passed to lockOrientation() (actually mozLockOrientation()) but portrait-primary and portrait-secondary. In addition, when portrait-secondary is given, Firefox acts as if the string was landscape-primary. Based on my tweets, two bugs have been filed (https://bugzil.la/1061372 and https://bugzil.la/1061373) and hopefully they will be fixed soon.

You can find the complete code for the demo below. You can also play with it online if you like.

Conclusion

In this article we’ve discussed the Screen Orientation API. This API exposes one property that specifies the orientation of the screen and two methods. The first method allows you to lock the screen in a given orientation, while the second releases the lock. Finally, it provides an event to know when a change of orientation happens.

As you’ve seen, using this API is quite simple and it should not be too difficult for you to employ it in a future project. Finally, the support among browsers is very good, so this is really something you can plan to adopt.

I'm a (full-stack) web and app developer with more than 5 years' experience programming for the web using HTML, CSS, Sass, JavaScript, and PHP. I'm an expert of JavaScript and HTML5 APIs but my interests include web security, accessibility, performance, and SEO. I'm also a regular writer for several networks, speaker, and author of the books jQuery in Action, third edition and Instant jQuery Selectors.