Skip to content

Manifest member in Manifest

orientation manifest member

Published Updated

Limited availabilityNot supported in Firefox (Desktop), Safari (macOS), Safari (iOS)W3C

The orientation manifest member asks the browser to lock an installed web app’s top-level windows to a default screen orientation, such as portrait or landscape, for as long as the app runs in an app-like display mode. It is a declarative counterpart to screen.orientation.lock(): the manifest sets the default orientation, which the browser restores whenever the orientation is unlocked or the window navigates, and the API changes it at runtime.

BCD (manifests.webapp.orientation) lists the member as supported from Chrome 39 on Android, Samsung Internet 4.0, Android WebView 39, and Firefox 79 for Android. Desktop Chrome 39 and Edge 79 are marked as supporting it too, but BCD does not separate parsing from locking a window, and screen.orientation.lock() itself always rejects on desktop Chromium. Desktop Firefox and Safari on iOS and macOS are marked as not supporting it. The specification leaves it to each browser which display modes can combine with an orientation, and names browser mode as one where a default orientation may make no sense, so expect the lock in fullscreen, standalone, and minimal-ui and not in a browser tab.

Property Value
Type string, one of the OrientationLockType values: any, natural, landscape, landscape-primary, landscape-secondary, portrait, portrait-primary, or portrait-secondary.
Default absent. MDN says the app then typically uses the device’s natural orientation and the user’s and system’s orientation settings.
Example value "portrait".

natural is the device’s own default (usually portrait on phones, usually landscape on tablets and computer monitors). portrait and landscape allow either of the two variants in that axis, so a phone that supports the secondary orientation stays readable when turned upside down; the -primary and -secondary forms pin a single one. any allows every orientation the operating system and the user’s settings permit. It is written when a manifest wants to say explicitly that it does not care, and omitting the member usually behaves much the same.

A value outside the list is dropped, not an error for the whole manifest: Chromium logs unknown 'orientation' value ignored. and continues as if the member were absent. The lock is a property of the app window, so it applies to every in-scope document the window shows and not to the same URLs opened in a browser tab.

Handle browsers that ignore the orientation lock with a layout that works in either orientation.

A data-entry app whose forms are laid out for a phone held upright locks to portrait. On Chrome for Android the installed app ignores the device rotating; in a browser tab and on iOS the same manifest has no effect and the layout must still work in landscape.

{
"name": "Field Journal",
"short_name": "Journal",
"start_url": "/",
"display": "standalone",
"orientation": "portrait"
}

Use portrait to let the screen flip 180 degrees on devices that support the secondary orientation when the user turns the phone around. portrait-primary blocks that rotation.

Reading the current orientation and reacting to changes

Section titled “Reading the current orientation and reacting to changes”

The manifest lock is invisible to script, but the orientation it produces is not. The Screen Orientation API reports it through screen.orientation.type and fires change on screen.orientation, including for a 180-degree turn. Browsers without the API (Safari on iOS before 16.4) take the fallback branch, where a media query reports only the axis, so a flip between the primary and secondary variants goes unnoticed.

function currentOrientation() {
if ('orientation' in screen && screen.orientation?.type) {
return screen.orientation.type; // e.g. "portrait-primary"
}
// Fallback: no Screen Orientation API; derive the axis from the viewport.
return matchMedia('(orientation: portrait)').matches ? 'portrait' : 'landscape';
}
function update() {
document.documentElement.dataset.orientation = currentOrientation();
}
if (screen.orientation?.addEventListener) {
screen.orientation.addEventListener('change', update);
} else {
matchMedia('(orientation: portrait)').addEventListener('change', update);
}
update();

Where the manifest lock is honoured, the app stays in one axis and the listener fires at most for flips between the two variants of that axis. Where the lock is ignored, the same listener lets you switch to a two-column layout when the device turns sideways.

Locking at runtime where the manifest is ignored

Section titled “Locking at runtime where the manifest is ignored”

screen.orientation.lock() can impose the same lock from script, with two constraints the manifest does not have: locking is typically enabled only on mobile devices and in fullscreen, and desktop Chrome and Edge always reject the call with NotSupportedError (MDN, ScreenOrientation.lock() and its compatibility data). The fallback is to do nothing and rely on the responsive layout.

async function lockPortraitIfPossible() {
if (!('orientation' in screen) || typeof screen.orientation.lock !== 'function') {
return 'unsupported'; // Safari: no lock(); layout stays responsive
}
try {
await document.documentElement.requestFullscreen();
await screen.orientation.lock('portrait');
return 'locked';
} catch (err) {
// Desktop Chrome and Edge reject as not supported; an iframe whose sandbox lacks `allow-orientation-lock` rejects as a security error.
return err.name;
}
}

Call it from a click handler, since requestFullscreen() needs user activation, and use the returned string to decide whether the UI keeps its rotate-the-device hint.

Specifications

SpecificationStatus
Web App Manifest: orientationW3C
  • Legend
  • Yes
  • Partial
  • Flag
  • No
  • Unknown
Browser / PlatformSupportVersionsConfidenceSourceNotes
Chrome (Desktop)#Yes39highsource—
Chrome (Android)#Yes39highsource1
Edge (Desktop)#Yes79highsource2
Firefox (Desktop)#No—highsource3
Firefox (Android)#Yes79highsource—
Safari (macOS)#No—highsource4
Safari (iOS)#No—highsource56
Samsung Internet#Yes4.0highsource7
WebView (Android)#Yes39highsource8
  1. Derived by browser-compat-data mirroring from Chrome.
  2. Derived by browser-compat-data mirroring from Chrome.
  3. No Firefox support is recorded in browser-compat-data.
  4. No Safari support is recorded in browser-compat-data.
  5. No Safari on iOS support is recorded in browser-compat-data.
  6. Derived by browser-compat-data mirroring from Safari.
  7. Derived by browser-compat-data mirroring from Chrome Android.
  8. Derived by browser-compat-data mirroring from Chrome Android.

Source data: /compatibility/manifest-orientation.json · Global usage: 76 % (StatCounter 2026-09, CC BY-SA 4.0)

Source: spec · MDN · Last verified 2026-10-03 · Confidence: high (computed from sources)