JavaScript Screen Orientation API

The Screen Orientation API lets a web page read the device's current orientation, react when it changes, and — on supporting devices — lock the screen to a specific orientation. It is useful for games, video players, camera apps, and anything where layout depends on whether the device is held in portrait or landscape.

This page covers the four things you need to know to use it:

• Reading the current orientation with screen.orientation (its type and angle).
• Reacting to rotation with the change event.
• Forcing an orientation with lock() and releasing it with unlock().
• The requirements and limits: a secure context, fullscreen for locking, and graceful fallbacks.

The API is exposed through screen.orientation, a ScreenOrientation object available on the global screen object. It works only in a secure context (HTTPS or localhost).

CSS alternative: If you only need to adjust layout on rotation, you usually do not need JavaScript at all — use CSS media queries @media (orientation: portrait) and @media (orientation: landscape). Reach for this API when you need the orientation value in script, want to run code on rotation, or need to lock the screen.

Reading the Current Orientation

screen.orientation has two read-only properties:

• type — a string describing the orientation: "portrait-primary", "portrait-secondary", "landscape-primary", or "landscape-secondary".
• angle — the rotation in degrees relative to the device's natural orientation: 0, 90, 180, or 270.

Checking Current Orientation

To read the current orientation, access these properties directly:

<script>
    // Read the current screen orientation
    function displayOrientation() {
        if (screen.orientation) {
            alert('Type: ' + screen.orientation.type +
                  '\nAngle: ' + screen.orientation.angle + '°');
        } else {
            alert('Screen Orientation API is not supported.');
        }
    }
    document.getElementById('check-btn').addEventListener('click', displayOrientation);
</script>

<div>
    <button id="check-btn">Check Orientation</button>
</div>

On a phone held upright you would typically see portrait-primary with an angle of 0; turned a quarter turn it becomes landscape-primary at 90. Most desktop monitors report landscape-primary and never change.

Reacting to Orientation Changes

The screen.orientation object fires a change event whenever the orientation switches. Listen for it to re-run layout logic, repaint a <canvas>, pause a game, or recompute sizes. The event itself carries no extra data — read the new state from screen.orientation inside the handler.

<script>
    var output = document.getElementById('orientation-status');

    function showOrientation() {
        output.textContent =
            screen.orientation.type + ' (' + screen.orientation.angle + '°)';
    }

    // Update on load and whenever the device rotates
    showOrientation();
    screen.orientation.addEventListener('change', showOrientation);
</script>

<div>
    <p>Current orientation: <strong id="orientation-status">…</strong></p>
</div>

The change event is the modern replacement for the old window.onorientationchange event and the deprecated window.orientation number — prefer screen.orientation in new code.

Locking the Screen Orientation

screen.orientation.lock() forces the screen into a chosen orientation. It is the right tool for a fullscreen game that only works in landscape, or a video player that should not flip while playing.

Two requirements are important:

1. The document must be in fullscreen. Locking only works after a successful Fullscreen API request. Calling lock() outside fullscreen rejects with a NotSupportedError (or similar) on most browsers.
2. lock() returns a Promise. It resolves when the lock is applied and rejects if the orientation is unsupported, the platform forbids it (most desktops), or the document is not fullscreen. Always handle the rejection.

<script>
    var app = document.getElementById('app');

    async function lockLandscape() {
        try {
            // 1. Enter fullscreen first — locking requires it.
            await app.requestFullscreen();
            // 2. Then lock to landscape.
            await screen.orientation.lock('landscape-primary');
            console.log('Orientation locked to landscape.');
        } catch (error) {
            console.error('Lock failed:', error.message);
        }
    }

    document.getElementById('lock-btn').addEventListener('click', lockLandscape);
</script>

<div id="app">
    <button id="lock-btn">Go Fullscreen &amp; Lock to Landscape</button>
</div>

The orientation string passed to lock() can be a single value ("portrait", "landscape", "portrait-primary", …) or, in some browsers, an array of acceptable values. Locking must be triggered by a user gesture, such as the button click above.

Where it works: Locking is mainly supported on mobile platforms (notably Chrome/Android). Most desktop browsers expose screen.orientation for reading but reject lock() — always assume it may fail and design a layout that works in any orientation.

Unlocking the Screen Orientation

screen.orientation.unlock() releases a lock you set earlier, letting the screen follow the device again. It is synchronous and returns nothing. Exiting fullscreen also clears any active lock automatically.

<script>
    function unlockOrientation() {
        if (screen.orientation && screen.orientation.unlock) {
            screen.orientation.unlock();
            console.log('Orientation unlocked.');
        }
    }
    document.getElementById('unlock-btn').addEventListener('click', unlockOrientation);
</script>

<div>
    <button id="unlock-btn">Unlock Orientation</button>
</div>

Best Practices

• Treat locking as best-effort. It fails on most desktops and can be disabled in browser settings, so never depend on it for core functionality — pair it with a layout that survives any orientation.
• Always catch the Promise. A rejected lock() that you ignore becomes an unhandled rejection in the console.
• Enter fullscreen first. A lock without an active fullscreen request will reject.
• Prefer CSS for layout. Use @media (orientation: …) for styling and reserve this API for behavior that genuinely needs the orientation value in JavaScript.
• Feature-detect. Check if (screen.orientation) and if (screen.orientation.lock) before calling, and remember the API needs a secure context (HTTPS or localhost).

Related Topics

• JavaScript Fullscreen API — required before locking the orientation.
• JavaScript Window Sizes and Scrolling — read viewport dimensions that change on rotation.

Practice