You can configure your apps to maintain a fixed size or orientation regardless of display size or device orientation (see App configuration below). If an app has requested a fixed orientation or the app is not resizable and its maximum or minimum aspect ratio is incompatible with the aspect ratio of the device display, the app is letterboxed—centered on screen, with mattes (black bars) filling the unused display area along the sides of the app.
Letterboxing happens often on large screen devices, especially foldables, because the device display dimensions and aspect ratio typically are different from those of standard phones, which most apps are designed for.
However, a letterboxed app can still look great on Android.
UI enhancements
Beginning with Android 12 (API level 31) and continuing with 12L (API level 32), the platform applies a variety of enhancements to letterboxed apps.
Device manufacturers implement these UI enhancements—you don't need to do any additional development for your app to take advantage of them.
Android 12
API level 31 introduces the following aesthetic enhancements:
- Rounded corners: The corners of the app window have a more refined look.
- Status bar transparency: Status bars, which overlay the app, are semitransparent, making elements at the top and bottom edges of the app window viewable.
- Configurable aspect ratio: Device manufacturers can adjust the aspect ratio of the app to improve its appearance.
12L
API level 32 adds the following functional improvements:
- Configurable positioning: On large screens, device manufacturers can position the app to the left or right side of the display, making interaction easier.
- Redesigned restart button: Device manufacturers can give the restart button for size compatibility mode a new look for better recognition by users.
App configuration
Letterboxing can happen when apps are not resizable or they have a fixed orientation. Configuration settings that control app orientation and resizability include the following:
screenOrientation: Specifies a fixed orientation for an app. Apps can also set Orientation at runtime by usingActivity#setRequestedOrientation().resizeableActivity: Indicates whether the app can run in multi-window mode, allowing the system to resize it to fit a window of varying dimensions.maxAspectRatio: Specifies the maximum aspect ratio supported by the app. Only apps withresizeableActivityset to false can setmaxAspectRatio.minAspectRatio: Specifies the minimum aspect ratio supported by the app. Only apps withresizeableActivityset to false can setminAspectRatio.
Size compatibility mode
Size compatibility mode is letterboxing that includes a restart control. Apps enter size compatibility mode when the platform determines that it can improve the display of a letterboxed app by rescaling the app to fill the device display in at least one dimension. The aspect ratio of the app and the original bounds of the app are maintained. The platform might scale an app down to fit the screen, but it will never scale an app up. The restart control restarts the activity, redrawing the display.
Size compatibility mode typically applies to activities that are restricted in orientation or aspect ratio and are configured (or determined by the platform) to be unresizable (see App configuration). When the activity moves to a display container that has incompatible dimensions, the system invokes size compatibility mode.
Device configuration changes that can trigger size compatibility mode include the following:
- Device rotation
- Foldable device folding or unfolding
- Change between full screen and split-screen display modes
Think outside the letterbox
The Android 12 enhancements improve the appearance of letterboxed apps, but the best improvement is to make your apps resizable and give them a responsive UI that adapts to displays of all sizes.
Resizable apps support multi-window mode, and responsive UIs provide the optimal user experience.
For development guidance, see the following guides: