Instructions to make or update an app's UI so that it adapts to different Android devices including phones, tablets, foldables, laptops, desktop, TV, Auto, and XR. It includes how to handle different window sizes, pointing devices (such as mouse) and text entry devices (such as keyboard) using the Compose MediaQuery API, and how to preserve UI, navigation, scroll, and media playback state across configuration changes (such as folding/unfolding a foldable, rotating a device, or resizing a window). It also covers multi-pane layouts using Navigation3 Scenes, adaptive UI components (such as buttons) with varying target sizes, and adaptive layouts (including navigation areas - nav rails and nav bars) using the Compose Grid and FlexBox APIs. It also covers desktop experiences with keyboard shortcuts, tooltips and custom cursors.
76%
Does it follow best practices?
Run evals on this skill
Adds up to 20 points to the overall score
Passed
No findings from the security scan
Fix and improve this skill with Tessl
tessl review fix ./jetpack-compose/adaptive/SKILL.mdThe app must:
To make an app adaptive, follow these steps or a subset of them adapting to the task.
Ensure that screenshot tests exist to verify the current UI on different form factors. If they don't exist, add the Compose Preview Screenshot Testing tool. Use the following annotation to create previews for all the major form factors. For example:
@Preview(name = "Phone", device = Devices.PHONE, showBackground = true)
@Preview(name = "Foldable", device = Devices.FOLDABLE, showBackground = true)
@Preview(name = "Tablet", device = Devices.TABLET, showBackground = true)
@Preview(name = "Desktop", device = Devices.DESKTOP, showBackground = true)
annotation class FormFactorPreviews
@PreviewTest
@FormFactorPreviews
@Composable
fun FeedScreenPreview() {
SnippetsTheme {
Box {
Text("My Screen")
}
}
}Bottom navigation bars are optimized for touch input when the user is holding a phone in portrait mode. On larger screen hand-held devices, like tablets and unfolded foldables, the navigation area must be accessible from the edge of the screen (navigation rail).
If you need to provide more screen space for the content, hide the navigation area. Examples of this include:
When the detail screen is displayed full-screen on mobile, full-screen mode must be deactivated on larger screens.
Steps to migrate:
NavigationSuiteItem.AnimatedContent or AnimatedVisibility composable. If so, follow the guidance in the "Control navigation area visibility".Scaffold) with NavigationSuiteScaffold from the Material 3 adaptive layouts library.navigationItems parameter of NavigationSuiteScaffold.If the navigation bar's visibility changes - it is hidden under certain
scenarios or on certain screens - this behavior must be maintained with the
adaptive navigation area. This is done using NavigationSuiteScaffold's state
parameter.
Steps to migrate:
isNavBarVisible or shouldShowNavBar as the variable name.NavigationSuiteScaffoldState using rememberNavigationSuiteScaffoldState() and pass it to NavigationSuiteScaffold.LaunchedEffect to call show or hide on the NavigationSuiteScaffoldState.For example:
// Pass this variable to any composable that needs to control the navigation area visibility
var isNavBarVisible by remember { mutableStateOf(true) }
val scaffoldVisibilityState = rememberNavigationSuiteScaffoldState()
NavigationSuiteScaffold(
navigationSuiteItems = navItems,
state = scaffoldVisibilityState
) {
// Main content
}
LaunchedEffect(isNavBarVisible){
if (isNavBarVisible) {
scaffoldVisibilityState.show()
} else {
scaffoldVisibilityState.hide()
}
}Analyze the codebase looking for related screens - tapping on something in one screen opens another screen that shows information related to the first. There are two canonical screen relationships: list-detail and supporting pane.
IMPORTANT: You must use the Navigation 3 SceneStrategy approach to implement
multi-pane layouts. Do not use ListDetailPaneScaffold or
SupportingPaneScaffold.
List-detail layouts display a list of items (this is the list screen) and clicking on an item opens a new screen that shows more details about that item (the detail screen).
Typical usage includes productivity apps like email, notes, and messaging.
Unless requested explicitly, avoid this pattern when the detail content requires substantial screen space (e.g., images or media that benefits from a full-screen presentation).
androidx.compose.material3.adaptive:adaptive-navigation3 libraryandroidx.compose.material3.adaptive.navigation3.ListDetailSceneStrategy using rememberListDetailSceneStrategyListDetailSceneStrategy to NavDisplay using its sceneStrategies parameterentry(metadata = ...) or NavEntry(metadata = ...) to the list entry using ListDetailSceneStrategy.listPane(detailPlaceholder = { <placeholder composable> }).detailPlaceholder parameter to add a placeholder on the detail screen when no list items are selected.ListDetailSceneStrategy.detailPane().For a reference implementation, check the Nav3 Material List Detail recipe.
Identify supporting pane screens where a main screen displays a single item, and selecting it opens a "supporting screen" with more details. The supporting screen complements the main screen and is shown in a supporting pane.
SceneStrategyandroidx.compose.material3.adaptive:adaptive-navigation3 libraryandroidx.compose.material3.adaptive.navigation3.SupportingPaneSceneStrategy using rememberSupportingPaneSceneStrategySupportingPaneSceneStrategy to NavDisplay using its sceneStrategies parameterentry(metadata = ...) or NavEntry(metadata = ...) to the main entry using SupportingPaneSceneStrategy.mainPane()SupportingPaneSceneStrategy.supportingPane()If you have made changes, record new reference files. Ask the user to visually verify that the new layouts are correct.
Look for the following vertical list composables: LazyColumn,
LazyVerticalGrid, LazyVerticalStaggeredGrid.
Steps to migrate:
LazyColumn: change to a LazyVerticalGrid and follow the instruction laterLazyVerticalGrid: change the columns parameter to use GridCells.Adaptive(<width>.dp)LazyVerticalStaggeredGrid: change the columns parameter to use StaggeredGridCells.Adaptive(<width>.dp)WARNING: Grid is an experimental API available from Compose 1.11.0-beta01. Confirm with the user that they are happy to use an experimental API in their codebase.
Look for any Column that contains multiple items of the same type and replace
it with Grid. Do not replace it with LazyVerticalGrid or any other lazy
layout. Do not place Grid inside the existing Column. Completely replace it.
Grid is configured by supplying a lambda (an extension function on
GridConfigurationScope) to its config parameter. Inside the lambda,
constraints provides the minimum and maximum dimensions of the grid container
and can be used to change the number of rows and columns based on the available
size. For example, the following code configures Grid such that when the
available width is:
Grid(
config = {
val maxWidthDp = constraints.maxWidth.toDp()
val (cols, rows) = if (maxWidthDp < 800.dp){
2 to 4
} else{
4 to 2
}
val gapSizeDp = 8.dp
val cellSize = ((maxWidthDp - (gapSizeDp * (cols - 1))) / cols).coerceAtLeast(0.dp)
repeat(cols) { column(cellSize) }
repeat(rows) { row(cellSize) }
gap(gapSizeDp)
}
) { /** items **/ }Grid is an experimental API so add the @OptIn(ExperimentalGridApi::class)
annotation to any function that uses it.
In an app with multiple top-level destinations, each screen must manage its own app bar state independently. There are two main scroll behaviors:
exitUntilCollapsedScrollBehavior: Hides on scroll down, stays hidden while you scroll up until you reach the very top (0 offset).enterAlwaysScrollBehavior: Hides on scroll down, shows immediately on scroll up.IMPORTANT: Never add android:configChanges or android:screenOrientation
to AndroidManifest.xml to suppress Activity recreation or lock orientation.
Opting out of recreation hides state-loss bugs instead of fixing them, breaks
adaptive resource reloading, and prevents an app's process from restarting.
When fixing state loss across configuration changes, systematically audit
every usage of remember across all screens, components, and state holders
(in other words, do not only search for remember { mutableStateOf(...) }):
remember { mutableStateOf(...) } with rememberSaveable { mutableStateOf(...) } for user input and interactive UI state, such as TextField draft text, search queries, scroll position, and toggle states.rememberSaveable(conversationId) { mutableStateOf("") }).Set) that are not natively Bundle-saveable:
MutableState<T> via var state by rememberSaveable(...) { mutableStateOf(...) }, pass your custom Saver using stateSaver (do not pass saver = ... when the block returns MutableState<T>):// this Saver implementation converts CustomState object which we don't know how to save
// to List<String> which we can save
private val CustomStateSaver = Saver<CustomState, List<String>>(
save = { customState -> customState.values.map { it.value } },
restore = { values -> CustomState(values.map { CustomStateValue.valueOf(it) }.toSet()) }
)
@Composable
fun MyComposable() {
var customState by rememberSaveable(stateSaver = CustomStateSaver) {
mutableStateOf(CustomState())
}
}@Serializable and use rememberSerializable.Plain remember { LazyListState() }, remember { LazyGridState() }, and
remember { ScrollState(...) } do not save scroll position across
configuration changes because they bypass the state class's Saver.
Inspect all scrollable containers (LazyColumn, LazyRow, LazyVerticalGrid,
LazyHorizontalGrid, LazyVerticalStaggeredGrid, Modifier.verticalScroll,
and Modifier.horizontalScroll) across all screens and reusable components, and
replace plain remember instantiations with the built-in saveable factory
functions:
remember { LazyListState() } -> rememberLazyListState()remember { LazyGridState() } -> rememberLazyGridState()remember { LazyStaggeredGridState() } -> rememberLazyStaggeredGridState()remember { ScrollState(initial = 0) } -> rememberScrollState()Check out the Navigation 3 guide to Save and manage navigation state for details.
ExoPlayer / Media3)When an MediaPlayer (such as ExoPlayer) is created inside a composable with remember, it is
released on disposal and recreated from scratch on configuration change,
resetting playback to 0:00 and auto-playing even if the user had paused the
video.
To preserve ExoPlayer playback state (currentPosition and playWhenReady):
savedPositionMs (mutableLongStateOf(0L)) and savedPlayWhenReady (mutableStateOf(true)) using rememberSaveable(videoResId).onDispose : update savedPlayWhenReady and savedPositionMs in a Player.Listener (onPlayWhenReadyChanged, onPositionDiscontinuity) and periodically inside a LaunchedEffect(player) loop while active.playWhenReady = savedPlayWhenReady and call seekTo(savedPositionMs) before prepare().LifecycleStartEffect so it does not auto-play a paused video or overwrite savedPlayWhenReady :
LifecycleStartEffect(player), only call player.play() when savedPlayWhenReady is true (otherwise a paused video will start playing again after restoration).onStopOrDispose, capture val wasPlaying = player.playWhenReady and savedPositionMs = player.currentPosition before calling player.pause(), then restore savedPlayWhenReady = wasPlaying so that player.pause() on stop/dispose does not overwrite savedPlayWhenReady to false:@UnstableApi
@Composable
private fun rememberExoPlayer(@RawRes videoResId: Int, fromUri: Unit.(Uri) -> MediaItem): ExoPlayer {
val context = LocalContext.current
var savedPositionMs by rememberSaveable(videoResId) { mutableLongStateOf(0L) }
var savedPlayWhenReady by rememberSaveable(videoResId) { mutableStateOf(true) }
val player = remember(videoResId) {
ExoPlayer.Builder(context.applicationContext).build().apply {
setMediaItem(MediaItem.fromUri(RawResourceDataSource.buildRawResourceUri(videoResId)))
repeatMode = Player.REPEAT_MODE_ONE
playWhenReady = savedPlayWhenReady
seekTo(savedPositionMs)
prepare()
}
}
DisposableEffect(player) {
val listener = object : Player.Listener {
override fun onPlayWhenReadyChanged(playWhenReady: Boolean, reason: Int) {
savedPlayWhenReady = playWhenReady
savedPositionMs = player.currentPosition
}
override fun onPositionDiscontinuity(
oldPosition: Player.PositionInfo,
newPosition: Player.PositionInfo,
reason: Int
) {
savedPositionMs = newPosition.positionMs
}
}
player.addListener(listener)
onDispose {
player.removeListener(listener)
player.release()
}
}
LaunchedEffect(player) {
while (isActive) {
savedPositionMs = player.currentPosition
delay(200)
}
}
LifecycleStartEffect(player) {
if (savedPlayWhenReady) {
player.play()
}
onStopOrDispose {
val wasPlaying = player.playWhenReady
savedPositionMs = player.currentPosition
player.pause()
savedPlayWhenReady = wasPlaying
}
}
return player
}Look at the user's prompt, requirements, or uploaded files to determine which desktop feature needs to be implemented.
Based on the feature identified, you must read the corresponding reference file and follow its instructions:
references/keyboard_shortcuts.mdreferences/tooltips.mdreferences/custom_cursors.mdEach reference starts by searching the whole app for the targets of that feature. Write that list down first, implement all of it (not only the first screen you open), and re-check the list before you finish.
Tabletop mode allows users to view and interact with content while their foldable device is placed on a flat surface. The top screen is angled at a convenient viewing angle and provides visual content. The bottom screen is flat on the surface and provides controls for that content.
To support foldable devices, identify any screens that provide the following:
To create layouts for foldables on these screens, you must read tabletop posture.
Build the app and run the local tests. If the project has screenshot tests, run them but DO NOT update the reference images. Prompt the user to do this after they have viewed the screenshot diffs.
The following APIs are available from Compose 1.11.0.
Check the FlexBox documentation:
Check the MediaQuery documentation when you need to query the device's screen size, pointer precision, keyboard type, whether it has cameras or microphones, and other device capabilities.
Check the Grid documentation when you need to display a fixed number of items in a grid layout:
android/skills
c729425
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.