# orientation: requesting a PWA's default screen

> What the manifest orientation member requests, how it relates to the separate Screen Orientation API, and what happens when a value isn't honored.

import CompatTable from '@components/CompatTable.astro';

**In one line:** The manifest `orientation` member requests a default screen orientation
— such as `portrait` or `landscape` — for an installed web app's top-level windows,
subject to what the browser and device actually honor.

## Where it is supported

<CompatTable feature="manifest-orientation" />

Per MDN and the spec, `orientation` support and behavior are conditional on the browser
and device honoring the requested value — treat this as a preference, not a guarantee.

## How to use it

Declare the member in the web app manifest with one of the spec's keyword values:

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

Accepted values per the spec include `any`, `natural`, `landscape`, `landscape-primary`,
`landscape-secondary`, `portrait`, `portrait-primary`, and `portrait-secondary`.

## How to detect it at runtime

The manifest `orientation` member sets the default orientation, which can be overridden at
runtime through other means, including the Screen Orientation API. The separate API's
`lock()` method has limited browser support, so feature-detect it before calling it and keep
the layout adaptable when the method is absent or the call is rejected:

```js
function supportsOrientationLock() {
  return 'orientation' in screen && typeof screen.orientation.lock === 'function';
}

async function lockPortrait() {
  if (!supportsOrientationLock()) {
    return; // no lock API on this browser: fall back to the responsive layout below
  }
  try {
    await screen.orientation.lock('portrait');
  } catch {
    // handle rejection — lock() has limited browser support
  }
}
```

```css
/* Fallback: adapt the layout with CSS instead of assuming either orientation
   mechanism took effect. */
@media (orientation: landscape) {
  .journal-entry {
    grid-template-columns: 1fr 1fr;
  }
}
```

## What goes wrong

- Per MDN and the spec, support for individual `orientation` values can vary by browser
  and device; the user agent attempts to honor the requested value but isn't guaranteed
  to for every value it accepts.
- MDN describes the manifest orientation as a preference the browser or OS attempts to
  honor, and separately documents the Screen Orientation API as a way to change
  orientation at runtime — the two are related but distinct mechanisms.
- Per MDN, omitting `orientation` typically falls back to the device's natural
  orientation together with the user's or system's own orientation settings, not a
  simple, guaranteed passthrough of "natural orientation" alone.
- The manifest `orientation` member and the separate Screen Orientation API
  (`screen.orientation`) are independent capabilities — a user agent can support one
  without the other.

## Where to go next

- [Web App Manifest: orientation support](/compatibility/manifest-orientation/) —
  browser support matrix
- [Manifest display modes: standalone vs fullscreen](/reference/manifest/display/) —
  the display mode this orientation request applies within