Platform Android Studio Google Play Jetpack Kotlin Docs News
Overview Guides Reference Samples Design & Quality
Android Dev Summit, October 23-24: two days of technical content, directly from the Android team. Sign-up for livestream updates.

Declare restricted screen support

Although we strongly recommend that you design your app so it can adapt to all screen sizes and densities, you still might not want your app to support certain screen configurations. If so, you can limit how much Android can resize your app or even restrict which devices can install it, as described on this page.

Before you restrict your app to certain screens, you should understand all the techniques to support multiple screens and implement them to the best of your ability.

Publish separate APKs for different screens

In case it's unreasonable for you to build a single APK that supports all screen configurations, Google Play allows you to publish multiple APKs for the same app listing. You can use this feature to provide separate APKs that each support a different set of screen configurations (as declared in the manifest file) without creating separate listings in the Google Play Store.

For example, if you want to publish both a handset version and a tablet version of your app, but you're unable to make one APK work for both screen sizes, you can publish two APKs for the same app listing. Depending on each device's screen configuration, Google Play will download the APK that matches each device's screen size.

For more information, see Creating Multiple APKs for Different Screen Sizes.

Declare a maximum aspect ratio

To support as many devices as possible, an app should dynamically adapt its layout to ensure its content and controls are visible and well-organized.

Most apps should also be resizeable so the user can run them in multi-window mode. The user can launch a resizeable activity in split-screen and freeform modes and change the size of the activity by dragging its sides or corners.

Multi-window mode is available for all apps running in Android 7.0 (API level 24) or higher and apps are resizeable by default. You can also explicitly set the attribute android:resizeableActivity true for an entire app, or specific activities.

If you do not want your app or activity to run in multi-window mode, set android:resizeableActivity false. In this case, the app always appears on the full screen. The system controls how this is done, depending on the Android OS level:

  • If your app targets Android 8.0 (API level 26) or higher, it fills the entire screen, according to its layout.
  • If your app targets Android 7.1 (API level 25) or lower, the system limits the size of the app's interface to a window with an aspect ratio of 16:9 (approximately 1.86). If the app runs on a device with a larger screen aspect ratio, the app appears in a 16:9 letterbox that leaves part of the screen unused.

If your app layout cannot adapt to arbitrarily large aspect ratios, you can explicitly enforce letterboxing on all Android OS levels by setting a maximum aspect ratio. We recommend a ratio of 2.4 (12:5). Your app will be letterboxed when it runs on a device with an aspect ratio greater than the one you specify. The value you choose must be at least 1.0 for Wear OS devices, and at least 1.33 for other devices. If you specify a ratio smaller than these limits, the system constrains the aspect ratio of your app depending on the OS level as described above.

To set the maximum aspect ratio for Android 8.0 (API level 26) and higher, declare the max ratio using android:MaxAspectRatio in your <activity> tag. The following example shows how to declare a maximum aspect ratio of 2.4:

<!-- Render on full screen up to screen aspect ratio of 2.4 -->
<!-- Use a letterbox on screens larger than 2.4 -->
<activity android:maxAspectRatio="2.4">
 ...
</activity>

For Android 7.1 and lower, add a <meta-data> element named android.max_aspect in the <application> element, as follows:

<!-- Render on full screen up to screen aspect ratio of 2.4 -->
<!-- Use a letterbox on screens larger than 2.4 -->
<meta-data android:name="android.max_aspect" android:value="2.4" />

If you set a maximum aspect ratio, don't forget to also set android:resizeableActivity false. Otherwise, the maximum aspect ratio has no effect.

Declare a maximum screen size

Even if don't completely optimize your app to support different screen sizes, Android can still stretch most apps to fit larger screens. So it's almost never necessary to declare a maximum screen size.

And if you decide to create multiple APKs for different screen sizes, there's no need to limit an APK to small screens only, because your APK that is optimized for large screens should have the larger versionCode, so Google Play always gives that APK to devices with a large screen.

However, if you're still not satisfied with the way Android resizes your app for large screens, you can disable resizing beyond a certain width by specifying the largestWidthLimitDp attribute in the <supports-screens> manifest tag. Then, instead of resizing your layout, Android enables screen compatibility mode, which draws your layout as it would on the largest size your app supports, and then scale up all the pixels to fill the screen.

Restrict your app for tablets or TVs only

You can prevent handset devices from downloading your app by using the <supports-screens> manifest element.

For example, the following declares that only large and xlarge screens should install your app:

<manifest ... >
    <supports-screens android:smallScreens="false"
                      android:normalScreens="false"
                      android:largeScreens="true"
                      android:xlargeScreens="true"/>
    ...
</manifest>

Restrict your app for specific sizes and densities only

You can define the exact screen sizes and densities your app supports using the <compatible-screens> manifest element. But we strongly recommend you avoid using this because any combination of size and density that you do not specify is considered a screen configuration with which your app is not compatible. So using this element makes it easy to block your app from lots of devices that your app actually can support.

The <compatible-screens> element must contain one or more <screen> elements. Each <screen> element specifies a screen configuration with which your app is compatible, using both the android:screenSize and android:screenDensity attributes. Each <screen> element must include both attributes to specify an individual screen configuration—if either attribute is missing, then the element is invalid (external services such as Google Play will ignore it).

Here's what the manifest entry looks like if your app is compatible with only small and normal screen sizes (and a subset of screen densities):

<manifest ... >
    <compatible-screens>
        <!-- all small size screens -->
        <screen android:screenSize="small" android:screenDensity="ldpi" />
        <screen android:screenSize="small" android:screenDensity="mdpi" />
        <screen android:screenSize="small" android:screenDensity="hdpi" />
        <screen android:screenSize="small" android:screenDensity="xhdpi" />
        <!-- all normal size screens -->
        <screen android:screenSize="normal" android:screenDensity="ldpi" />
        <screen android:screenSize="normal" android:screenDensity="mdpi" />
        <screen android:screenSize="normal" android:screenDensity="hdpi" />
        <screen android:screenSize="normal" android:screenDensity="xhdpi" />
    </compatible-screens>
    ...
    <application ... >
        ...
    <application>
</manifest>

Any size and density combination not explicitly declared here will be restricted from installing the app.

Previous
Support display cutouts
Next
Overview