lightbulb_outline Please take our October 2018 developer survey. Start survey

Support display cutouts

device with a display cutout

A display cutout is an area on some devices that extends into the display surface to allow for an edge-to-edge experience while providing space for important sensors on the front of the device. Android officially supports display cutouts on devices running Android 9 (API level 28) and higher. Note that device manufacturers can also choose to support display cutouts on devices running Android 8.1 or lower.

This topic describes how to implement support for devices with cutouts, including how to work with the cutout area--that is, the edge-to-edge rectangle on the display surface that contains the cutout.

What to expect on devices with display cutouts

To ensure consistency and app compatibility, devices running Android 9 must ensure the following cutout behavior:

  • A single edge can contain at most one cutout.
  • A device cannot have more than two cutouts.
  • A device cannot have cutouts on either of its longer edges.
  • In portrait orientation with no special flags set, the status bar must extend to at least the height of the cutout.
  • By default, in fullscreen or landscape orientation, the entire cutout area must be letterboxed.

Choose how your app handles cutout areas

If you don't want your content to overlap with a cutout area, making sure that your content does not overlap with the status bar and the navigation bar is generally sufficient. If you are rendering into the cutout area, you can use WindowInsets.getDisplayCutout() to retrieve a DisplayCutout object that contains the safe insets and bounding box for each cutout. These APIs let you check whether your content overlaps with the cutout so that you can reposition, if needed.

Android also allows you to control whether to display content inside of the cutout area. The window layout attribute layoutInDisplayCutoutMode controls how your content is drawn in the cutout area. You can set layoutInDisplayCutoutMode to one of the following values:

You can set the cutout mode either programmatically or by setting a style in your activity. The example below defines a style that you can use to apply the LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES attribute to the activity.

<style name="ActivityTheme">
  <item name="android:windowLayoutInDisplayCutoutMode">
    shortEdges <!-- default, shortEdges, never -->
  </item>
</style>

The sections below describe the different cutout modes in more detail.

Default behavior

By default, in portrait mode with no special flags set, the status bar on a device with a cutout is resized to be at least as tall as the cutout, and your content displays in the area below. In landscape or fullscreen mode, your app window is letterboxed so that none of your content displays in the cutout area.

Render content in short edge cutout areas

For some content, such as videos, photos, maps, and games, rendering in the cutout area can be a great way to provide a more immersive, edge-to-edge experience for users. With LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES, the content extends into the cutout area on the short edge of the display in both portrait and landscape, regardless of whether the system bars are hidden or visible. Note that the window can never extend into a cutout area on the long edges of the screen. When using this mode, be sure that no important content overlaps with the cutout area.

Note that Android might not allow the content view to overlap the system bars. To override this behavior and force content to extend into the cutout area, apply any of the following flags to the view visibility via the View.setSystemUiVisibility(int) method:

  • SYSTEM_UI_FLAG_LAYOUT_FULLSCREEN
  • SYSTEM_UI_FLAG_LAYOUT_HIDE_NAVIGATION
  • SYSTEM_UI_FLAG_LAYOUT_STABLE

Here are some examples of LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES:

content rendering into the cutout area while in portrait mode

content rendering into the cutout area while in landscape mode

Note that a cutout in the corner is considered to be on the short edge, so the same behavior applies:

device with a corner cutout

Never render content in the display cutout area

With LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER, the window is never allowed to overlap with the cutout area.

This mode should be used with windows that transiently set View.SYSTEM_UI_FLAG_FULLSCREEN or View.SYSTEM_UI_FLAG_HIDE_NAVIGATION to avoid performing another layout of the window when the flag is set or cleared.

See examples of LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER below:

Special mode

Some devices running Android 8.1 (API level 27) or earlier support a special mode that lets users extend a letterboxed fullscreen or landscape app into the cutout area. This mode is typically controlled with a toggle in the navigation bar that presents a dialog that requires confirmation before extending the screen.

Best practices for display cutout support

When working with display cutouts, be sure to consider the following:

  • Don't let the cutout area obscure any important text, controls, or other information.
  • Don't place or extend any interactive elements that require fine touch recognition into the cutout area. Touch sensitivity might be lower in the cutout area.
  • Avoid hard-coding the status bar height, as this can lead to overlapping or cut-off content. Where possible, use WindowInsetsCompat to retrieve the status bar height and determine the appropriate padding to apply to your content.

  • Don't assume that the app has the entire window. Instead, confirm its location by using View.getLocationInWindow(). Don't use View.getLocationOnScreen().

  • Be sure to properly handle transitions into and out of fullscreen mode. this Android Developers blog post .

  • With default cutout behavior in portrait mode, if the cutout area is at the top edge and the window did not set FLAG_FULLSCREEN or View.SYSTEM_UI_FLAG_FULLSCREEN, the window can extend into the cutout area. Similarly, if the cutout area is at the bottom edge and the window did not set View.SYSTEM_UI_FLAG_HIDE_NAVIGATION, the window can extend into the cutout area. In fullscreen or landscape modes, the window is laid out such that it does not overlap with the cutout area.

  • Use shortEdges or never cutout modes if your app needs to transition into and out of fullscreen mode. Default cutout behavior can cause content in your app to move up and down during transitions, as demonstrated in the image below:

  • In fullscreen mode, be careful using window versus screen coordinates, as your app does not take up the whole screen when letterboxed. Because of the letterbox, coordinates from the screen origin are no longer the same as coordinates from the window origin. You can transform screen coordinates to the view’s coordinates as needed by using getLocationOnScreen(). The image below shows how coordinates differ when content is letterboxed:

    When handling MotionEvent, use MotionEvent.getX() and MotionEvent.getY() to avoid similar coordinate issues. Don't use MotionEvent.getRawX() or MotionEvent.getRawY().

Test how your content renders

simulating a display cutout in the emulator

Be sure to test all of your app's screens and experiences. Test on devices with different types of cutouts, if possible. If you don't have a device with a cutout, you can simulate some common cutout configurations on any device or emulator running Android 9 by doing the following:

  1. Enable developer options.
  2. In the Developer options screen, scroll down to the Drawing section, and select Simulate a display with a cutout.
  3. Select the cutout type.

Additional resources

For more information about display cutout support, see the following links: