edge-to-edge

$27

-

The app MUST apply system insets, or align content to rulers, so critical

UI remains tappable. Choose only one method to avoid double padding:

• PREFERRED: When available, use Scaffolds and pass PaddingValues to the content lambda.

Scaffold { innerPadding ->

    // innerPadding accounts for system bars and any Scaffold components

    LazyColumn(

        modifier = Modifier

            .fillMaxSize()

            .consumeWindowInsets(innerPadding),

        contentPadding = innerPadding

    ) { /* Content */ }

}

-

PREFERRED: When available, use the automatic inset handling or padding modifiers in material components.

• Material 3 Components manages safe areas for its own components, including:

• TopAppBar

• SmallTopAppBar

• CenterAlignedTopAppBar

• MediumTopAppBar

• LargeTopAppBar

• BottomAppBar

• ModalDrawerSheet

• DismissibleDrawerSheet

• PermanentDrawerSheet

• ModalBottomSheet

• NavigationBar

• NavigationRail

• For Material 2 Components, use the windowInsetsparameter to apply insets manually for BottomAppBar, TopAppBar and BottomNavigation. DO NOT apply padding to the parent container; instead, pass insets directly to the App Bar component. Applying padding to the parent container prevents the App Bar background from drawing into the system bar area. For example, for TopAppBar, choose only one of the following options:

• PREFERRED: TopAppBar(windowInsets = AppBarDefaults.topAppBarWindowInsets)

• TopAppBar(windowInsets = WindowInsets.systemBars.exclude(WindowInsets.navigationBars))

• TopAppBar(windowInsets = WindowInsets.systemBars.add(WindowInsets.captionBar))

-

For components outside a Scaffold, use padding modifiers, such as Modifier.safeDrawingPadding() or Modifier.windowInsetsPadding(WindowInsets.safeDrawing).

Box(

    modifier = Modifier

        .fillMaxSize()

        .safeDrawingPadding()

) {

    Button(

        onClick = {},

        modifier = Modifier.align(Alignment.BottomCenter)

    ) {

        Text("Login")

    }

}

-

For deeply nested components with excessive padding, use WindowInsetsRulers (e.g. Modifier.fitInside(WindowInsetsRulers.SafeDrawing.current)). See the IME section for a code sample.

-

When you need an element (e.g. a custom header or decorative scrim) to

equal the dimensions of a system bar, use inset size modifiers (e.g.

Modifier.windowInsetsTopHeight(WindowInsets.systemBars)).

See the Lists section for a code sample.

Adaptive Scaffolds

• NavigationSuiteScaffold manages safe areas for its own components, like the NavigationRail or NavigationBar. However, the adaptive scaffolds (e.g. NavigationSuiteScaffold, ListDetailPaneScaffold) don't propagate PaddingValues to their inner contents. You MUST apply insets to individual screens or components (e.g., list contentPadding or FAB padding) as described in Step 3 . DO NOT apply safeDrawingPadding or similar modifiers to the NavigationSuiteScaffold parent. This clips and prevents an edge-to-edge screen.

IME

• For each Activity with a soft keyboard, check that android:windowSoftInputMode="adjustResize" is set in the AndroidManifest.xml. DO NOT use SOFT_INPUT_ADJUST_RESIZE because it is deprecated. Then, maintain focus on the input field. Choose one:

-

• PREFERRED: Add Modifier.fitInside(WindowInsetsRulers.Ime.current) to the content container. This is preferred over imePadding() because it reduces jank and extra padding caused by forgetting to consume insets upstream in the hierarchy.

-

• Add imePadding to the content container. The padding modifier MUST be placed before Modifier.verticalScroll(). Do NOT use Modifier.imePadding() if the parent already accounts for the IME with contentWindowInsets (e.g. contentWindowInsets = WindowInsets.safeDrawing). Doing so will cause double padding.

IMEs with Scaffolds code patterns

#### RIGHT

RIGHT because contentWindowInsets contains IME insets, which are passed to the

