Managing CSS Safe Area Insets for Android Cutouts in TWAs

Modern Android smartphones feature edge-to-edge screens with hardware cutouts for front-facing cameras, sensors, and speaker grills. These design elements, often referred to as notches or pinholes, can obstruct web application layouts if not managed correctly. When converting your Progressive Web App (PWA) into an Android app using a Trusted Web Activity (TWA), your web content has the ability to render behind these system cutouts to provide an immersive, native-like user experience. However, without precise CSS adjustments, critical UI elements such as action bars, navigation drawers, and floating action buttons can become obscured or unclickable.

Understanding How Android Handles Display Cutouts

By default, Android wraps web content inside a TWA within a standard viewport that respects the safe boundaries of the screen. This means the system status bar at the top and the navigation bar at the bottom remain solid black or colored blocks, and your web app is bounded between them. While this prevents your layout from being cut off, it breaks the native app aesthetic by creating distinct borders around the viewport.

To create a truly immersive application, you can configure your TWA to render in fullscreen or edge-to-edge mode. When edge-to-edge mode is active, the web view expands to occupy the absolute limits of the physical display, drawing content underneath both the status bar and the display cutout area. This is where CSS safe area variables become essential to prevent content overlap.

Configuring the Viewport Meta Tag for Edge-to-Edge Rendering

The first step in controlling layout rendering around screen cutouts is adjusting the HTML viewport meta tag in your PWA. By default, most mobile viewports restrict content to the safe area. To instruct the rendering engine to extend the web layout to the physical edges of the display, you must use the viewport-fit property.

You must add the viewport-fit parameter with a value of cover to your existing viewport meta tag inside the head of your document. The standard configuration looks like this:

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

Setting this property tells the underlying Custom Tab engine that your application is prepared to handle the entire screen area, including areas covered by notches or the status bar. Once applied, your application's background colors will stretch to the very top and bottom of the display. However, any text or interactive elements positioned near the top of the viewport will now slide underneath the camera cutout.

Writing CSS with Safe Area Insets

To prevent interactive components from ending up beneath the screen cutout, CSS provides environment variables that expose the exact boundaries of the safe display region. These variables are defined by the CSS Values and Units Module and are exposed in browsers supporting the safe-area-inset properties.

The four main environment variables you must use to adjust your layout are:

• safe-area-inset-top: The distance from the top of the physical screen to the safe area boundary, typically encompassing the status bar and camera notch.
• safe-area-inset-bottom: The distance from the bottom of the screen to the safe area, which covers virtual navigation pills or gestures.
• safe-area-inset-left: The distance from the left edge of the screen to the safe area, relevant during landscape orientation.
• safe-area-inset-right: The distance from the right edge of the screen to the safe area, also relevant in landscape.

These variables can be integrated directly into your CSS layout rules using the env function. For example, if you have a fixed top navigation header, you must add padding to ensure the text remains visible below the camera cutout:

header { padding-top: env(safe-area-inset-top); }

If your header already has default padding, you can combine the value with the CSS calc function to ensure your layout proportions remain consistent on devices with and without cutouts:

header { padding-top: calc(16px + env(safe-area-inset-top)); }

Fallback Strategies for Older Browsers

While almost all modern Android devices running Chrome support the CSS env function, it is best practice to provide fallback values for older browser engines or alternative platforms that do not recognize these variables. CSS properties that contain unrecognized functions are ignored completely, meaning a single missing fallback can break your layout padding.

To solve this, declare the fallback property directly before the rule that uses the env function:

header { padding-top: 16px; padding-top: calc(16px + env(safe-area-inset-top)); }

If the device supports the env function, the second rule will override the first. If not, the first rule remains active, ensuring a safe layout margin on all devices.

Handling Landscape Orientations and Side Cutouts

When an Android device is rotated into landscape mode, physical cutouts that were previously at the top of the screen are now positioned on the left or right side. If your TWA supports landscape orientation, failing to account for side insets will cause your sidebar menus or left-hand content to merge into the camera punch-hole.

To avoid this, apply the left and right safe area insets to your main container elements. By using a wrapper container for your entire application, you can dynamically shift content away from the sides of the screen without altering your individual component layouts:

.app-wrapper { padding-left: env(safe-area-inset-left); padding-right: env(safe-area-inset-right); }

This configuration creates protective margins on both sides of the screen when in landscape mode, while automatically collapsing to zero pixels when the device is held in portrait mode, where the side insets are non-existent.

Summary of Cutout Management Properties

The following table outlines the CSS safe area variables, their behaviour in different device orientations, and how they apply to your TWA application UI:

By implementing these safe area CSS rules throughout your progressive web application, your TWA will scale across various Android screen shapes, notches, and virtual control schemes. This prevents layouts from feeling misplaced and ensures that vital interaction points are always accessible to your users.