Manifest member in Manifest
orientation manifest member
Published Updated
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.
Member
Section titled “Member”| 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.
Examples
Section titled “Examples”Handle browsers that ignore the orientation lock with a layout that works in either orientation.
Declaring a portrait-only field journal
Section titled “Declaring a portrait-only field journal”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.
See also
Section titled “See also”- display manifest member
- scope manifest member
- WebAPK: how Chrome installs PWAs on Android
- Web Application Manifest: orientation member (w3.org)
- ScreenOrientation: lock() method (developer.mozilla.org)
Specifications
| Specification | Status |
|---|---|
| Web App Manifest: orientation | W3C |
- Legend
- Yes
- Partial
- Flag
- No
- Unknown
| Browser / Platform | Support | Versions | Confidence | Source | Notes |
|---|---|---|---|---|---|
| Chrome (Desktop)# | Yes | 39 | high | source | — |
| Chrome (Android)# | Yes | 39 | high | source | 1 |
| Edge (Desktop)# | Yes | 79 | high | source | 2 |
| Firefox (Desktop)# | No | — | high | source | 3 |
| Firefox (Android)# | Yes | 79 | high | source | — |
| Safari (macOS)# | No | — | high | source | 4 |
| Safari (iOS)# | No | — | high | source | 56 |
| Samsung Internet# | Yes | 4.0 | high | source | 7 |
| WebView (Android)# | Yes | 39 | high | source | 8 |
- Derived by browser-compat-data mirroring from Chrome.
- Derived by browser-compat-data mirroring from Chrome.
- No Firefox support is recorded in browser-compat-data.
- No Safari support is recorded in browser-compat-data.
- No Safari on iOS support is recorded in browser-compat-data.
- Derived by browser-compat-data mirroring from Safari.
- Derived by browser-compat-data mirroring from Chrome Android.
- Derived by browser-compat-data mirroring from Chrome Android.