content lambda as innerPadding.

// RIGHT

Scaffold(contentWindowInsets = WindowInsets.safeDrawing) { innerPadding ->

    Column(

        modifier = Modifier

            .padding(innerPadding)

            .consumeWindowInsets(innerPadding)

            .verticalScroll(rememberScrollState())

    ) { /* Content */ }

}

RIGHT because fitInside fits the content to the IME insets regardless of

contentWindowInsets.

// RIGHT

Scaffold() { innerPadding ->

    Column(

        modifier = Modifier

            .padding(innerPadding)

            .consumeWindowInsets(innerPadding)

            .fitInside(WindowInsetsRulers.Ime.current)

            .verticalScroll(rememberScrollState())

    ) { /* Content */ }

}

RIGHT because the default contentWindowInsets does not contain IME insets, and

imePadding() applies IME insets:

// RIGHT

Scaffold() { innerPadding ->

    Column(

        modifier = Modifier

            .padding(innerPadding)

            .consumeWindowInsets(innerPadding)

            .imePadding()

            .verticalScroll(rememberScrollState())

    ) { /* Content */ }

}

#### WRONG

WRONG because there will be excess padding when the IME opens. IME insets are

applied twice, once with innerPadding, which contains IME insets from the passed

contentWindowInsets values, and once with imePadding:

// WRONG

Scaffold( contentWindowInsets = WindowInsets.safeDrawing ) { innerPadding ->

    Column(

        modifier = Modifier

            .padding(innerPadding)

            .imePadding()

            .verticalScroll(rememberScrollState())

    ) { /* Content */ }

}

WRONG because the IME will cover up the content. Scaffold's default

contentWindowInsets does NOT contain IME insets.

// WRONG

Scaffold() { innerPadding ->

    Column(

        modifier = Modifier

            .padding(innerPadding)

            .verticalScroll(rememberScrollState())

    ) { /* Content */ }

}

IMEs without Scaffolds code patterns

#### RIGHT

The following code samples WILL NOT cause excessive padding.

// RIGHT

Box(

    // Insets consumed

    modifier = Modifier.safeDrawingPadding() // or imePadding(), safeContentPadding(), safeGesturesPadding()

) {

    Column(

        modifier = Modifier.imePadding()

    ) { /* Content */ }

}

// RIGHT

Box(

    // Insets consumed

    modifier = Modifier.windowInsetsPadding(WindowInsets.safeDrawing) // or WindowInsets.ime, WindowInsets.safeContent, WindowInsets.safeGestures

) {

    Column(

        modifier = Modifier.imePadding()

    ) { /* Content */ }

}

// RIGHT

Box(

    // Insets not consumed, but irrelevant due to fitInside

    modifier = Modifier.padding(WindowInsets.safeDrawing.asPaddingValues()) // or WindowInsets.ime.asPaddingValues(), WindowInsets.safeContent.asPaddingValues(), WindowInsets.safeGestures.asPaddingValues()

) {

    Column(

        modifier = Modifier

            .fillMaxSize()

            .fitInside(WindowInsetsRulers.Ime.current)

    ) { /* Content */ }

}

#### WRONG

The following code sample WILL cause excessive padding because IME insets are

applied twice:

// WRONG

Box(

    // Insets not consumed

    modifier = Modifier.padding(WindowInsets.safeDrawing.asPaddingValues()) // or WindowInsets.ime.asPaddingValues(), WindowInsets.safeContent.asPaddingValues(), WindowInsets.safeGestures.asPaddingValues()

) {

    Column(

        modifier = Modifier.imePadding()

    ) { /* Content */ }

}

Navigation Bar Contrast & System Bar Icons

-

If the Activity uses enableEdgeToEdge from WindowCompat, you MUST set

isAppearanceLightNavigationBars and isAppearanceLightStatusBars to the

inverse of the device theme for apps that support light and dark theme so the

system bar icons are legible. It's recommended to do this in your theme file.

