docs.rodeo

MDN Web Docs mirror

orientation

{{QuickLinksWithSubpages("/en-US/docs/Web/Progressive_web_apps/Manifest/Reference")}} 

The orientation manifest member is used to specify the default orientation for your web application. It defines how the app should be displayed when launched and during use, in relation to the device’s screen orientation, particularly on devices that support multiple orientations.

[!NOTE] The app’s orientation can be changed during runtime through various means, such as using the Screen Orientation API.

Syntax

/* Keyword values */
"orientation": "any"
"orientation": "natural"
"orientation": "portrait"
"orientation": "portrait-primary"
"orientation": "portrait-secondary"
"orientation": "landscape"
"orientation": "landscape-primary"
"orientation": "landscape-secondary"

Values

Description

To understand the orientation manifest member, it’s important to be familiar with the following orientation-related concepts:

When a device is rotated, it typically changes the screen orientation. For example, rotating a mobile phone from vertical to horizontal usually switches the screen from portrait to landscape mode. Without any specific orientation set in the manifest, most apps will adjust their layout to fit this new screen orientation.

The manifest’s orientation member allows you to control how your app responds to these changes. By specifying a preferred orientation for your app, you can decide whether your app should adapt to screen orientation changes or maintain a fixed layout regardless of how the device is held. For example, by setting "orientation": "portrait-primary", you can indicate that you prefer your app to always be displayed in upright portrait mode relative to the screen, even if the device is rotated. The browser or operating system will attempt to honor this preference when possible.

The example below illustrates how a web app’s layout might appear when a mobile phone is rotated. For this example, assume that the app’s orientation value is set to any, allowing the app to rotate between all orientation values when the mobile phone is rotated. Also assume that both the phone and the browser support all orientations. The sequence shows a clockwise rotation of the phone, with each position rotated from the starting position as follows:

<div class="container">
  <div class="orientation">
    <div class="device portrait-primary">
      <div class="screen">
        <div class="title-bar">App Title Bar</div>
        <div class="content">App content in portrait mode</div>
      </div>
    </div>
    <div class="label"><code>portrait-primary</code></div>
  </div>
  <div class="orientation">
    <div class="device landscape-primary">
      <div class="screen">
        <div class="title-bar">App Title Bar</div>
        <div class="content">App content in landscape mode</div>
      </div>
    </div>
    <div class="label"><code>landscape-primary</code></div>
  </div>
  <div class="orientation">
    <div class="device portrait-secondary">
      <div class="screen">
        <div class="title-bar">App Title Bar</div>
        <div class="content">App content in inverted portrait mode</div>
      </div>
    </div>
    <div class="label"><code>portrait-secondary</code></div>
  </div>
  <div class="orientation">
    <div class="device landscape-secondary">
      <div class="screen">
        <div class="title-bar">App Title Bar</div>
        <div class="content">App content in inverted landscape mode</div>
      </div>
    </div>
    <div class="label"><code>landscape-secondary</code></div>
  </div>
</div>

.container {
  display: grid;
  grid-template-columns: 1fr 1fr;
  grid-gap: 40px;
  padding: 20px;
}

.orientation {
  display: flex;
  flex-direction: column;
  align-items: center;
  text-align: center;
}

.device {
  width: 200px;
  height: 300px;
  border: 5px solid black;
  border-radius: 20px;
  position: relative;
  background-color: white;
  margin-bottom: 10px;
}

.screen {
  width: 180px;
  height: 280px;
  border-radius: 15px;
  background-color: lightgrey;
  margin: 10px;
  overflow: hidden;
  display: flex;
  flex-direction: column;
}

.title-bar {
  background-color: #4285f4;
  color: white;
  padding: 5px;
  text-align: center;
  font-weight: bold;
}

.content {
  flex-grow: 1;
  display: flex;
  justify-content: center;
  align-items: center;
  padding: 10px;
  text-align: center;
}

.landscape-primary,
.landscape-secondary {
  width: 300px;
  height: 200px;
}

.landscape-primary .screen,
.landscape-secondary .screen {
  width: 280px;
  height: 180px;
}

.portrait-secondary {
  transform: rotate(180deg);
}

.landscape-secondary {
  transform: rotate(180deg);
}

.label {
  margin-top: 10px;
  font-family: Arial, sans-serif;
  font-size: 15px;
}

{{EmbedLiveSample('Description', '', 800)}} 

Scope and default behavior

The specified orientation is applied to all top-level {{Glossary("Browsing context", "browsing contexts")}}  of the web app.

If a browser supports the specified orientation value, it will use this as the default app orientation throughout the app’s lifespan, unless overridden at runtime. This means that browsers will revert to this default orientation whenever the top-level browsing context is navigated.

Choosing a preferred orientation for your web app

By setting a specific orientation, you can ensure that your web app is displayed optimally for its content and user interface. For example, a video app is often better suited to landscape orientation, while a reading app typically works better in portrait orientation.

Not specifying an orientation can also be a deliberate choice, allowing your web app to adapt flexibly to different devices and user preferences.

Manifest orientation vs. Screen Orientation API behavior

While the orientation manifest member sets the default orientation of the web app, the orientation of a top-level browsing context can be changed once the web app is running using the Screen Orientation API.

The orientation values are similar across the web app manifest and the Screen Orientation API, but their behavior and purposes differ.

Platform and browser limitations

When adding the orientation preference for your app, keep the following considerations and limitations mind:

Examples

Specifying a fixed orientation for a web app

This example sets the app’s orientation to portrait-primary. Assuming browser and device support, the app will always display in upright portrait mode even when the device is rotated.

{
  "name": "My Web App",
  "orientation": "portrait-primary"
}

Setting a flexible orientation for a web app

Consider a photo viewing and editing app. In the app’s manifest file, as shown below, orientation is set to any. This allows the app to be launched in the device’s current orientation and adapt to both portrait and landscape orientations as users rotate their devices. This orientation setting will enable users to view and edit photos comfortably in whichever orientation best suits the current display or their current usage context.

{
  "name": "PhotoGallery Pro",
  "short_name": "PhotoGal",
  "description": "A professional photo gallery and editing application",
  "start_url": "/index.html",
  "display": "standalone",
  "orientation": "any",
  "icons": [
    {
      "src": "icon-192.png",
      "sizes": "192x192",
      "type": "image/png"
    }
  ],
  "related_applications": [
    {
      "platform": "play",
      "url": "https://play.google.com/store/apps/details?id=com.example.photogallery"
    }
  ]
}

Specifications

{{Specifications}} 

Browser compatibility

{{Compat}} 

See also

In this article

View on MDN