Handling Display Cutouts and Notches in Android TWAs

Modern Android smartphones feature edge-to-edge displays with physical cutouts for front-facing cameras and sensors. These cutouts, commonly referred to as notches or punch holes, present a unique design challenge when deploying web applications to mobile app stores. When a Progressive Web App (PWA) runs inside a Trusted Web Activity (TWA) wrapper, developers must explicitly manage how web content flows around these system interruptions to avoid layout clipping and compromised user experiences.

Understanding Viewport Fit and Android Display Modes

By default, when an Android device loads a web app in a standard mobile browser or a standard TWA configuration, the rendering engine limits the web canvas to the safe area of the screen. This means the browser automatically adds letterboxing or pillarboxing around the notch, pushing the viewport below the status bar. While this default behaviour prevents text from being obscured by the camera hardware, it leaves a visually unappealing, solid-coloured bar at the top of the app, ruining the native application aesthetic.

To achieve a truly immersive, edge-to-edge layout that mirrors high-end native apps, you must configure your web viewport to draw content beneath the status bar and display cutout areas. How this displays is highly dependent on your app manifest settings. The table below illustrates how different display modes interact with the system status bar and display cutouts on Android devices.

Configuring the Viewport Meta Tag for Bezel-Less Displays

The first step in taking control of the entire screen is updating your HTML document viewport meta tag. This tag controls the document width, scaling, and scaling limits. To instruct the rendering engine (Blink/Chromium in the case of Android TWAs) to expand content to the physical edge of the display, you must include the viewport-fit property.

Add the following viewport declaration inside the head of your main HTML document:

<meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover">

The critical parameter here is viewport-fit=cover. Setting this parameter forces the document viewport to match the physical dimensions of the screen, including the areas occupied by display cutouts. Once applied, your background colours, gradients, and images will bleed seamlessly into the status bar area and behind camera punch holes. However, because the content now occupies the cutout zone, standard header links, back buttons, and navigation elements run the risk of becoming physically covered by the camera lens or clipped by curved screen corners.

Utilising CSS Safe Area Variables to Avoid Content Clipping

After instructing the browser to draw over the entire screen, you must protect your interactive elements by utilising CSS environment variables. The W3C CSS Working Group introduced four predefined variables that query the layout engine for the exact pixel dimensions of the unsafe zones on each side of the screen.

• env(safe-area-inset-top): The height of the cutout zone at the top of the display.
• env(safe-area-inset-bottom): The height of the navigation bar or physical home indicator zone at the bottom.
• env(safe-area-inset-left): The width of any left-side cutout, relevant when the device is rotated to landscape mode.
• env(safe-area-inset-right): The width of any right-side cutout in landscape mode.

These values are dynamically populated by Android according to the active device hardware. If the device has no notch or is running in a mode where the status bar is not overlaid, these variables evaluate to zero pixels, making them entirely safe to use across all screen formats.

Practical CSS Implementation Examples

To implement these variables effectively, apply padding or margins to your top and bottom navigation bars. Below is an example of a CSS layout for a fixed mobile header that guarantees text and interactive icons remain completely readable and tappable below any camera punch holes.

header { position: fixed; top: 0; left: 0; right: 0; height: 60px; background-color: #111111; padding-top: env(safe-area-inset-top); box-sizing: content-box; }

By setting the padding-top to the top safe area inset and changing the box-sizing property to content-box, you ensure that the internal content area of the header remains exactly 60 pixels tall, while the physical container expands upward to cover the background space beneath the status bar.

For complex layouts where you need to add fallback values for older browsers that do not support environment variables, you can declare properties using the following CSS structure:

padding-top: 20px; padding-top: env(safe-area-inset-top, 20px);

In this scenario, if the browser supports safe-area-inset-top, it overrides the static twenty-pixel fallback with the device-specific value, preventing design regression on non-standard configurations.

Managing the Android Status Bar and Navigation Bar

A complete edge-to-edge aesthetic relies on harmonising your CSS environment styling with the underlying Android operating system. When compiling your PWA into a TWA, your Android app configuration utilizes the theme_color property declared in your web app manifest to set the primary colour of the status bar. Ensure that this manifest value perfectly matches the background color applied to your web header layout.

If you prefer a translucent or fully transparent status bar, you can modify your TWA build configurations to enable translucent system bars. Once enabled, ensure your body tag or root container applies the safe-area variables correctly to avoid overlaps with the system time, Wi-Fi, and battery indicator text. It is crucial to test that light and dark system themes are paired with correct contrast colouring for the system icons to ensure notifications and status symbols remain readable.

Testing and Simulating Display Cutouts on Android

Validating the visual rendering of your TWA across thousands of distinct Android handset designs can be challenging without physical testing equipment. However, developers can leverage both Chrome DevTools and native Android Developer Options to simulate various cutout designs.

To test and simulate different display cutouts on a physical Android handset, execute the following steps:

• Open the settings menu on your Android test device and navigate to About Phone.
• Tap the Build Number seven times to unlock Developer Options.
• Navigate back to Settings, enter System, and select Developer Options.
• Scroll down to the Drawing category and select the setting titled Display Cutout.
• Choose between options such as Corner Cutout, Double Cutout, or Punch Hole Cutout to force the system to simulate these hardware profiles.

Once selected, the Android OS alters its layout, forcing your TWA to adapt dynamically. Launch your installed TWA and check that all interactive elements, modals, close buttons, and navigational sidebars adjust cleanly around the newly simulated boundaries, confirming your CSS safe-area implementation is robust and production-ready.