DO NOT do this if the Activities use enableEdgeToEdge from ComponentActivity

because it handles the icon colors automatically.

// Only use if calling `enableEdgeToEdge` from `WindowCompat`.

// Apply to your theme file.

@Composable

fun MyTheme(

    darkTheme: Boolean = isSystemInDarkTheme(),

    content: @Composable () -> Unit

) {

    val view = LocalView.current

    if (!view.isInEditMode) {

        SideEffect {

            val window = (view.context as? Activity)?.window ?: return@SideEffect

            val controller = WindowCompat.getInsetsController(window, view)

            // Dark icons for Light Mode (!darkTheme), Light icons for Dark Mode

            controller.isAppearanceLightStatusBars = !darkTheme

            controller.isAppearanceLightNavigationBars = !darkTheme

        }

    }

    MaterialTheme(content = content)

}

-

If any screen uses a Scaffold or a NavigationSuiteScaffold with a bottom

bar (e.g., BottomAppBar, NavigationBar), set

window.isNavigationBarContrastEnforced = false in the corresponding Activity

for SDK 29+. This prevents the system from adding a translucent background to

the navigation bar, verifying your bottom bar colors extend to the bottom of the

screen.

Lists

• Apply inset padding (like Scaffold's innerPadding) to the contentPadding parameter of scrollable components (e.g. LazyColumn, LazyRow). DO NOT apply it as a Modifier.padding() to the list's parent container, as this clips the content and prevents it from scrolling behind the system bars.

• Create a translucent composable covering the system bar so that the icons are still legible.

class SystemBarProtectionSnippets : ComponentActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {

        super.onCreate(savedInstanceState)

        // enableEdgeToEdge sets window.isNavigationBarContrastEnforced = true

        // which is used to add a translucent scrim to three-button navigation

        enableEdgeToEdge()

        setContent {

            MyTheme {

                // Main content

                MyContent()

                // After drawing main content, draw status bar protection

                StatusBarProtection()

            }

        }

    }

}

@Composable

private fun StatusBarProtection(

    color: Color = MaterialTheme.colorScheme.surfaceContainer,

) {

    Spacer(

        modifier = Modifier

            .fillMaxWidth()

            .height(

                with(LocalDensity.current) {

                    (WindowInsets.statusBars.getTop(this) * 1.2f).toDp()

                }

            )

            .background(

                brush = Brush.verticalGradient(

                    colors = listOf(

                        color.copy(alpha = 1f),

                        color.copy(alpha = 0.8f),

                        Color.Transparent

                    )

                )

            )

    )

}

Dialogs

If both the following conditions are true, then the Dialog is full screen and

must be made edge-to-edge:

• The DialogProperties contains usePlatformDefaultWidth = false.

• The Dialog calls Modifier.fillMaxSize().

To make a full screen Dialog edge-to-edge, set decorFitsSystemWindows = false

in the DialogProperties.

Dialog(

    onDismissRequest = { /* Handle dismiss */ },

    properties = DialogProperties(

        // 1. Allows the dialog to span the full width of the screen

        usePlatformDefaultWidth = false,

        // 2. Allows the dialog to draw behind status and navigation bars

        decorFitsSystemWindows = false

    )

) { /* Content */ }

Checklist

• [ ] Does every Activity call enableEdgeToEdge()?

• [ ] Is adjustResize set in the AndroidManifest.xml?

• [ ] Does every TextField, OutlinedTextField, or BasicTextField have a parent with imePadding(), fitInside, Modifier.safeDrawingPadding(), Modifier.safeContentPadding(), Modifier.safeGesturesPadding(), or contentWindowInsets set to WindowInsets.safeDrawing or WindowInsets.ime?

• [] Does the first and last list item draw away from the system bars by passing insets to contentPadding?

• [] Do FABs draw above the navigation bars by either being inside a Scaffold or by applying Modifier.safeDrawingPadding()?

• [] Does the project build? Run ./gradlew build to be sure.