Managing Screen Orientation and Display Modes in Android PWAs

When launching a website on a mobile device, the browser wrapper controls the screen orientation, status bar integration, and layout boundaries. However, once you convert your Progressive Web App into a signed Android application via a Trusted Web Activity (TWA), your web application assumes full control of the device screen. Managing display modes, locking orientation for specific experiences, and designing around modern screen cutouts (notches) are essential steps to deliver an interface that behaves like a natively compiled app.

Web App Manifest Display Modes on Android

The display property in your Web App Manifest defines how much of the browser's chrome remains visible to the user. When compiling your PWA into an Android package, the TWA reader parses this key to determine the window style of your Android Activity.

For almost all business applications, SaaS tools, and content platforms, standalone is the optimal choice. It makes the browser URL bar, refresh buttons, and navigation controls disappear completely, while retaining the standard Android system bar at the top of the screen. This allows the user to monitor battery life, network connections, and system notifications while using your application.

If you choose fullscreen, be aware that you must handle the exit and entry of this mode gracefully within your app's web UI. Fullscreen hides the Android navigation buttons, meaning users must swipe from the edge of the screen to reveal back buttons, which can sometimes interfere with your internal application touch gestures.

Locking Screen Orientation in your Android PWA

Many applications, such as games, point-of-sale systems, or dedicated dashboards, require a locked screen orientation to prevent layouts from breaking when the user tilts their mobile device. The Web App Manifest offers a standard way to declare this intent via the orientation property.

You can set your desired orientation using several standard manifest values:

• portrait: Forces the app to load and stay in portrait mode, ignoring device rotation.
• landscape: Forces the application to render horizontally.
• any: Allows full rotation across all four quadrants based on device sensors.

When you build your APK or AAB, the TWA toolchain reads the orientation property from your web manifest and hardcodes it into the AndroidManifest.xml file under the main Activity configuration. This ensures that even before your web assets load, the Android operating system locks the screen orientation immediately upon app launch, preventing jarring orientation shifts during the splash screen phase.

If your application requires dynamic orientation changes (for example, a video player that should rotatable only when a video plays), you should avoid hardcoding a lock in your manifest. Instead, keep the manifest orientation set to any, and manage rotation dynamically inside your JavaScript using the Screen Orientation API:

Note that standard browsers often restrict screen orientation locking unless the web page is running in fullscreen mode. However, inside a wrapped TWA environment, because the app already runs in a standalone window, these API locks are highly reliable and behave consistently across modern Android versions.

Handling Notches and Safe Areas

Modern Android smartphones feature camera cutouts, hole punches, and notches that physically encroach on the display canvas. If your PWA is configured to run in fullscreen or uses modern edge-to-edge layouts that draw behind the status bar, your web content can easily be obscured by these physical hardware features.

To design defensively against display cutouts, you must use a combination of viewport configurations and CSS environment variables. First, configure your viewport meta tag in your HTML header to support edge-to-edge drawing:

Setting viewport-fit=cover instructs the browser engine to expand the HTML document to fill the entire physical screen, including the area behind the camera notch and the navigation bar. If you do not specify this, the browser engine will artificially letterbox your application, creating unwanted black bars at the top or bottom of your UI.

Once edge-to-edge drawing is enabled, you must use CSS safe area variables to pad your interactive elements. This prevents critical buttons, header text, or custom navigation bars from slipping behind physical camera cutouts or the Android home navigation swipe area.

These variables dynamically resolve to the exact pixel width or height of the screen obstruction on the user's specific device. On devices without a notch, they fallback gracefully to the default values provided as the second argument (such as 20px or 16px).

Testing Orientation and Display Rules

To verify your screen orientation locks and display configurations, you must test on physical devices or accurate emulators. The Chrome DevTools mobile emulator on desktop can simulate screen dimensions and basic orientation flips, but it does not emulate native Android notch behaviour or system-level orientation locks enforced by the AndroidManifest.xml.

Compile your PWA using a Trusted Web Activity build tool and install the resulting debug APK onto your test device. Rotate the device 180 degrees and check if the layout adjusts smoothly without causing visual artifacts. Ensure that critical action buttons are not clipped by rounded screen corners or the camera punch-hole, and confirm that the status bar text remains legible against your application header colour.