The Screen Orientation API provides web applications with the ability to read the current screen orientation state and lock the screen to a specific orientation. It is accessed via screen.orientation. The API exposes type (e.g., portrait-primary, landscape-primary) and angle (0°, 90°, 180°, 270°) properties, along with lock() and unlock() methods. This is especially useful for games, video players, and full-screen web apps that need to control display orientation.

On desktop browsers (Chrome, Edge, etc.), the screen.orientation.lock() method typically requires the document to be in fullscreen mode. If you attempt to lock orientation without fullscreen, you'll get a DOMException with a message like "lock() requires a fullscreen document". The solution is to first call document.documentElement.requestFullscreen(), then lock the orientation. This tool automatically attempts fullscreen when needed. On mobile devices, fullscreen is usually not required for orientation lock.

• portrait-primary — Device is upright, in its "natural" portrait position (angle: 0°). This is how most phones are held.
• portrait-secondary — Device is upside down relative to its natural portrait position (angle: 180°).
• landscape-primary — Device is rotated 90° clockwise from natural portrait (angle: 90° on most devices). The top of the device points left.
• landscape-secondary — Device is rotated 270° clockwise (or 90° counter-clockwise) from natural portrait (angle: 270°). The top points right.

Note: The "primary" landscape direction may be 90° or 270° depending on the device manufacturer's convention. Most smartphones use 90° for landscape-primary.

Widely supported on modern browsers: Chrome 38+, Firefox 43+, Edge 79+, Opera 25+, Samsung Internet 5.0+. Partial support in Safari: iOS Safari 13+ supports reading orientation but lock() is limited — it typically works only in standalone PWA mode (Add to Home Screen) or when using webkit prefixes in some versions. Desktop Safari has limited support. Always check 'orientation' in screen before using the API. This tool automatically detects API availability and adjusts accordingly.

Use the change event on screen.orientation:

screen.orientation.addEventListener('change', () => {
  console.log('Orientation:', screen.orientation.type);
  console.log('Angle:', screen.orientation.angle);
});

Alternatively, you can use the onchange property: screen.orientation.onchange = () => { ... }. The legacy window.orientationchange event is deprecated and should not be used in new projects.

Orientation lock inside iframes has additional restrictions. The iframe must have the allow="fullscreen" attribute for fullscreen requests, and allow="screen-orientation-lock" (or the legacy allow="orientation-lock") for orientation locking. Even with these permissions, some browsers may block orientation lock in cross-origin iframes. If you're embedding this tool, ensure the host page includes these permissions. The Permissions Policy header can also affect this: Permissions-Policy: screen-orientation-lock=(self).

lock('any') allows the screen to freely rotate to any orientation (portrait or landscape, primary or secondary) while technically keeping a "lock" active — it effectively removes restrictions but maintains the lock state. unlock() completely releases the lock, returning orientation control to the system default behavior. In practice, both result in free rotation, but lock('any') keeps the lock promise resolved, while unlock() fully releases it. Use unlock() when you're done controlling orientation.

• "lock() requires a fullscreen document" — Enter fullscreen mode first using document.documentElement.requestFullscreen(). Desktop browsers enforce this.
• "lock() requires a user gesture" — The lock must be initiated by a user action (click, tap, keypress). It cannot be called automatically on page load.
• "NotSupportedError" — The requested orientation (e.g., portrait-secondary) is not supported by the device or browser. Fall back to portrait or landscape.
• "AbortError" — Another lock request is already pending. Wait for the previous promise to resolve before calling lock again.
• API not available — Check 'orientation' in screen. If false, the browser doesn't support this API. Consider using a polyfill or accepting the limitation.