androidx.compose.foundation.layout

In this page, you'll find documentation for types, properties, and functions available in the androidx.compose.foundation.layout package. For example:

Layouts such as Box, Column, Row, and BoxWithConstraints.
Layout modifiers such as aspectRatio, offset, padding, size, and wrapContentSize.

If you're looking for guidance instead, check out the following Compose guides:

Interfaces

`Arrangement.Horizontal`	Used to specify the horizontal arrangement of the layout's children in layouts like `Row`.	Cmn
`Arrangement.HorizontalOrVertical`	Used to specify the horizontal arrangement of the layout's children in horizontal layouts like `Row`, or the vertical arrangement of the layout's children in vertical layouts like `Column`.	Cmn
`Arrangement.Vertical`	Used to specify the vertical arrangement of the layout's children in layouts like `Column`.	Cmn
`BoxScope`	A BoxScope provides a scope for the children of `Box` and `BoxWithConstraints`.	Cmn
`BoxWithConstraintsScope`	Receiver scope being used by the children parameter of `BoxWithConstraints`	Cmn
`ColumnScope`	Scope for the children of `Column`.	Cmn
`ContextualFlowColumnOverflowScope`	This interface is deprecated. ContextualFlowLayouts are no longer maintained	Cmn
`ContextualFlowColumnScope`	This interface is deprecated. ContextualFlowLayouts are no longer maintained	Cmn
`ContextualFlowRowOverflowScope`	This interface is deprecated. ContextualFlowLayouts are no longer maintained	Cmn
`ContextualFlowRowScope`	This interface is deprecated. ContextualFlowLayouts are no longer maintained	Cmn
`FlowColumnOverflowScope`	Scope for the overflow `FlowColumn`.	Cmn
`FlowColumnScope`	Scope for the children of `FlowColumn`.	Cmn
`FlowRowOverflowScope`	Scope for the overflow `FlowRow`.	Cmn
`FlowRowScope`	Scope for the children of `FlowRow`.	Cmn
`PaddingValues`	Describes a padding to be applied along the edges inside a box.	Cmn
`RowScope`	Scope for the children of `Row`.	Cmn
`WindowInsets`	A representation of window insets that tracks access to enable recomposition, relayout, and redrawing when values change.	Cmn

Classes

`ContextualFlowColumnOverflow`	This class is deprecated. ContextualFlowLayouts are no longer maintained	Cmn
`ContextualFlowRowOverflow`	This class is deprecated. ContextualFlowLayouts are no longer maintained	Cmn
`FlowColumnOverflow`	This class is deprecated. FlowLayout overflow is no longer maintained	Cmn
`FlowLayoutOverflow`	This class is deprecated. FlowLayout overflow is no longer maintained	Cmn
`FlowRowOverflow`	This class is deprecated. FlowLayout overflow is no longer maintained	Cmn
`MutableWindowInsets`	A `WindowInsets` whose values can change without changing the instance.	Cmn
`PaddingValues.Absolute`	Describes an absolute (RTL unaware) padding to be applied along the edges inside a box.	Cmn
`WindowInsetsSides`	`WindowInsetsSides` is used in `WindowInsets.only` to define which sides of the `WindowInsets` should apply.	Cmn

Objects

`Arrangement`	Used to specify the arrangement of the layout's children in layouts like `Row` or `Column` in the main axis direction (horizontal and vertical, respectively).	Cmn
`Arrangement.Absolute`		Cmn
`ComposeFoundationLayoutFlags`	This is a collection of flags which are used to guard against regressions in some of the "riskier" refactors or new feature support that is added to this module.	Cmn
`WindowInsets.Companion`		Cmn

Annotations

`ExperimentalLayoutApi`		Cmn
`LayoutScopeMarker`		Cmn

Enums

IntrinsicSize

Intrinsic size used in width or height which can refer to width or height.

Cmn

Top-level functions summary

`Unit`	`@Composable Box(modifier: Modifier)` A box with no content that can participate in layout, drawing, pointer input due to the `modifier` applied to it.	Cmn
`inline Unit`	`@Composable Box( modifier: Modifier, contentAlignment: Alignment, propagateMinConstraints: Boolean, content: @Composable BoxScope.() -> Unit )` A layout composable with `content`.	Cmn
`Unit`	`@Composable @UiComposable BoxWithConstraints( modifier: Modifier, contentAlignment: Alignment, propagateMinConstraints: Boolean, content: @Composable @UiComposable BoxWithConstraintsScope.() -> Unit )` A composable that defines its own content according to the available space, based on the incoming constraints or the current `LayoutDirection`.	Cmn
`inline Unit`	`@Composable Column( modifier: Modifier, verticalArrangement: Arrangement.Vertical, horizontalAlignment: Alignment.Horizontal, content: @Composable ColumnScope.() -> Unit )` A layout composable that places its children in a vertical sequence.	Cmn
`Unit`	`@Composable @ExperimentalLayoutApi ContextualFlowColumn( itemCount: Int, modifier: Modifier, verticalArrangement: Arrangement.Vertical, horizontalArrangement: Arrangement.Horizontal, itemHorizontalAlignment: Alignment.Horizontal, maxItemsInEachColumn: Int, maxLines: Int, overflow: ContextualFlowColumnOverflow, content: @Composable ContextualFlowColumnScope.(index: Int) -> Unit )` This function is deprecated. ContextualFlowLayouts are no longer maintained	Cmn
`Unit`	`@Composable @ExperimentalLayoutApi ContextualFlowRow( itemCount: Int, modifier: Modifier, horizontalArrangement: Arrangement.Horizontal, verticalArrangement: Arrangement.Vertical, itemVerticalAlignment: Alignment.Vertical, maxItemsInEachRow: Int, maxLines: Int, overflow: ContextualFlowRowOverflow, content: @Composable ContextualFlowRowScope.(index: Int) -> Unit )` This function is deprecated. ContextualFlowLayouts are no longer maintained	Cmn
`Unit`	`@Composable FlowColumn( modifier: Modifier, verticalArrangement: Arrangement.Vertical, horizontalArrangement: Arrangement.Horizontal, itemHorizontalAlignment: Alignment.Horizontal, maxItemsInEachColumn: Int, maxLines: Int, content: @Composable FlowColumnScope.() -> Unit )` `FlowColumn` is a layout that fills items from top to bottom, and when it runs out of space on the bottom, moves to the next "column" or "line" on the right or left based on ltr or rtl layouts, and then continues filling items from top to bottom.	Cmn
`Unit`	`@Composable @ExperimentalLayoutApi FlowColumn( modifier: Modifier, verticalArrangement: Arrangement.Vertical, horizontalArrangement: Arrangement.Horizontal, itemHorizontalAlignment: Alignment.Horizontal, maxItemsInEachColumn: Int, maxLines: Int, overflow: FlowColumnOverflow, content: @Composable FlowColumnScope.() -> Unit )` This function is deprecated. The overflow parameter has been deprecated	Cmn
`Unit`	`@Composable FlowRow( modifier: Modifier, horizontalArrangement: Arrangement.Horizontal, verticalArrangement: Arrangement.Vertical, itemVerticalAlignment: Alignment.Vertical, maxItemsInEachRow: Int, maxLines: Int, content: @Composable FlowRowScope.() -> Unit )` `FlowRow` is a layout that fills items from left to right (ltr) in LTR layouts or right to left (rtl) in RTL layouts and when it runs out of space, moves to the next "row" or "line" positioned on the bottom, and then continues filling items until the items run out.	Cmn
`Unit`	`@Composable @ExperimentalLayoutApi FlowRow( modifier: Modifier, horizontalArrangement: Arrangement.Horizontal, verticalArrangement: Arrangement.Vertical, itemVerticalAlignment: Alignment.Vertical, maxItemsInEachRow: Int, maxLines: Int, overflow: FlowRowOverflow, content: @Composable FlowRowScope.() -> Unit )` This function is deprecated. The overflow parameter has been deprecated	Cmn
`PaddingValues`	`PaddingValues(all: Dp)` Creates a padding of `all` dp along all 4 edges.	Cmn
`PaddingValues`	`PaddingValues(horizontal: Dp, vertical: Dp)` Creates a padding of `horizontal` dp along the left and right edges, and of `vertical` dp along the top and bottom edges.	Cmn
`PaddingValues`	`PaddingValues(start: Dp, top: Dp, end: Dp, bottom: Dp)` Creates a padding to be applied along the edges inside a box.	Cmn
`inline Unit`	`@Composable Row( modifier: Modifier, horizontalArrangement: Arrangement.Horizontal, verticalAlignment: Alignment.Vertical, content: @Composable RowScope.() -> Unit )` A layout composable that places its children in a horizontal sequence.	Cmn
`Unit`	`@Composable @NonRestartableComposable Spacer(modifier: Modifier)` Component that represents an empty space layout, whose size can be defined using `Modifier.width`, `Modifier.height` and `Modifier.size` modifiers.	Cmn
`WindowInsets`	`WindowInsets()` Create a `WindowInsets` with fixed dimensions of 0 on all sides.	Cmn
`WindowInsets`	`WindowInsets(left: Dp, top: Dp, right: Dp, bottom: Dp)` Create a `WindowInsets` with fixed dimensions, using `Dp` values.	Cmn
`WindowInsets`	`WindowInsets(left: Int, top: Int, right: Int, bottom: Int)` Create a `WindowInsets` with fixed dimensions.	Cmn

Extension functions summary

`Modifier`	`Modifier.absoluteOffset(offset: Density.() -> IntOffset)` Offset the content by `offset` px.	Cmn
`Modifier`	`Modifier.absoluteOffset(x: Dp, y: Dp)` Offset the content by (`x` dp, `y` dp).	Cmn
`Modifier`	`Modifier.absolutePadding(left: Dp, top: Dp, right: Dp, bottom: Dp)` Apply additional space along each edge of the content in `Dp`: `left`, `top`, `right` and `bottom`.	Cmn
`WindowInsets`	`WindowInsets.add(insets: WindowInsets)` Returns a `WindowInsets` that has values of this, added to the values of `insets`.	Cmn
`PaddingValues`	`@Composable WindowInsets.asPaddingValues()` Convert a `WindowInsets` to a `PaddingValues` and uses `LocalDensity` for DP to pixel conversion.	Cmn
`PaddingValues`	`WindowInsets.asPaddingValues(density: Density)` Convert a `WindowInsets` to a `PaddingValues` and uses `density` for DP to pixel conversion.	Cmn
`Modifier`	`Modifier.aspectRatio( ratio: @FloatRange(from = 0.0, fromInclusive = false) Float, matchHeightConstraintsFirst: Boolean )` Attempts to size the content to match a specified aspect ratio by trying to match one of the incoming constraints in the following order: `Constraints.maxWidth`, `Constraints.maxHeight`, `Constraints.minWidth`, `Constraints.minHeight` if `matchHeightConstraintsFirst` is `false` (which is the default), or `Constraints.maxHeight`, `Constraints.maxWidth`, `Constraints.minHeight`, `Constraints.minWidth` if `matchHeightConstraintsFirst` is `true`.	Cmn
`Dp`	`PaddingValues.calculateEndPadding(layoutDirection: LayoutDirection)` The padding to be applied along the end edge inside a box: along the right edge if the layout direction is LTR, or along the left edge for RTL.	Cmn
`Dp`	`PaddingValues.calculateStartPadding(layoutDirection: LayoutDirection)` The padding to be applied along the start edge inside a box: along the left edge if the layout direction is LTR, or along the right edge for RTL.	Cmn
`Modifier`	`Modifier.captionBarPadding()` Adds padding to accommodate the `caption bar` insets.	Cmn android
`Modifier`	`Modifier.consumeWindowInsets(insets: WindowInsets)` Consume insets that haven't been consumed yet by other insets Modifiers similar to `windowInsetsPadding` without adding any padding.	Cmn
`Modifier`	`Modifier.consumeWindowInsets(paddingValues: PaddingValues)` Consume `paddingValues` as insets as if the padding was added irrespective of insets.	Cmn
`Modifier`	`Modifier.defaultMinSize(minWidth: Dp, minHeight: Dp)` Constrain the size of the wrapped layout only when it would be otherwise unconstrained: the `minWidth` and `minHeight` constraints are only applied when the incoming corresponding constraint is `0`.	Cmn
`Modifier`	`Modifier.displayCutoutPadding()` Adds padding to accommodate the `display cutout`.	Cmn android
`WindowInsets`	`WindowInsets.exclude(insets: WindowInsets)` Returns the values in this `WindowInsets` that are not also in `insets`.	Cmn
`Modifier`	`Modifier.fillMaxHeight(fraction: @FloatRange(from = 0.0, to = 1.0) Float)` Have the content fill (possibly only partially) the `Constraints.maxHeight` of the incoming measurement constraints, by setting the `minimum height` and the `maximum height` to be equal to the `maximum height` multiplied by `fraction`.	Cmn
`Modifier`	`Modifier.fillMaxSize(fraction: @FloatRange(from = 0.0, to = 1.0) Float)` Have the content fill (possibly only partially) the `Constraints.maxWidth` and `Constraints.maxHeight` of the incoming measurement constraints, by setting the `minimum width` and the `maximum width` to be equal to the `maximum width` multiplied by `fraction`, as well as the `minimum height` and the `maximum height` to be equal to the `maximum height` multiplied by `fraction`.	Cmn
`Modifier`	`Modifier.fillMaxWidth(fraction: @FloatRange(from = 0.0, to = 1.0) Float)` Have the content fill (possibly only partially) the `Constraints.maxWidth` of the incoming measurement constraints, by setting the `minimum width` and the `maximum width` to be equal to the `maximum width` multiplied by `fraction`.	Cmn
`Modifier`	`Modifier.fitInside(rulers: RectRulers)` Fits the contents within `rulers`.	Cmn
`Modifier`	`Modifier.fitOutside(rulers: RectRulers)` If one of the `Ruler`s in `rulers` has a value within the bounds of the Layout, this sizes the content to that `Ruler` and the edge.	Cmn
`Modifier`	`Modifier.height(height: Dp)` Declare the preferred height of the content to be exactly `height`dp.	Cmn
`Modifier`	`Modifier.height(intrinsicSize: IntrinsicSize)` Declare the preferred height of the content to be the same as the min or max intrinsic height of the content.	Cmn
`Modifier`	`Modifier.heightIn(min: Dp, max: Dp)` Constrain the height of the content to be between `min`dp and `max`dp as permitted by the incoming measurement `Constraints`.	Cmn
`Modifier`	`@ExperimentalLayoutApi Modifier.imeNestedScroll()` Controls the soft keyboard as a nested scrolling on Android `R` and later.	android
`Modifier`	`Modifier.imePadding()` Adds padding to accommodate the `ime` insets.	Cmn android
`Modifier`	`Modifier.mandatorySystemGesturesPadding()` Adds padding to accommodate the `mandatory system gestures` insets.	Cmn android
`Modifier`	`Modifier.navigationBarsPadding()` Adds padding to accommodate the `navigation bars` insets.	Cmn android
`Modifier`	`Modifier.offset(offset: Density.() -> IntOffset)` Offset the content by `offset` px.	Cmn
`Modifier`	`Modifier.offset(x: Dp, y: Dp)` Offset the content by (`x` dp, `y` dp).	Cmn
`Modifier`	`Modifier.onConsumedWindowInsetsChanged( block: (consumedWindowInsets: WindowInsets) -> Unit )` Calls `block` with the `WindowInsets` that have been consumed, either by `consumeWindowInsets` or one of the padding Modifiers, such as `imePadding`.	Cmn
`WindowInsets`	`WindowInsets.only(sides: WindowInsetsSides)` Returns a `WindowInsets` that eliminates all dimensions except the ones that are enabled.	Cmn
`Modifier`	`Modifier.padding(all: Dp)` Apply `all` dp of additional space along each edge of the content, left, top, right and bottom.	Cmn
`Modifier`	`Modifier.padding(paddingValues: PaddingValues)` Apply `PaddingValues` to the component as additional space along each edge of the content's left, top, right and bottom.	Cmn
`Modifier`	`Modifier.padding(horizontal: Dp, vertical: Dp)` Apply `horizontal` dp space along the left and right edges of the content, and `vertical` dp space along the top and bottom edges.	Cmn
`Modifier`	`Modifier.padding(start: Dp, top: Dp, end: Dp, bottom: Dp)` Apply additional space along each edge of the content in `Dp`: `start`, `top`, `end` and `bottom`.	Cmn
`Modifier`	`Modifier.paddingFrom(alignmentLine: AlignmentLine, before: Dp, after: Dp)` A `Modifier` that can add padding to position the content according to specified distances from its bounds to an `alignment line`.	Cmn
`Modifier`	`Modifier.paddingFrom( alignmentLine: AlignmentLine, before: TextUnit, after: TextUnit )` A `Modifier` that can add padding to position the content according to specified distances from its bounds to an `alignment line`.	Cmn
`Modifier`	`Modifier.paddingFromBaseline(top: Dp, bottom: Dp)` A `Modifier` that positions the content in a layout such that the distance from the top of the layout to the `baseline of the first line of text in the content` is `top`, and the distance from the `baseline of the last line of text in the content` to the bottom of the layout is `bottom`.	Cmn
`Modifier`	`Modifier.paddingFromBaseline(top: TextUnit, bottom: TextUnit)` A `Modifier` that positions the content in a layout such that the distance from the top of the layout to the `baseline of the first line of text in the content` is `top`, and the distance from the `baseline of the last line of text in the content` to the bottom of the layout is `bottom`.	Cmn
`Modifier`	`Modifier.recalculateWindowInsets()` This recalculates the `WindowInsets` based on the size and position.	Cmn
`Modifier`	`Modifier.requiredHeight(height: Dp)` Declare the height of the content to be exactly `height`dp.	Cmn
`Modifier`	`Modifier.requiredHeight(intrinsicSize: IntrinsicSize)` Declare the height of the content to be exactly the same as the min or max intrinsic height of the content.	Cmn
`Modifier`	`Modifier.requiredHeightIn(min: Dp, max: Dp)` Constrain the height of the content to be between `min`dp and `max`dp.	Cmn
`Modifier`	`Modifier.requiredSize(size: Dp)` Declare the size of the content to be exactly `size`dp width and height.	Cmn
`Modifier`	`Modifier.requiredSize(size: DpSize)` Declare the size of the content to be exactly `size`.	Cmn
`Modifier`	`Modifier.requiredSize(width: Dp, height: Dp)` Declare the size of the content to be exactly `width`dp and `height`dp.	Cmn
`Modifier`	`Modifier.requiredSizeIn( minWidth: Dp, minHeight: Dp, maxWidth: Dp, maxHeight: Dp )` Constrain the width of the content to be between `minWidth`dp and `maxWidth`dp, and the height of the content to be between `minHeight`dp and `maxHeight`dp.	Cmn
`Modifier`	`Modifier.requiredWidth(intrinsicSize: IntrinsicSize)` Declare the width of the content to be exactly the same as the min or max intrinsic width of the content.	Cmn
`Modifier`	`Modifier.requiredWidth(width: Dp)` Declare the width of the content to be exactly `width`dp.	Cmn
`Modifier`	`Modifier.requiredWidthIn(min: Dp, max: Dp)` Constrain the width of the content to be between `min`dp and `max`dp.	Cmn
`Modifier`	`Modifier.safeContentPadding()` Adds padding to accommodate the `safe content` insets.	Cmn android
`Modifier`	`Modifier.safeDrawingPadding()` Adds padding to accommodate the `safe drawing` insets.	Cmn android
`Modifier`	`Modifier.safeGesturesPadding()` Adds padding to accommodate the `safe gestures` insets.	Cmn android
`Modifier`	`Modifier.size(size: Dp)` Declare the preferred size of the content to be exactly `size`dp square.	Cmn
`Modifier`	`Modifier.size(size: DpSize)` Declare the preferred size of the content to be exactly `size`.	Cmn
`Modifier`	`Modifier.size(width: Dp, height: Dp)` Declare the preferred size of the content to be exactly `width`dp by `height`dp.	Cmn
`Modifier`	`Modifier.sizeIn(minWidth: Dp, minHeight: Dp, maxWidth: Dp, maxHeight: Dp)` Constrain the width of the content to be between `minWidth`dp and `maxWidth`dp and the height of the content to be between `minHeight`dp and `maxHeight`dp as permitted by the incoming measurement `Constraints`.	Cmn
`Modifier`	`Modifier.statusBarsPadding()` Adds padding to accommodate the `status bars` insets.	Cmn android
`Modifier`	`Modifier.systemBarsPadding()` Adds padding to accommodate the `system bars` insets.	Cmn android
`Modifier`	`Modifier.systemGesturesPadding()` Adds padding to accommodate the `system gestures` insets.	Cmn android
`WindowInsets`	`WindowInsets.union(insets: WindowInsets)` Returns a `WindowInsets` that has the maximum values of this `WindowInsets` and `insets`.	Cmn
`Modifier`	`Modifier.waterfallPadding()` Adds padding to accommodate the `waterfall` insets.	Cmn android
`Modifier`	`Modifier.width(intrinsicSize: IntrinsicSize)` Declare the preferred width of the content to be the same as the min or max intrinsic width of the content.	Cmn
`Modifier`	`Modifier.width(width: Dp)` Declare the preferred width of the content to be exactly `width`dp.	Cmn
`Modifier`	`Modifier.widthIn(min: Dp, max: Dp)` Constrain the width of the content to be between `min`dp and `max`dp as permitted by the incoming measurement `Constraints`.	Cmn
`Modifier`	`Modifier.windowInsetsBottomHeight(insets: WindowInsets)` Sets the height to that of `insets` at the `bottom` of the screen.	Cmn
`Modifier`	`Modifier.windowInsetsEndWidth(insets: WindowInsets)` Sets the width to that of `insets` at the `end` of the screen, using either `left` or `right`, depending on the `LayoutDirection`.	Cmn
`Modifier`	`Modifier.windowInsetsPadding(insets: WindowInsets)` Adds padding so that the content doesn't enter `insets` space.	Cmn
`Modifier`	`Modifier.windowInsetsStartWidth(insets: WindowInsets)` Sets the width to that of `insets` at the `start` of the screen, using either `left` or `right`, depending on the `LayoutDirection`.	Cmn
`Modifier`	`Modifier.windowInsetsTopHeight(insets: WindowInsets)` Sets the height to that of `insets` at the `top` of the screen.	Cmn
`Modifier`	`Modifier.wrapContentHeight( align: Alignment.Vertical, unbounded: Boolean )` Allow the content to measure at its desired height without regard for the incoming measurement `minimum height constraint`, and, if `unbounded` is true, also without regard for the incoming measurement `maximum height constraint`.	Cmn
`Modifier`	`Modifier.wrapContentSize(align: Alignment, unbounded: Boolean)` Allow the content to measure at its desired size without regard for the incoming measurement `minimum width` or `minimum height` constraints, and, if `unbounded` is true, also without regard for the incoming maximum constraints.	Cmn
`Modifier`	`Modifier.wrapContentWidth( align: Alignment.Horizontal, unbounded: Boolean )` Allow the content to measure at its desired width without regard for the incoming measurement `minimum width constraint`, and, if `unbounded` is true, also without regard for the incoming measurement `maximum width constraint`.	Cmn

Extension properties summary

`Boolean`	`@ExperimentalLayoutApi WindowInsets.Companion.areNavigationBarsVisible` `true` when the `navigationBars` are being displayed, irrespective of whether they intersects with the Window.	android
`Boolean`	`@ExperimentalLayoutApi WindowInsets.Companion.areStatusBarsVisible` `true` when the `statusBars` are being displayed, irrespective of whether they intersects with the Window.	android
`Boolean`	`@ExperimentalLayoutApi WindowInsets.Companion.areSystemBarsVisible` `true` when the `systemBars` are being displayed, irrespective of whether they intersects with the Window.	android
`WindowInsets`	`WindowInsets.Companion.captionBar` An insets type representing the window of a caption bar.	Cmn android
`WindowInsets`	`@ExperimentalLayoutApi WindowInsets.Companion.captionBarIgnoringVisibility` The insets that the `WindowInsetsCompat.Type.captionBar` will consume if shown.	android
`Boolean`	`AbstractComposeView.consumeWindowInsets` Indicates whether access to `WindowInsets` within the `content` should consume the Android `android.view.WindowInsets`.	android
`WindowInsets`	`WindowInsets.Companion.displayCutout` This `WindowInsets` represents the area with the display cutout (e.g. for camera).	Cmn android
`WindowInsets`	`WindowInsets.Companion.ime` An insets type representing the window of the software keyboard.	Cmn android
`WindowInsets`	`@ExperimentalLayoutApi WindowInsets.Companion.imeAnimationSource` The `WindowInsets` for the IME before the IME started animating in.	android
`WindowInsets`	`@ExperimentalLayoutApi WindowInsets.Companion.imeAnimationTarget` The `WindowInsets` for the IME when the animation completes, if it is allowed to complete successfully.	android
`Boolean`	`@ExperimentalLayoutApi WindowInsets.Companion.isCaptionBarVisible` `true` when the `caption bar` is being displayed, irrespective of whether it intersects with the Window.	android
`Boolean`	`@ExperimentalLayoutApi WindowInsets.Companion.isImeVisible` `true` when the `soft keyboard` is being displayed, irrespective of whether it intersects with the Window.	android
`Boolean`	`@ExperimentalLayoutApi WindowInsets.Companion.isTappableElementVisible` `true` when the `tappableElement` is being displayed, irrespective of whether they intersects with the Window.	android
`WindowInsets`	`WindowInsets.Companion.mandatorySystemGestures` These insets represent the space where system gestures have priority over application gestures.	Cmn android
`WindowInsets`	`WindowInsets.Companion.navigationBars` These insets represent where system UI places navigation bars.	Cmn android
`WindowInsets`	`@ExperimentalLayoutApi WindowInsets.Companion.navigationBarsIgnoringVisibility` The insets that `WindowInsetsCompat.Type.navigationBars` will consume if shown.	android
`WindowInsets`	`WindowInsets.Companion.safeContent` The insets that include all areas that may be drawn over or have gesture confusion, including everything in `safeDrawing` and `safeGestures`.	Cmn android
`WindowInsets`	`WindowInsets.Companion.safeDrawing` The insets that include areas where content may be covered by other drawn content.	Cmn android
`WindowInsets`	`WindowInsets.Companion.safeGestures` The insets that include areas where gestures may be confused with other input, including `systemGestures`, `mandatorySystemGestures`, `waterfall`, and `tappableElement`.	Cmn android
`WindowInsets`	`WindowInsets.Companion.statusBars` These insets represent status bar.	Cmn android
`WindowInsets`	`@ExperimentalLayoutApi WindowInsets.Companion.statusBarsIgnoringVisibility` The insets that `WindowInsetsCompat.Type.statusBars` will consume if shown.	android
`WindowInsets`	`WindowInsets.Companion.systemBars` These insets represent all system bars.	Cmn android
`WindowInsets`	`@ExperimentalLayoutApi WindowInsets.Companion.systemBarsIgnoringVisibility` The insets that `WindowInsetsCompat.Type.systemBars` will consume if shown.	android
`WindowInsets`	`WindowInsets.Companion.systemGestures` The `systemGestures` insets represent the area of a window where system gestures have priority and may consume some or all touch input, e.g. due to the system bar occupying it, or it being reserved for touch-only gestures.	Cmn android
`WindowInsets`	`WindowInsets.Companion.tappableElement` Returns the tappable element insets.	Cmn android
`WindowInsets`	`@ExperimentalLayoutApi WindowInsets.Companion.tappableElementIgnoringVisibility` The insets that `WindowInsetsCompat.Type.tappableElement` will consume if active.	android
`WindowInsets`	`WindowInsets.Companion.waterfall` The insets for the curved areas in a waterfall display.	Cmn android

Top-level functions

Box

Cmn

Artifact: androidx.compose.foundation:foundation-layout

View Source

Added in 1.0.0

@Composable
fun Box(modifier: Modifier): Unit

A box with no content that can participate in layout, drawing, pointer input due to the modifier applied to it.

Example usage:

import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.layout.size
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.unit.dp

Box {
    Box(Modifier.fillMaxSize().background(Color.Cyan))
    Box(
        Modifier.matchParentSize().padding(top = 20.dp, bottom = 20.dp).background(Color.Yellow)
    )
    Box(Modifier.matchParentSize().padding(40.dp).background(Color.Magenta))
    Box(Modifier.align(Alignment.Center).size(300.dp, 300.dp).background(Color.Green))
    Box(Modifier.align(Alignment.TopStart).size(150.dp, 150.dp).background(Color.Red))
    Box(Modifier.align(Alignment.BottomEnd).size(150.dp, 150.dp).background(Color.Blue))
}

Parameters
`modifier: Modifier`	The modifier to be applied to the layout.

Box

Cmn

Artifact: androidx.compose.foundation:foundation-layout

View Source

Added in 1.0.0

@Composable
inline fun Box(
    modifier: Modifier = Modifier,
    contentAlignment: Alignment = Alignment.TopStart,
    propagateMinConstraints: Boolean = false,
    content: @Composable BoxScope.() -> Unit
): Unit

A layout composable with content. The Box will size itself to fit the content, subject to the incoming constraints. When children are smaller than the parent, by default they will be positioned inside the Box according to the contentAlignment. For individually specifying the alignments of the children layouts, use the BoxScope.align modifier. By default, the content will be measured without the Box's incoming min constraints, unless propagateMinConstraints is true. As an example, setting propagateMinConstraints to true can be useful when the Box has content on which modifiers cannot be specified directly and setting a min size on the content of the Box is needed. If propagateMinConstraints is set to true, the min size set on the Box will also be applied to the content, whereas otherwise the min size will only apply to the Box. When the content has more than one layout child the layout children will be stacked one on top of the other (positioned as explained above) in the composition order.

Example usage:

import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.layout.size
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.unit.dp

Box {
    Box(Modifier.fillMaxSize().background(Color.Cyan))
    Box(
        Modifier.matchParentSize().padding(top = 20.dp, bottom = 20.dp).background(Color.Yellow)
    )
    Box(Modifier.matchParentSize().padding(40.dp).background(Color.Magenta))
    Box(Modifier.align(Alignment.Center).size(300.dp, 300.dp).background(Color.Green))
    Box(Modifier.align(Alignment.TopStart).size(150.dp, 150.dp).background(Color.Red))
    Box(Modifier.align(Alignment.BottomEnd).size(150.dp, 150.dp).background(Color.Blue))
}

Parameters
`modifier: Modifier = Modifier`	The modifier to be applied to the layout.
`contentAlignment: Alignment = Alignment.TopStart`	The default alignment inside the Box.
`propagateMinConstraints: Boolean = false`	Whether the incoming min constraints should be passed to content.
`content: @Composable BoxScope.() -> Unit`	The content of the `Box`.

BoxWithConstraints

Cmn

Artifact: androidx.compose.foundation:foundation-layout

View Source

Added in 1.0.0

@Composable
@UiComposable
fun BoxWithConstraints(
    modifier: Modifier = Modifier,
    contentAlignment: Alignment = Alignment.TopStart,
    propagateMinConstraints: Boolean = false,
    content: @Composable @UiComposable BoxWithConstraintsScope.() -> Unit
): Unit

A composable that defines its own content according to the available space, based on the incoming constraints or the current LayoutDirection. Example usage:

import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.BoxWithConstraints
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.size
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.unit.dp

BoxWithConstraints {
    val rectangleHeight = 100.dp
    if (maxHeight < rectangleHeight * 2) {
        Box(Modifier.size(50.dp, rectangleHeight).background(Color.Blue))
    } else {
        Column {
            Box(Modifier.size(50.dp, rectangleHeight).background(Color.Blue))
            Box(Modifier.size(50.dp, rectangleHeight).background(Color.Gray))
        }
    }
}

The composable will compose the given children, and will position the resulting layout elements in a parent layout which behaves similar to a Box. The layout will size itself to fit the content, subject to the incoming constraints. When children are smaller than the parent, by default they will be positioned inside the layout according to the contentAlignment. For individually specifying the alignments of the children layouts, use the BoxScope.align modifier. By default, the content will be measured without the Box's incoming min constraints, unless propagateMinConstraints is true. As an example, setting propagateMinConstraints to true can be useful when the BoxWithConstraints has content on which modifiers cannot be specified directly and setting a min size on the content of the BoxWithConstraints is needed. If propagateMinConstraints is set to true, the min size set on the BoxWithConstraints will also be applied to the content, whereas otherwise the min size will only apply to the BoxWithConstraints. When the content has more than one layout child the layout children will be stacked one on top of the other (positioned as explained above) in the composition order.

Parameters
`modifier: Modifier = Modifier`	Modifier to be applied to the layout.
`contentAlignment: Alignment = Alignment.TopStart`	The default alignment inside the `BoxWithConstraints`.
`propagateMinConstraints: Boolean = false`	Whether the incoming min constraints should be passed to content.
`content: @Composable @UiComposable BoxWithConstraintsScope.() -> Unit`	The content of the `BoxWithConstraints`.

Column

Cmn

Artifact: androidx.compose.foundation:foundation-layout

View Source

Added in 1.0.0

@Composable
inline fun Column(
    modifier: Modifier = Modifier,
    verticalArrangement: Arrangement.Vertical = Arrangement.Top,
    horizontalAlignment: Alignment.Horizontal = Alignment.Start,
    content: @Composable ColumnScope.() -> Unit
): Unit

A layout composable that places its children in a vertical sequence. For a layout composable that places its children in a horizontal sequence, see Row. Note that by default items do not scroll; see Modifier.verticalScroll to add this behavior. For a vertically scrollable list that only composes and lays out the currently visible items see LazyColumn.

The Column layout is able to assign children heights according to their weights provided using the ColumnScope.weight modifier. If a child is not provided a weight, it will be asked for its preferred height before the sizes of the children with weights are calculated proportionally to their weight based on the remaining available space. Note that if the Column is vertically scrollable or part of a vertically scrollable container, any provided weights will be disregarded as the remaining available space will be infinite.

When none of its children have weights, a Column will be as small as possible to fit its children one on top of the other. In order to change the height of the Column, use the Modifier.height modifiers; e.g. to make it fill the available height Modifier.fillMaxHeight can be used. If at least one child of a Column has a weight, the Column will fill the available height, so there is no need for Modifier.fillMaxHeight. However, if Column's size should be limited, the Modifier.height or Modifier.size layout modifiers should be applied.

When the size of the Column is larger than the sum of its children sizes, a verticalArrangement can be specified to define the positioning of the children inside the Column. See Arrangement for available positioning behaviors; a custom arrangement can also be defined using the constructor of Arrangement. Below is an illustration of different vertical arrangements:

Column
arrangements

Example usage:

import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.size
import androidx.compose.foundation.layout.width
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.unit.dp

Column {
    // The child with no weight will have the specified size.
    Box(Modifier.size(40.dp, 80.dp).background(Color.Magenta))
    // Has weight, the child will occupy half of the remaining height.
    Box(Modifier.width(40.dp).weight(1f).background(Color.Yellow))
    // Has weight and does not fill, the child will occupy at most half of the remaining height.
    // Therefore it will occupy 80.dp (its preferred height) if the assigned height is larger.
    Box(Modifier.size(40.dp, 80.dp).weight(1f, fill = false).background(Color.Green))
}

Parameters
`modifier: Modifier = Modifier`	The modifier to be applied to the Column.
`verticalArrangement: Arrangement.Vertical = Arrangement.Top`	The vertical arrangement of the layout's children.
`horizontalAlignment: Alignment.Horizontal = Alignment.Start`	The horizontal alignment of the layout's children.
`content: @Composable ColumnScope.() -> Unit`	The content of the Column

See also
`Row`
`LazyColumn`

ContextualFlowColumn

Cmn

Artifact: androidx.compose.foundation:foundation-layout

View Source

Added in 1.8.0

Deprecated in 1.8.0

@Composable
@ExperimentalLayoutApi
fun ContextualFlowColumn(
    itemCount: Int,
    modifier: Modifier = Modifier,
    verticalArrangement: Arrangement.Vertical = Arrangement.Top,
    horizontalArrangement: Arrangement.Horizontal = Arrangement.Start,
    itemHorizontalAlignment: Alignment.Horizontal = Alignment.Start,
    maxItemsInEachColumn: Int = Int.MAX_VALUE,
    maxLines: Int = Int.MAX_VALUE,
    overflow: ContextualFlowColumnOverflow = ContextualFlowColumnOverflow.Clip,
    content: @Composable ContextualFlowColumnScope.(index: Int) -> Unit
): Unit

ContextualFlowColumn is a specialized version of the FlowColumn layout. It is designed to enable users to make contextual decisions during the construction of FlowColumn layouts.

This component is particularly advantageous when dealing with a large collection of items, allowing for efficient management and display. Unlike traditional FlowColumn that composes all items regardless of their visibility, ContextualFlowColumn smartly limits composition to only those items that are visible within its constraints, such as maxLines or maxWidth. This approach ensures optimal performance and resource utilization by composing fewer items than the total number available, based on the current context and display parameters.

While maintaining the core functionality of the standard FlowColumn, ContextualFlowColumn operates on an index-based system and composes items sequentially, one after another. This approach provides a perfect way to make contextual decisions and can be an easier way to handle problems such as dynamic see more buttons such as (N+ buttons).

Example:

import androidx.compose.foundation.background
import androidx.compose.foundation.horizontalScroll
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.ContextualFlowColumn
import androidx.compose.foundation.layout.ContextualFlowColumnOverflow
import androidx.compose.foundation.layout.ContextualFlowColumnOverflowScope
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.layout.width
import androidx.compose.foundation.layout.wrapContentHeight
import androidx.compose.foundation.rememberScrollState
import androidx.compose.material.Text
import androidx.compose.runtime.Composable
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.text.font.FontWeight
import androidx.compose.ui.unit.dp
import androidx.compose.ui.unit.sp

val totalCount = 300
var maxLines by remember { mutableStateOf(2) }

Text(
    modifier = Modifier.fillMaxWidth(1f).padding(20.dp),
    text =
        "ContextualFlowColumn (based on Subcompose)" +
            " is great for Large Items & +N dynamic labels",
    fontWeight = FontWeight.Bold,
)

val moreOrCollapseIndicator =
    @Composable { scope: ContextualFlowColumnOverflowScope ->
        val remainingItems = totalCount - scope.shownItemCount
        DynamicSeeMore(isHorizontal = true, remainingItems = remainingItems) {
            if (remainingItems == 0) {
                maxLines = 2
            } else {
                maxLines += 2
            }
        }
    }
ContextualFlowColumn(
    modifier =
        Modifier.fillMaxWidth(1f)
            .horizontalScroll(rememberScrollState())
            .padding(20.dp)
            .height(200.dp)
            .wrapContentHeight(align = Alignment.Top),
    verticalArrangement = Arrangement.spacedBy(10.dp),
    horizontalArrangement = Arrangement.spacedBy(20.dp),
    maxLines = maxLines,
    overflow =
        ContextualFlowColumnOverflow.expandOrCollapseIndicator(
            minColumnsToShowCollapse = 4,
            expandIndicator = moreOrCollapseIndicator,
            collapseIndicator = moreOrCollapseIndicator,
        ),
    itemCount = totalCount,
) { index ->
    Box(
        modifier =
            Modifier.align(Alignment.CenterHorizontally)
                .height(50.dp)
                .width(50.dp)
                .background(Color.Green)
    ) {
        Text(
            text = index.toString(),
            fontSize = 18.sp,
            modifier = Modifier.padding(3.dp).align(Alignment.Center),
        )
    }
}

Parameters
`itemCount: Int`	The total number of item composable
`modifier: Modifier = Modifier`	The modifier to be applied to the Row.
`verticalArrangement: Arrangement.Vertical = Arrangement.Top`	The vertical arrangement of the layout's virtual column.
`horizontalArrangement: Arrangement.Horizontal = Arrangement.Start`	The horizontal arrangement of the layout's children.
`itemHorizontalAlignment: Alignment.Horizontal = Alignment.Start`	The cross axis/horizontal alignment of an item in the column.
`maxItemsInEachColumn: Int = Int.MAX_VALUE`	The maximum number of items per column
`maxLines: Int = Int.MAX_VALUE`	The maximum number of columns
`overflow: ContextualFlowColumnOverflow = ContextualFlowColumnOverflow.Clip`	The straoadtegy to handle overflowing items
`content: @Composable ContextualFlowColumnScope.(index: Int) -> Unit`	The indexed-based content of `ContextualFlowColumnScope`

See also
`FlowColumn`
`ContextualFlowRow`

ContextualFlowRow

Cmn

Artifact: androidx.compose.foundation:foundation-layout

View Source

Added in 1.8.0

Deprecated in 1.8.0

@Composable
@ExperimentalLayoutApi
fun ContextualFlowRow(
    itemCount: Int,
    modifier: Modifier = Modifier,
    horizontalArrangement: Arrangement.Horizontal = Arrangement.Start,
    verticalArrangement: Arrangement.Vertical = Arrangement.Top,
    itemVerticalAlignment: Alignment.Vertical = Alignment.Top,
    maxItemsInEachRow: Int = Int.MAX_VALUE,
    maxLines: Int = Int.MAX_VALUE,
    overflow: ContextualFlowRowOverflow = ContextualFlowRowOverflow.Clip,
    content: @Composable ContextualFlowRowScope.(index: Int) -> Unit
): Unit

ContextualFlowRow is a specialized version of the FlowRow layout. It is designed to enable users to make contextual decisions during the construction of FlowRow layouts.

This component is particularly advantageous when dealing with a large collection of items, allowing for efficient management and display. Unlike traditional FlowRow that composes all items regardless of their visibility, ContextualFlowRow smartly limits composition to only those items that are visible within its constraints, such as maxLines or maxHeight. This approach ensures optimal performance and resource utilization by composing fewer items than the total number available, based on the current context and display parameters.

While maintaining the core functionality of the standard FlowRow, ContextualFlowRow operates on an index-based system and composes items sequentially, one after another. This approach provides a perfect way to make contextual decisions and can be an easier way to handle problems such as dynamic see more buttons such as (N+ buttons).

Example:

import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.ContextualFlowRow
import androidx.compose.foundation.layout.ContextualFlowRowOverflow
import androidx.compose.foundation.layout.ContextualFlowRowOverflowScope
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.layout.width
import androidx.compose.foundation.layout.wrapContentHeight
import androidx.compose.material.Text
import androidx.compose.runtime.Composable
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.text.font.FontWeight
import androidx.compose.ui.unit.dp
import androidx.compose.ui.unit.sp

val totalCount = 300
var maxLines by remember { mutableStateOf(2) }

Text(
    modifier =
        Modifier.fillMaxWidth(1f).padding(20.dp).wrapContentHeight(align = Alignment.Top),
    text =
        "ContextualFlowRow (based on Subcompose)" +
            " is great for Large Items & +N dynamic labels",
    fontWeight = FontWeight.Bold,
)
val moreOrCollapseIndicator =
    @Composable { scope: ContextualFlowRowOverflowScope ->
        val remainingItems = totalCount - scope.shownItemCount
        DynamicSeeMore(isHorizontal = true, remainingItems = remainingItems) {
            if (remainingItems == 0) {
                maxLines = 2
            } else {
                maxLines += 5
            }
        }
    }
ContextualFlowRow(
    modifier =
        Modifier.fillMaxWidth(1f).padding(20.dp).wrapContentHeight(align = Alignment.Top),
    horizontalArrangement = Arrangement.spacedBy(10.dp),
    verticalArrangement = Arrangement.spacedBy(20.dp),
    maxLines = maxLines,
    overflow =
        ContextualFlowRowOverflow.expandOrCollapseIndicator(
            minRowsToShowCollapse = 4,
            expandIndicator = moreOrCollapseIndicator,
            collapseIndicator = moreOrCollapseIndicator,
        ),
    itemCount = totalCount,
) {
    Box(
        Modifier.align(Alignment.CenterVertically)
            .width(50.dp)
            .height(50.dp)
            .background(Color.Green)
    ) {
        Text(
            text = it.toString(),
            fontSize = 18.sp,
            modifier = Modifier.padding(3.dp).align(Alignment.Center),
        )
    }
}

Parameters
`itemCount: Int`	The total number of item composable
`modifier: Modifier = Modifier`	The modifier to be applied to the Row.
`horizontalArrangement: Arrangement.Horizontal = Arrangement.Start`	The horizontal arrangement of the layout's children.
`verticalArrangement: Arrangement.Vertical = Arrangement.Top`	The vertical arrangement of the layout's virtual rows.
`itemVerticalAlignment: Alignment.Vertical = Alignment.Top`	The cross axis/vertical alignment of an item in the column.
`maxItemsInEachRow: Int = Int.MAX_VALUE`	The maximum number of items per row
`maxLines: Int = Int.MAX_VALUE`	The maximum number of rows
`overflow: ContextualFlowRowOverflow = ContextualFlowRowOverflow.Clip`	The strategy to handle overflowing items
`content: @Composable ContextualFlowRowScope.(index: Int) -> Unit`	The indexed-based content of `ContextualFlowRowScope`

See also
`FlowRow`
`ContextualFlowColumn`

FlowColumn

Cmn

Artifact: androidx.compose.foundation:foundation-layout

View Source

Added in 1.8.0

@Composable
fun FlowColumn(
    modifier: Modifier = Modifier,
    verticalArrangement: Arrangement.Vertical = Arrangement.Top,
    horizontalArrangement: Arrangement.Horizontal = Arrangement.Start,
    itemHorizontalAlignment: Alignment.Horizontal = Alignment.Start,
    maxItemsInEachColumn: Int = Int.MAX_VALUE,
    maxLines: Int = Int.MAX_VALUE,
    content: @Composable FlowColumnScope.() -> Unit
): Unit

FlowColumn is a layout that fills items from top to bottom, and when it runs out of space on the bottom, moves to the next "column" or "line" on the right or left based on ltr or rtl layouts, and then continues filling items from top to bottom.

It supports ltr in LTR layouts, by placing the first column to the left, and then moving to the right It supports rtl in RTL layouts, by placing the first column to the right, and then moving to the left

Example:

import androidx.compose.foundation.BorderStroke
import androidx.compose.foundation.background
import androidx.compose.foundation.border
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.FlowColumn
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.layout.width
import androidx.compose.foundation.layout.wrapContentHeight
import androidx.compose.material.Text
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.text.font.FontWeight
import androidx.compose.ui.unit.dp
import androidx.compose.ui.unit.sp

Text(
    modifier =
        Modifier.fillMaxWidth(1f).padding(20.dp).wrapContentHeight(align = Alignment.Top),
    text = "FlowColumn with weights",
    fontWeight = FontWeight.Bold,
)

FlowColumn(
    Modifier.padding(20.dp)
        .fillMaxWidth()
        .padding(20.dp)
        .wrapContentHeight(align = Alignment.Top)
        .height(200.dp)
        .border(BorderStroke(2.dp, Color.Gray)),
    horizontalArrangement = Arrangement.spacedBy(10.dp),
    verticalArrangement = Arrangement.spacedBy(20.dp),
    maxItemsInEachColumn = 3,
) {
    repeat(17) { index ->
        Box(
            Modifier.align(Alignment.CenterHorizontally)
                .width(50.dp)
                .height(50.dp)
                .weight(1f, true)
                .background(color = Color.Green)
        ) {
            Text(text = index.toString(), fontSize = 18.sp, modifier = Modifier.padding(3.dp))
        }
    }
}

When a Modifier ColumnScope.weight is provided, it scales the item based on the number items that fall on the column it was placed in.

Parameters
`modifier: Modifier = Modifier`	The modifier to be applied to the Row.
`verticalArrangement: Arrangement.Vertical = Arrangement.Top`	The vertical arrangement of the layout's children.
`horizontalArrangement: Arrangement.Horizontal = Arrangement.Start`	The horizontal arrangement of the layout's virtual columns
`itemHorizontalAlignment: Alignment.Horizontal = Alignment.Start`	The cross axis/horizontal alignment of an item in the column.
`maxItemsInEachColumn: Int = Int.MAX_VALUE`	The maximum number of items per column
`maxLines: Int = Int.MAX_VALUE`	The max number of rows
`content: @Composable FlowColumnScope.() -> Unit`	The content as a `ColumnScope`

See also
`FlowRow`
`Column`

FlowColumn

Cmn

Artifact: androidx.compose.foundation:foundation-layout

View Source

Added in 1.8.0

Deprecated in 1.8.0

@Composable
@ExperimentalLayoutApi
fun FlowColumn(
    modifier: Modifier = Modifier,
    verticalArrangement: Arrangement.Vertical = Arrangement.Top,
    horizontalArrangement: Arrangement.Horizontal = Arrangement.Start,
    itemHorizontalAlignment: Alignment.Horizontal = Alignment.Start,
    maxItemsInEachColumn: Int = Int.MAX_VALUE,
    maxLines: Int = Int.MAX_VALUE,
    overflow: FlowColumnOverflow = FlowColumnOverflow.Clip,
    content: @Composable FlowColumnScope.() -> Unit
): Unit

Example:

import androidx.compose.foundation.BorderStroke
import androidx.compose.foundation.background
import androidx.compose.foundation.border
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.FlowColumn
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.layout.width
import androidx.compose.foundation.layout.wrapContentHeight
import androidx.compose.material.Text
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.text.font.FontWeight
import androidx.compose.ui.unit.dp
import androidx.compose.ui.unit.sp

Text(
    modifier =
        Modifier.fillMaxWidth(1f).padding(20.dp).wrapContentHeight(align = Alignment.Top),
    text = "FlowColumn with weights",
    fontWeight = FontWeight.Bold,
)

FlowColumn(
    Modifier.padding(20.dp)
        .fillMaxWidth()
        .padding(20.dp)
        .wrapContentHeight(align = Alignment.Top)
        .height(200.dp)
        .border(BorderStroke(2.dp, Color.Gray)),
    horizontalArrangement = Arrangement.spacedBy(10.dp),
    verticalArrangement = Arrangement.spacedBy(20.dp),
    maxItemsInEachColumn = 3,
) {
    repeat(17) { index ->
        Box(
            Modifier.align(Alignment.CenterHorizontally)
                .width(50.dp)
                .height(50.dp)
                .weight(1f, true)
                .background(color = Color.Green)
        ) {
            Text(text = index.toString(), fontSize = 18.sp, modifier = Modifier.padding(3.dp))
        }
    }
}

When a Modifier ColumnScope.weight is provided, it scales the item based on the number items that fall on the column it was placed in.

Parameters
`modifier: Modifier = Modifier`	The modifier to be applied to the Row.
`verticalArrangement: Arrangement.Vertical = Arrangement.Top`	The vertical arrangement of the layout's children.
`horizontalArrangement: Arrangement.Horizontal = Arrangement.Start`	The horizontal arrangement of the layout's virtual columns
`itemHorizontalAlignment: Alignment.Horizontal = Alignment.Start`	The cross axis/horizontal alignment of an item in the column.
`maxItemsInEachColumn: Int = Int.MAX_VALUE`	The maximum number of items per column
`maxLines: Int = Int.MAX_VALUE`	The max number of rows
`overflow: FlowColumnOverflow = FlowColumnOverflow.Clip`	The strategy to handle overflowing items
`content: @Composable FlowColumnScope.() -> Unit`	The content as a `ColumnScope`

See also
`FlowRow`
`ContextualFlowColumn`
`Column`

FlowRow

Cmn

Artifact: androidx.compose.foundation:foundation-layout

View Source

Added in 1.8.0

@Composable
fun FlowRow(
    modifier: Modifier = Modifier,
    horizontalArrangement: Arrangement.Horizontal = Arrangement.Start,
    verticalArrangement: Arrangement.Vertical = Arrangement.Top,
    itemVerticalAlignment: Alignment.Vertical = Alignment.Top,
    maxItemsInEachRow: Int = Int.MAX_VALUE,
    maxLines: Int = Int.MAX_VALUE,
    content: @Composable FlowRowScope.() -> Unit
): Unit

FlowRow is a layout that fills items from left to right (ltr) in LTR layouts or right to left (rtl) in RTL layouts and when it runs out of space, moves to the next "row" or "line" positioned on the bottom, and then continues filling items until the items run out.

Example:

import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.FlowRow
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.layout.width
import androidx.compose.foundation.layout.wrapContentHeight
import androidx.compose.material.Text
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.text.font.FontWeight
import androidx.compose.ui.unit.dp
import androidx.compose.ui.unit.sp

Text(
    modifier =
        Modifier.fillMaxWidth(1f).padding(20.dp).wrapContentHeight(align = Alignment.Top),
    text = "Flow Row with weights",
    fontWeight = FontWeight.Bold,
)

FlowRow(
    Modifier.fillMaxWidth(1f).padding(20.dp).wrapContentHeight(align = Alignment.Top),
    horizontalArrangement = Arrangement.spacedBy(10.dp),
    verticalArrangement = Arrangement.spacedBy(20.dp),
    maxItemsInEachRow = 3,
) {
    repeat(20) {
        Box(
            Modifier.align(Alignment.CenterVertically)
                .width(50.dp)
                .height(50.dp)
                .weight(1f, true)
                .background(Color.Green)
        ) {
            Text(text = it.toString(), fontSize = 18.sp, modifier = Modifier.padding(3.dp))
        }
    }
}

When a Modifier RowScope.weight is provided, it scales the item based on the number items that fall on the row it was placed in.

Note that if two or more Text components are placed in a Row, normally they should be aligned by their first baselines. FlowRow as a general purpose container does not do it automatically so developers need to handle this manually. This is achieved by adding a RowScope.alignByBaseline modifier to every such Text component. By default this modifier aligns by androidx.compose.ui.layout.FirstBaseline. If, however, you need to align Texts by androidx.compose.ui.layout.LastBaseline for example, use a more general RowScope.alignBy modifier.

Parameters
`modifier: Modifier = Modifier`	The modifier to be applied to the Row.
`horizontalArrangement: Arrangement.Horizontal = Arrangement.Start`	The horizontal arrangement of the layout's children.
`verticalArrangement: Arrangement.Vertical = Arrangement.Top`	The vertical arrangement of the layout's virtual rows.
`itemVerticalAlignment: Alignment.Vertical = Alignment.Top`	The cross axis/vertical alignment of an item in the column.
`maxItemsInEachRow: Int = Int.MAX_VALUE`	The maximum number of items per row
`maxLines: Int = Int.MAX_VALUE`	The max number of rows
`content: @Composable FlowRowScope.() -> Unit`	The content as a `RowScope`

See also
`FlowColumn`
`Row`

FlowRow

Cmn

Artifact: androidx.compose.foundation:foundation-layout

View Source

Added in 1.8.0

Deprecated in 1.8.0

@Composable
@ExperimentalLayoutApi
fun FlowRow(
    modifier: Modifier = Modifier,
    horizontalArrangement: Arrangement.Horizontal = Arrangement.Start,
    verticalArrangement: Arrangement.Vertical = Arrangement.Top,
    itemVerticalAlignment: Alignment.Vertical = Alignment.Top,
    maxItemsInEachRow: Int = Int.MAX_VALUE,
    maxLines: Int = Int.MAX_VALUE,
    overflow: FlowRowOverflow = FlowRowOverflow.Clip,
    content: @Composable FlowRowScope.() -> Unit
): Unit

Example:

import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.FlowRow
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.layout.width
import androidx.compose.foundation.layout.wrapContentHeight
import androidx.compose.material.Text
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.text.font.FontWeight
import androidx.compose.ui.unit.dp
import androidx.compose.ui.unit.sp

Text(
    modifier =
        Modifier.fillMaxWidth(1f).padding(20.dp).wrapContentHeight(align = Alignment.Top),
    text = "Flow Row with weights",
    fontWeight = FontWeight.Bold,
)

FlowRow(
    Modifier.fillMaxWidth(1f).padding(20.dp).wrapContentHeight(align = Alignment.Top),
    horizontalArrangement = Arrangement.spacedBy(10.dp),
    verticalArrangement = Arrangement.spacedBy(20.dp),
    maxItemsInEachRow = 3,
) {
    repeat(20) {
        Box(
            Modifier.align(Alignment.CenterVertically)
                .width(50.dp)
                .height(50.dp)
                .weight(1f, true)
                .background(Color.Green)
        ) {
            Text(text = it.toString(), fontSize = 18.sp, modifier = Modifier.padding(3.dp))
        }
    }
}

When a Modifier RowScope.weight is provided, it scales the item based on the number items that fall on the row it was placed in.

Parameters
`modifier: Modifier = Modifier`	The modifier to be applied to the Row.
`horizontalArrangement: Arrangement.Horizontal = Arrangement.Start`	The horizontal arrangement of the layout's children.
`verticalArrangement: Arrangement.Vertical = Arrangement.Top`	The vertical arrangement of the layout's virtual rows.
`itemVerticalAlignment: Alignment.Vertical = Alignment.Top`	The cross axis/vertical alignment of an item in the column.
`maxItemsInEachRow: Int = Int.MAX_VALUE`	The maximum number of items per row
`maxLines: Int = Int.MAX_VALUE`	The max number of rows
`overflow: FlowRowOverflow = FlowRowOverflow.Clip`	The strategy to handle overflowing items
`content: @Composable FlowRowScope.() -> Unit`	The content as a `RowScope`

See also
`FlowColumn`
`Row`

PaddingValues

Cmn

Artifact: androidx.compose.foundation:foundation-layout

View Source

fun PaddingValues(all: Dp): PaddingValues

Creates a padding of all dp along all 4 edges.

PaddingValues

Cmn

Artifact: androidx.compose.foundation:foundation-layout

View Source

fun PaddingValues(horizontal: Dp = 0.dp, vertical: Dp = 0.dp): PaddingValues

Creates a padding of horizontal dp along the left and right edges, and of vertical dp along the top and bottom edges.

PaddingValues

Cmn

Artifact: androidx.compose.foundation:foundation-layout

View Source

fun PaddingValues(start: Dp = 0.dp, top: Dp = 0.dp, end: Dp = 0.dp, bottom: Dp = 0.dp): PaddingValues

Creates a padding to be applied along the edges inside a box. In LTR contexts start will be applied along the left edge and end will be applied along the right edge. In RTL contexts, start will correspond to the right edge and end to the left.

Row

Cmn

Artifact: androidx.compose.foundation:foundation-layout

View Source

Added in 1.0.0

@Composable
inline fun Row(
    modifier: Modifier = Modifier,
    horizontalArrangement: Arrangement.Horizontal = Arrangement.Start,
    verticalAlignment: Alignment.Vertical = Alignment.Top,
    content: @Composable RowScope.() -> Unit
): Unit

A layout composable that places its children in a horizontal sequence. For a layout composable that places its children in a vertical sequence, see Column. Note that by default items do not scroll; see Modifier.horizontalScroll to add this behavior. For a horizontally scrollable list that only composes and lays out the currently visible items see LazyRow.

The Row layout is able to assign children widths according to their weights provided using the RowScope.weight modifier. If a child is not provided a weight, it will be asked for its preferred width before the sizes of the children with weights are calculated proportionally to their weight based on the remaining available space. Note that if the Row is horizontally scrollable or part of a horizontally scrollable container, any provided weights will be disregarded as the remaining available space will be infinite.

When none of its children have weights, a Row will be as small as possible to fit its children one next to the other. In order to change the width of the Row, use the Modifier.width modifiers; e.g. to make it fill the available width Modifier.fillMaxWidth can be used. If at least one child of a Row has a weight, the Row will fill the available width, so there is no need for Modifier.fillMaxWidth. However, if Row's size should be limited, the Modifier.width or Modifier.size layout modifiers should be applied.

When the size of the Row is larger than the sum of its children sizes, a horizontalArrangement can be specified to define the positioning of the children inside the Row. See Arrangement for available positioning behaviors; a custom arrangement can also be defined using the constructor of Arrangement. Below is an illustration of different horizontal arrangements:

Row
arrangements

Example usage:

import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.size
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.unit.dp
import androidx.compose.ui.unit.sp

Row {
    // The child with no weight will have the specified size.
    Box(Modifier.size(40.dp, 80.dp).background(Color.Magenta))
    // Has weight, the child will occupy half of the remaining width.
    Box(Modifier.height(40.dp).weight(1f).background(Color.Yellow))
    // Has weight and does not fill, the child will occupy at most half of the remaining width.
    // Therefore it will occupy 80.dp (its preferred width) if the assigned width is larger.
    Box(Modifier.size(80.dp, 40.dp).weight(1f, fill = false).background(Color.Green))
}

Note that if two or more Text components are placed in a Row, normally they should be aligned by their first baselines. Row as a general purpose container does not do it automatically so developers need to handle this manually. This is achieved by adding a RowScope.alignByBaseline modifier to every such Text component. By default this modifier aligns by FirstBaseline. If, however, you need to align Texts by LastBaseline for example, use a more general RowScope.alignBy modifier.

See example of using Texts inside the Row:

import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.fillMaxHeight
import androidx.compose.foundation.layout.size
import androidx.compose.material.Text
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.unit.dp
import androidx.compose.ui.unit.sp

Row(Modifier.fillMaxHeight()) {
    // The center of the magenta Box and the baselines of the two texts will be
    // vertically aligned. Note that alignBy() or alignByBaseline() has to be specified
    // for all children we want to take part in the alignment. For example, alignByBaseline()
    // means that the baseline of the text should be aligned with the alignment line
    // (possibly another baseline) specified for siblings using alignBy or alignByBaseline.
    // If no other sibling had alignBy() or alignByBaseline(), the modifier would have no
    // effect.
    Box(
        modifier =
            Modifier.size(80.dp, 40.dp)
                .alignBy { it.measuredHeight / 2 }
                .background(Color.Magenta)
    )
    Text(
        text = "Text 1",
        fontSize = 40.sp,
        modifier = Modifier.alignByBaseline().background(color = Color.Red),
    )
    Text(text = "Text 2", modifier = Modifier.alignByBaseline().background(color = Color.Cyan))
}

Parameters
`modifier: Modifier = Modifier`	The modifier to be applied to the Row.
`horizontalArrangement: Arrangement.Horizontal = Arrangement.Start`	The horizontal arrangement of the layout's children.
`verticalAlignment: Alignment.Vertical = Alignment.Top`	The vertical alignment of the layout's children.
`content: @Composable RowScope.() -> Unit`	The content of the Row

See also
`Column`
`LazyRow`

Spacer

Cmn

Artifact: androidx.compose.foundation:foundation-layout

View Source

Added in 1.0.0

@Composable
@NonRestartableComposable
fun Spacer(modifier: Modifier): Unit

Component that represents an empty space layout, whose size can be defined using Modifier.width, Modifier.height and Modifier.size modifiers.

import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.size
import androidx.compose.foundation.layout.width
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.unit.dp

Row {
    Box(Modifier.size(100.dp).background(Color.Red))
    Spacer(Modifier.width(20.dp))
    Box(Modifier.size(100.dp).background(Color.Magenta))
    Spacer(Modifier.weight(1f))
    Box(Modifier.size(100.dp).background(Color.Black))
}

Parameters
`modifier: Modifier`	modifiers to set to this spacer

WindowInsets

Cmn

Artifact: androidx.compose.foundation:foundation-layout

View Source

Added in 1.9.0-beta01

fun WindowInsets(): WindowInsets

Create a WindowInsets with fixed dimensions of 0 on all sides.

WindowInsets

Cmn

Artifact: androidx.compose.foundation:foundation-layout

View Source

fun WindowInsets(left: Dp = 0.dp, top: Dp = 0.dp, right: Dp = 0.dp, bottom: Dp = 0.dp): WindowInsets

Create a WindowInsets with fixed dimensions, using Dp values.

import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.WindowInsets
import androidx.compose.foundation.layout.statusBars
import androidx.compose.foundation.layout.union
import androidx.compose.foundation.layout.windowInsetsPadding
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.dp
import androidx.core.view.WindowCompat

class SampleActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        WindowCompat.setDecorFitsSystemWindows(window, false)
        super.onCreate(savedInstanceState)
        setContent {
            // Make sure we are at least 10 DP away from the top.
            val insets = WindowInsets.statusBars.union(WindowInsets(top = 10.dp))
            Box(Modifier.windowInsetsPadding(insets)) {
                // app content
            }
        }
    }
}

WindowInsets

Cmn

Artifact: androidx.compose.foundation:foundation-layout

View Source

Added in 1.2.0

fun WindowInsets(left: Int = 0, top: Int = 0, right: Int = 0, bottom: Int = 0): WindowInsets

Create a WindowInsets with fixed dimensions.

import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.WindowInsets
import androidx.compose.foundation.layout.statusBars
import androidx.compose.foundation.layout.union
import androidx.compose.foundation.layout.windowInsetsPadding
import androidx.compose.ui.Modifier
import androidx.core.view.WindowCompat

class SampleActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        WindowCompat.setDecorFitsSystemWindows(window, false)
        super.onCreate(savedInstanceState)
        setContent {
            // Make sure we are at least 10 pixels away from the top.
            val insets = WindowInsets.statusBars.union(WindowInsets(top = 10))
            Box(Modifier.windowInsetsPadding(insets)) {
                // app content
            }
        }
    }
}

Extension functions

absoluteOffset

Cmn

Artifact: androidx.compose.foundation:foundation-layout

View Source

Added in 1.0.0

fun Modifier.absoluteOffset(offset: Density.() -> IntOffset): Modifier

Offset the content by offset px. The offsets can be positive as well as non-positive. Applying an offset only changes the position of the content, without interfering with its size measurement.

This modifier is designed to be used for offsets that change, possibly due to user interactions. It avoids recomposition when the offset is changing, and also adds a graphics layer that prevents unnecessary redrawing of the context when the offset is changing.

This modifier will not consider layout direction when calculating the position of the content: a positive horizontal offset will always move the content to the right. For a modifier that considers layout direction when applying the offset, see offset.

Example usage:

import androidx.compose.foundation.clickable
import androidx.compose.foundation.layout.absoluteOffset
import androidx.compose.foundation.layout.offset
import androidx.compose.material.Text
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.IntOffset
import androidx.compose.ui.unit.dp

// This text will be offset in steps of 10.dp from the top left of the available space.
var offset by remember { mutableStateOf(0) }
Text(
    "Layout offset modifier sample",
    Modifier.clickable { offset += 10 }.absoluteOffset { IntOffset(offset, offset) },
)

See also
`absoluteOffset`

absoluteOffset

Cmn

Artifact: androidx.compose.foundation:foundation-layout

View Source

fun Modifier.absoluteOffset(x: Dp = 0.dp, y: Dp = 0.dp): Modifier

Offset the content by (x dp, y dp). The offsets can be positive as well as non-positive. Applying an offset only changes the position of the content, without interfering with its size measurement.

This modifier will not consider layout direction when calculating the position of the content: a positive x offset will always move the content to the right. For a modifier that considers the layout direction when applying the offset, see offset.

Example usage:

import androidx.compose.foundation.layout.absoluteOffset
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.offset
import androidx.compose.foundation.layout.wrapContentSize
import androidx.compose.material.Text
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.dp

// This text will be offset (10.dp, 20.dp) from the center of the available space.
Text(
    "Layout offset modifier sample",
    Modifier.fillMaxSize().wrapContentSize(Alignment.Center).absoluteOffset(10.dp, 20.dp),
)

See also
`offset`

absolutePadding

Cmn

Artifact: androidx.compose.foundation:foundation-layout

View Source

fun Modifier.absolutePadding(
    left: Dp = 0.dp,
    top: Dp = 0.dp,
    right: Dp = 0.dp,
    bottom: Dp = 0.dp
): Modifier

Apply additional space along each edge of the content in Dp: left, top, right and bottom. These paddings are applied without regard to the current LayoutDirection, see padding to apply relative paddings. Padding is applied before content measurement and takes precedence; content may only be as large as the remaining space.

Negative padding is not permitted — it will cause IllegalArgumentException. See Modifier.offset.

Example usage:

import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.absolutePadding
import androidx.compose.foundation.layout.size
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.unit.dp

Box(Modifier.background(color = Color.Gray)) {
    Box(
        Modifier.absolutePadding(left = 20.dp, top = 30.dp, right = 20.dp, bottom = 30.dp)
            .size(50.dp)
            .background(Color.Blue)
    )
}

add

Cmn

Artifact: androidx.compose.foundation:foundation-layout

View Source

Added in 1.2.0

fun WindowInsets.add(insets: WindowInsets): WindowInsets

Returns a WindowInsets that has values of this, added to the values of insets. For example, if this has a top of 10 and insets has a top of 5, the returned WindowInsets will have a top of 15.

asPaddingValues

Cmn

Artifact: androidx.compose.foundation:foundation-layout

View Source

Added in 1.2.0

@Composable
fun WindowInsets.asPaddingValues(): PaddingValues

Convert a WindowInsets to a PaddingValues and uses LocalDensity for DP to pixel conversion. PaddingValues can be passed to some containers to pad internal content so that it doesn't overlap the insets when fully scrolled. Ensure that the insets are consumed after the padding is applied if insets are to be used further down the hierarchy.

import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.PaddingValues
import androidx.compose.foundation.layout.WindowInsets
import androidx.compose.foundation.layout.asPaddingValues
import androidx.compose.foundation.layout.navigationBars
import androidx.compose.foundation.lazy.LazyColumn
import androidx.core.view.WindowCompat

class SampleActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        WindowCompat.setDecorFitsSystemWindows(window, false)
        super.onCreate(savedInstanceState)
        setContent {
            LazyColumn(contentPadding = WindowInsets.navigationBars.asPaddingValues()) {
                // items
            }
        }
    }
}

asPaddingValues

Cmn

Artifact: androidx.compose.foundation:foundation-layout

View Source

Added in 1.2.0

fun WindowInsets.asPaddingValues(density: Density): PaddingValues

Convert a WindowInsets to a PaddingValues and uses density for DP to pixel conversion. PaddingValues can be passed to some containers to pad internal content so that it doesn't overlap the insets when fully scrolled. Ensure that the insets are consumed after the padding is applied if insets are to be used further down the hierarchy.

import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.PaddingValues
import androidx.compose.foundation.layout.WindowInsets
import androidx.compose.foundation.layout.asPaddingValues
import androidx.compose.foundation.layout.navigationBars
import androidx.compose.foundation.lazy.LazyColumn
import androidx.core.view.WindowCompat

class SampleActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        WindowCompat.setDecorFitsSystemWindows(window, false)
        super.onCreate(savedInstanceState)
        setContent {
            LazyColumn(contentPadding = WindowInsets.navigationBars.asPaddingValues()) {
                // items
            }
        }
    }
}

aspectRatio

Cmn

Artifact: androidx.compose.foundation:foundation-layout

View Source

Added in 1.0.0

fun Modifier.aspectRatio(
    ratio: @FloatRange(from = 0.0, fromInclusive = false) Float,
    matchHeightConstraintsFirst: Boolean = false
): Modifier

Attempts to size the content to match a specified aspect ratio by trying to match one of the incoming constraints in the following order: Constraints.maxWidth, Constraints.maxHeight, Constraints.minWidth, Constraints.minHeight if matchHeightConstraintsFirst is false (which is the default), or Constraints.maxHeight, Constraints.maxWidth, Constraints.minHeight, Constraints.minWidth if matchHeightConstraintsFirst is true. The size in the other dimension is determined by the aspect ratio. The combinations will be tried in this order until one non-empty is found to satisfy the constraints. If no valid size is obtained this way, it means that there is no non-empty size satisfying both the constraints and the aspect ratio, so the constraints will not be respected and the content will be sized such that the Constraints.maxWidth or Constraints.maxHeight is matched (depending on matchHeightConstraintsFirst).

Example usage:

import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.aspectRatio
import androidx.compose.foundation.layout.width
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.unit.dp

Box(Modifier.width(100.dp).aspectRatio(2f).background(Color.Green))

Parameters
`ratio: @FloatRange(from = 0.0, fromInclusive = false) Float`	the desired width/height positive ratio
`matchHeightConstraintsFirst: Boolean = false`	if true, height constraints will be matched before width constraints and used to calculate the resulting size according to `ratio`

calculateEndPadding

Cmn

Artifact: androidx.compose.foundation:foundation-layout

View Source

Added in 1.0.0

fun PaddingValues.calculateEndPadding(layoutDirection: LayoutDirection): Dp

The padding to be applied along the end edge inside a box: along the right edge if the layout direction is LTR, or along the left edge for RTL.

calculateStartPadding

Cmn

Artifact: androidx.compose.foundation:foundation-layout

View Source

Added in 1.0.0

fun PaddingValues.calculateStartPadding(layoutDirection: LayoutDirection): Dp

The padding to be applied along the start edge inside a box: along the left edge if the layout direction is LTR, or along the right edge for RTL.

captionBarPadding

Cmn android

Artifact: androidx.compose.foundation:foundation-layout

View Source

fun Modifier.captionBarPadding(): Modifier

Adds padding to accommodate the caption bar insets.

Any insets consumed by other insets padding modifiers or consumeWindowInsets on a parent layout will be excluded from the padding. WindowInsets.Companion.captionBar will be consumed for child layouts as well.

For example, if a parent layout uses displayCutoutPadding, the area that the parent layout pads for the status bars will not be padded again by this captionBarPadding modifier.

When used, the WindowInsets will be consumed.

import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.captionBarPadding
import androidx.compose.ui.Modifier
import androidx.core.view.WindowCompat

class SampleActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        WindowCompat.setDecorFitsSystemWindows(window, false)
        super.onCreate(savedInstanceState)
        setContent {
            Box(Modifier.captionBarPadding()) {
                // app content
            }
        }
    }
}

consumeWindowInsets

Cmn

Artifact: androidx.compose.foundation:foundation-layout

View Source

Added in 1.4.0

fun Modifier.consumeWindowInsets(insets: WindowInsets): Modifier

Consume insets that haven't been consumed yet by other insets Modifiers similar to windowInsetsPadding without adding any padding.

This can be useful when content offsets are provided by WindowInsets.asPaddingValues. This should be used further down the hierarchy than the PaddingValues is used so that the values aren't consumed before the padding is added.

import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.PaddingValues
import androidx.compose.foundation.layout.WindowInsets
import androidx.compose.foundation.layout.asPaddingValues
import androidx.compose.foundation.layout.consumeWindowInsets
import androidx.compose.foundation.layout.navigationBars
import androidx.compose.foundation.layout.padding
import androidx.compose.ui.Modifier
import androidx.core.view.WindowCompat

class SampleActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        WindowCompat.setDecorFitsSystemWindows(window, false)
        super.onCreate(savedInstanceState)
        setContent {
            Box(Modifier.padding(WindowInsets.navigationBars.asPaddingValues())) {
                Box(Modifier.consumeWindowInsets(WindowInsets.navigationBars)) {
                    // app content
                }
            }
        }
    }
}

consumeWindowInsets

Cmn

Artifact: androidx.compose.foundation:foundation-layout

View Source

Added in 1.4.0

fun Modifier.consumeWindowInsets(paddingValues: PaddingValues): Modifier

Consume paddingValues as insets as if the padding was added irrespective of insets. Layouts further down the hierarchy that use windowInsetsPadding, safeContentPadding, and other insets padding Modifiers won't pad for the values that paddingValues provides. This can be useful when content offsets are provided by layout rather than windowInsetsPadding modifiers.

This method consumes all of paddingValues in addition to whatever has been consumed by other windowInsetsPadding modifiers by ancestors. consumeWindowInsets accepting a WindowInsets argument ensures that its insets are consumed and doesn't consume more if they have already been consumed by ancestors.

import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.PaddingValues
import androidx.compose.foundation.layout.WindowInsets
import androidx.compose.foundation.layout.consumeWindowInsets
import androidx.compose.foundation.layout.padding
import androidx.compose.ui.Modifier
import androidx.compose.ui.platform.LocalDensity
import androidx.compose.ui.unit.dp
import androidx.core.view.WindowCompat

class SampleActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        WindowCompat.setDecorFitsSystemWindows(window, false)
        super.onCreate(savedInstanceState)
        setContent {
            with(LocalDensity.current) {
                val paddingValues = PaddingValues(horizontal = 20.dp)
                Box(Modifier.padding(paddingValues).consumeWindowInsets(paddingValues)) {
                    // app content
                }
            }
        }
    }
}

defaultMinSize

Cmn

Artifact: androidx.compose.foundation:foundation-layout

View Source

fun Modifier.defaultMinSize(
    minWidth: Dp = Dp.Unspecified,
    minHeight: Dp = Dp.Unspecified
): Modifier

Constrain the size of the wrapped layout only when it would be otherwise unconstrained: the minWidth and minHeight constraints are only applied when the incoming corresponding constraint is 0. The modifier can be used, for example, to define a default min size of a component, while still allowing it to be overidden with smaller min sizes across usages.

Example usage:

import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.defaultMinSize
import androidx.compose.foundation.layout.requiredSize
import androidx.compose.foundation.layout.requiredSizeIn
import androidx.compose.foundation.layout.size
import androidx.compose.foundation.layout.sizeIn
import androidx.compose.runtime.Composable
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.unit.dp

@Composable
fun DefaultMinBox(modifier: Modifier = Modifier) {
    Box(modifier.defaultMinSize(minWidth = 100.dp, minHeight = 100.dp).background(Color.Blue))
}
// This will be a 100.dp x 100.dp blue box. Because we are not providing any min constraints
// to the DefaultMinBox, defaultMinSize will apply its min constraints.
DefaultMinBox()
// This will be a 50.dp x 50.dp blue box. Because we are providing min constraints
// to the DefaultMinBox, defaultMinSize will not apply its min constraints.
DefaultMinBox(Modifier.requiredSizeIn(minWidth = 50.dp, minHeight = 50.dp))
// Note that if DefaultMinBox used requiredSizeIn or sizeIn rather than
// defaultMinSize, the min constraints would have been applied with either
// of the above usages.

displayCutoutPadding

Cmn android

Artifact: androidx.compose.foundation:foundation-layout

View Source

fun Modifier.displayCutoutPadding(): Modifier

Adds padding to accommodate the display cutout.

Any insets consumed by other insets padding modifiers or consumeWindowInsets on a parent layout will be excluded from the padding. WindowInsets.Companion.displayCutout will be consumed for child layouts as well.

For example, if a parent layout uses statusBarsPadding, the area that the parent layout pads for the status bars will not be padded again by this displayCutoutPadding modifier.

When used, the WindowInsets will be consumed.

import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.displayCutoutPadding
import androidx.compose.foundation.layout.statusBars
import androidx.compose.foundation.layout.statusBarsPadding
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.core.view.WindowCompat

class SampleActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        WindowCompat.setDecorFitsSystemWindows(window, false)
        super.onCreate(savedInstanceState)
        setContent {
            Box(Modifier.background(Color.Blue).statusBarsPadding()) {
                Box(Modifier.background(Color.Yellow).displayCutoutPadding()) {
                    // app content
                }
            }
        }
    }
}

exclude

Cmn

Artifact: androidx.compose.foundation:foundation-layout

View Source

Added in 1.2.0

fun WindowInsets.exclude(insets: WindowInsets): WindowInsets

Returns the values in this WindowInsets that are not also in insets. For example, if this WindowInsets has a WindowInsets.getTop value of 10 and insets has a WindowInsets.getTop value of 8, the returned WindowInsets will have a WindowInsets.getTop value of 2.

Negative values are never returned. For example if insets has a WindowInsets.getTop of 10 and this has a WindowInsets.getTop of 0, the returned WindowInsets will have a WindowInsets.getTop value of 0.

fillMaxHeight

Cmn

Artifact: androidx.compose.foundation:foundation-layout

View Source

Added in 1.0.0

fun Modifier.fillMaxHeight(
    fraction: @FloatRange(from = 0.0, to = 1.0) Float = 1.0f
): Modifier

Have the content fill (possibly only partially) the Constraints.maxHeight of the incoming measurement constraints, by setting the minimum height and the maximum height to be equal to the maximum height multiplied by fraction. Note that, by default, the fraction is 1, so the modifier will make the content fill the whole available height. If the incoming maximum height is Constraints.Infinity this modifier will have no effect.

import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.fillMaxHeight
import androidx.compose.foundation.layout.size
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.unit.dp

Box(Modifier.fillMaxHeight().background(Color.Red), contentAlignment = Alignment.Center) {
    Box(Modifier.size(100.dp).background(color = Color.Magenta))
}

import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.fillMaxHeight
import androidx.compose.foundation.layout.requiredSize
import androidx.compose.foundation.layout.requiredWidth
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.unit.dp

Box(Modifier.requiredSize(100.dp).background(Color.Red), contentAlignment = Alignment.Center) {
    // The inner Box will be (30.dp x 50.dp).
    Box(Modifier.requiredWidth(30.dp).fillMaxHeight(0.5f).background(color = Color.Magenta))
}

Parameters

Parameters
`fraction: @FloatRange(from = 0.0, to = 1.0) Float = 1.0f`	The fraction of the maximum height to use, between `0` and `1`, inclusive. Example usage:

fraction: @FloatRange(from = 0.0, to = 1.0) Float = 1.0f

The fraction of the maximum height to use, between 0 and 1, inclusive.

Example usage:

fillMaxSize

Cmn

Artifact: androidx.compose.foundation:foundation-layout

View Source

Added in 1.0.0

fun Modifier.fillMaxSize(fraction: @FloatRange(from = 0.0, to = 1.0) Float = 1.0f): Modifier

Have the content fill (possibly only partially) the Constraints.maxWidth and Constraints.maxHeight of the incoming measurement constraints, by setting the minimum width and the maximum width to be equal to the maximum width multiplied by fraction, as well as the minimum height and the maximum height to be equal to the maximum height multiplied by fraction. Note that, by default, the fraction is 1, so the modifier will make the content fill the whole available space. If the incoming maximum width or height is Constraints.Infinity this modifier will have no effect in that dimension.

import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.size
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.unit.dp

Box(Modifier.fillMaxSize().background(Color.Red), contentAlignment = Alignment.Center) {
    Box(Modifier.size(100.dp).background(color = Color.Magenta))
}

import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.requiredSize
import androidx.compose.foundation.layout.requiredWidth
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.unit.dp

Box(Modifier.requiredSize(100.dp).background(Color.Red), contentAlignment = Alignment.Center) {
    // The inner Box will be (50.dp x 50.dp).
    Box(Modifier.requiredWidth(30.dp).fillMaxSize(0.5f).background(color = Color.Magenta))
}

Parameters

Parameters
`fraction: @FloatRange(from = 0.0, to = 1.0) Float = 1.0f`	The fraction of the maximum size to use, between `0` and `1`, inclusive. Example usage:

fraction: @FloatRange(from = 0.0, to = 1.0) Float = 1.0f

The fraction of the maximum size to use, between 0 and 1, inclusive.

Example usage:

fillMaxWidth

Cmn

Artifact: androidx.compose.foundation:foundation-layout

View Source

Added in 1.0.0

fun Modifier.fillMaxWidth(fraction: @FloatRange(from = 0.0, to = 1.0) Float = 1.0f): Modifier

Have the content fill (possibly only partially) the Constraints.maxWidth of the incoming measurement constraints, by setting the minimum width and the maximum width to be equal to the maximum width multiplied by fraction. Note that, by default, the fraction is 1, so the modifier will make the content fill the whole available width. If the incoming maximum width is Constraints.Infinity this modifier will have no effect.

import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.size
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.unit.dp

Box(Modifier.fillMaxWidth().background(Color.Red), contentAlignment = Alignment.Center) {
    Box(Modifier.size(100.dp).background(color = Color.Magenta))
}

import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.requiredHeight
import androidx.compose.foundation.layout.requiredSize
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.unit.dp

Box(Modifier.requiredSize(100.dp).background(Color.Red), contentAlignment = Alignment.Center) {
    // The inner Box will be (50.dp x 30.dp).
    Box(
        Modifier.fillMaxWidth(fraction = 0.5f)
            .requiredHeight(30.dp)
            .background(color = Color.Magenta)
    )
}

Parameters

Parameters
`fraction: @FloatRange(from = 0.0, to = 1.0) Float = 1.0f`	The fraction of the maximum width to use, between `0` and `1`, inclusive. Example usage:

fraction: @FloatRange(from = 0.0, to = 1.0) Float = 1.0f

The fraction of the maximum width to use, between 0 and 1, inclusive.

Example usage:

fitInside

Cmn

Artifact: androidx.compose.foundation:foundation-layout

View Source

Added in 1.9.0-beta01

fun Modifier.fitInside(rulers: RectRulers): Modifier

Fits the contents within rulers. This only works when Constraints have fixed width and fixed height. This can be accomplished, for example, by having Modifier.size, or Modifier.fillMaxSize, or other size modifier before fitInside. If the Constraints sizes aren't fixed, fitInside will size the child to the Constraints and try to center the content within rulers.

import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.fitInside
import androidx.compose.foundation.layout.fitOutside
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.layout.WindowInsetsRulers.Companion.NavigationBars
import androidx.compose.ui.layout.WindowInsetsRulers.Companion.SafeContent
import androidx.compose.ui.layout.WindowInsetsRulers.Companion.StatusBars

Box(Modifier.fillMaxSize()) {
    // Drawn behind the status bar
    Box(Modifier.fillMaxSize().fitOutside(StatusBars.current).background(Color.Blue))
    // Drawn behind the navigation bar
    Box(Modifier.fillMaxSize().fitOutside(NavigationBars.current).background(Color.Red))
    // Body of the app
    Box(Modifier.fillMaxSize().fitInside(SafeContent.current).background(Color.Yellow))
}

See also
`fitOutside`

fitOutside

Cmn

Artifact: androidx.compose.foundation:foundation-layout

View Source

Added in 1.9.0-beta01

fun Modifier.fitOutside(rulers: RectRulers): Modifier

If one of the Rulers in rulers has a value within the bounds of the Layout, this sizes the content to that Ruler and the edge. If multiple Rulers have a value within the space, only one is chosen, in this order: RectRulers.left, RectRulers.top, RectRulers.right, RectRulers.bottom. This only works when Constraints have fixed width and fixed height. This can be accomplished, for example, by having Modifier.size, or Modifier.fillMaxSize, or other size modifier before fitOutside. If the Constraints sizes aren't fixed, or there are no Rulers within the bounds of the layout, fitOutside will size the content area to 0x0.

import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.fitInside
import androidx.compose.foundation.layout.fitOutside
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.layout.WindowInsetsRulers.Companion.NavigationBars
import androidx.compose.ui.layout.WindowInsetsRulers.Companion.SafeContent
import androidx.compose.ui.layout.WindowInsetsRulers.Companion.StatusBars

Box(Modifier.fillMaxSize()) {
    // Drawn behind the status bar
    Box(Modifier.fillMaxSize().fitOutside(StatusBars.current).background(Color.Blue))
    // Drawn behind the navigation bar
    Box(Modifier.fillMaxSize().fitOutside(NavigationBars.current).background(Color.Red))
    // Body of the app
    Box(Modifier.fillMaxSize().fitInside(SafeContent.current).background(Color.Yellow))
}

See also
`fitInside`

height

Cmn

Artifact: androidx.compose.foundation:foundation-layout

View Source

fun Modifier.height(height: Dp): Modifier

Declare the preferred height of the content to be exactly heightdp. The incoming measurement Constraints may override this value, forcing the content to be either smaller or larger.

For a modifier that sets the height of the content regardless of the incoming constraints see Modifier.requiredHeight. See width or size to set other preferred dimensions. See widthIn, heightIn or sizeIn to set a preferred size range.

Example usage:

import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.aspectRatio
import androidx.compose.foundation.layout.height
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.unit.dp

Box { Box(Modifier.height(100.dp).aspectRatio(1f).background(Color.Blue)) }

height

Cmn

Artifact: androidx.compose.foundation:foundation-layout

View Source

Added in 1.0.0

fun Modifier.height(intrinsicSize: IntrinsicSize): Modifier

Declare the preferred height of the content to be the same as the min or max intrinsic height of the content. The incoming measurement Constraints may override this value, forcing the content to be either smaller or larger.

See width for other options of sizing to intrinsic width. Also see height and heightIn for other options to set the preferred height.

Example usage for min intrinsic:

import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.IntrinsicSize
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.fillMaxHeight
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.size
import androidx.compose.foundation.layout.width
import androidx.compose.material.Text
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.unit.dp

// Builds a layout containing two pieces of text separated by a divider, where the divider
// is sized according to the height of the longest text.
//
// Here height min intrinsic is adding a height premeasurement pass for the Row,
// whose minimum intrinsic height will correspond to the height of the largest Text. Then
// height min intrinsic will measure the Row with tight height, the same as the
// premeasured minimum intrinsic height, which due to fillMaxHeight will force the Texts and
// the divider to use the same height.
Box {
    Row(Modifier.height(IntrinsicSize.Min)) {
        Text(
            text = "This is a really short text",
            modifier = Modifier.weight(1f).fillMaxHeight(),
        )
        Box(Modifier.width(1.dp).fillMaxHeight().background(Color.Black))
        Text(
            text =
                "This is a much much much much much much much much much much" +
                    " much much much much much much longer text",
            modifier = Modifier.weight(1f).fillMaxHeight(),
        )
    }
}

Example usage for max intrinsic:

import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.IntrinsicSize
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.aspectRatio
import androidx.compose.foundation.layout.fillMaxHeight
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.size
import androidx.compose.foundation.layout.width
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.unit.dp

// Builds a layout containing two aspectRatios separated by a divider, where the divider
// is sized according to the height of the taller aspectRatio.
//
// Here height max intrinsic is adding a height premeasurement pass for the
// Row, whose maximum intrinsic height will correspond to the height of the taller
// aspectRatio. Then height max intrinsic will measure the Row with tight height,
// the same as the premeasured maximum intrinsic height, which due to fillMaxHeight modifier
// will force the aspectRatios and the divider to use the same height.
//
Box {
    Row(Modifier.height(IntrinsicSize.Max)) {
        val modifier = Modifier.fillMaxHeight().weight(1f)
        Box(modifier.aspectRatio(2f).background(Color.Gray))
        Box(Modifier.width(1.dp).fillMaxHeight().background(Color.Black))
        Box(modifier.aspectRatio(1f).background(Color.Blue))
    }
}

heightIn

Cmn

Artifact: androidx.compose.foundation:foundation-layout

View Source

fun Modifier.heightIn(min: Dp = Dp.Unspecified, max: Dp = Dp.Unspecified): Modifier

Constrain the height of the content to be between mindp and maxdp as permitted by the incoming measurement Constraints. If the incoming constraints are more restrictive the requested size will obey the incoming constraints and attempt to be as close as possible to the preferred size.

imeNestedScroll

android

Artifact: androidx.compose.foundation:foundation-layout

View Source

@ExperimentalLayoutApi
fun Modifier.imeNestedScroll(): Modifier

Controls the soft keyboard as a nested scrolling on Android R and later. This allows the user to drag the soft keyboard up and down.

After scrolling, the IME will animate either to the fully shown or fully hidden position, depending on the position and fling.

import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.imeNestedScroll
import androidx.compose.foundation.layout.imePadding
import androidx.compose.foundation.lazy.LazyColumn
import androidx.compose.material.Text
import androidx.compose.ui.Modifier

LazyColumn(
    modifier =
        Modifier.fillMaxSize() // fill the window
            .imePadding() // pad out the bottom for the IME
            .imeNestedScroll(), // scroll IME at the bottom
    reverseLayout = true, // First item is at the bottom
) {
    // content
    items(50) { Text("Hello World") }
}

imePadding

Cmn android

Artifact: androidx.compose.foundation:foundation-layout

View Source

fun Modifier.imePadding(): Modifier

Adds padding to accommodate the ime insets.

Any insets consumed by other insets padding modifiers or consumeWindowInsets on a parent layout will be excluded from the padding. WindowInsets.Companion.ime will be consumed for child layouts as well.

For example, if a parent layout uses navigationBarsPadding, the area that the parent layout pads for the status bars will not be padded again by this imePadding modifier.

When used, the WindowInsets will be consumed.

import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.ime
import androidx.compose.foundation.layout.imePadding
import androidx.compose.foundation.layout.systemBars
import androidx.compose.foundation.layout.systemBarsPadding
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.core.view.WindowCompat

class SampleActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        WindowCompat.setDecorFitsSystemWindows(window, false)
        super.onCreate(savedInstanceState)
        setContent {
            Box(Modifier.background(Color.Blue).systemBarsPadding()) {
                Box(Modifier.imePadding()) {
                    // app content
                }
            }
        }
    }
}

mandatorySystemGesturesPadding

Cmn android

Artifact: androidx.compose.foundation:foundation-layout

View Source

fun Modifier.mandatorySystemGesturesPadding(): Modifier

Adds padding to accommodate the mandatory system gestures insets.

Any insets consumed by other insets padding modifiers or consumeWindowInsets on a parent layout will be excluded from the padding. WindowInsets.Companion.mandatorySystemGestures will be consumed for child layouts as well.

For example, if a parent layout uses navigationBarsPadding, the area that the parent layout pads for the status bars will not be padded again by this mandatorySystemGesturesPadding modifier.

When used, the WindowInsets will be consumed.

import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.mandatorySystemGesturesPadding
import androidx.compose.foundation.layout.systemBars
import androidx.compose.foundation.layout.systemBarsPadding
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.core.view.WindowCompat

class SampleActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        WindowCompat.setDecorFitsSystemWindows(window, false)
        super.onCreate(savedInstanceState)
        setContent {
            Box(Modifier.background(Color.Blue).systemBarsPadding()) {
                // The app content won't interfere with the mandatory system gestures area.
                // It will just be white.
                Box(Modifier.background(Color.White).mandatorySystemGesturesPadding()) {
                    // app content
                }
            }
        }
    }
}

navigationBarsPadding

Cmn android

Artifact: androidx.compose.foundation:foundation-layout

View Source

fun Modifier.navigationBarsPadding(): Modifier

Adds padding to accommodate the navigation bars insets.

Any insets consumed by other insets padding modifiers or consumeWindowInsets on a parent layout will be excluded from the padding. WindowInsets.Companion.navigationBars will be consumed for child layouts as well.

For example, if a parent layout uses systemBarsPadding, the area that the parent layout pads for the status bars will not be padded again by this navigationBarsPadding modifier.

When used, the WindowInsets will be consumed.

import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.navigationBars
import androidx.compose.foundation.layout.navigationBarsPadding
import androidx.compose.foundation.layout.statusBars
import androidx.compose.foundation.layout.statusBarsPadding
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.core.view.WindowCompat

class SampleActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        WindowCompat.setDecorFitsSystemWindows(window, false)
        super.onCreate(savedInstanceState)
        setContent {
            Box(Modifier.background(Color.Blue).statusBarsPadding()) {
                Box(Modifier.background(Color.Green).navigationBarsPadding()) {
                    // app content
                }
            }
        }
    }
}

offset

Cmn

Artifact: androidx.compose.foundation:foundation-layout

View Source

Added in 1.0.0

fun Modifier.offset(offset: Density.() -> IntOffset): Modifier

Offset the content by offset px. The offsets can be positive as well as non-positive. Applying an offset only changes the position of the content, without interfering with its size measurement.

This modifier will automatically adjust the horizontal offset according to the layout direction: when the LD is LTR, positive horizontal offsets will move the content to the right and when the LD is RTL, positive horizontal offsets will move the content to the left. For a modifier that offsets without considering layout direction, see absoluteOffset.

Example usage:

import androidx.compose.foundation.clickable
import androidx.compose.foundation.layout.offset
import androidx.compose.material.Text
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.IntOffset
import androidx.compose.ui.unit.dp

// This text will be offset in steps of 10.dp from the top left of the available space in
// left-to-right context, and from top right in right-to-left context.
var offset by remember { mutableStateOf(0) }
Text(
    "Layout offset modifier sample",
    Modifier.clickable { offset += 10 }.offset { IntOffset(offset, offset) },
)

See also
`absoluteOffset`

offset

Cmn

Artifact: androidx.compose.foundation:foundation-layout

View Source

fun Modifier.offset(x: Dp = 0.dp, y: Dp = 0.dp): Modifier

This modifier will automatically adjust the horizontal offset according to the layout direction: when the layout direction is LTR, positive x offsets will move the content to the right and when the layout direction is RTL, positive x offsets will move the content to the left. For a modifier that offsets without considering layout direction, see absoluteOffset.

Example usage:

import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.offset
import androidx.compose.foundation.layout.wrapContentSize
import androidx.compose.material.Text
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.dp

// This text will be offset (10.dp, 20.dp) from the center of the available space. In the
// right-to-left context, the offset will be (-10.dp, 20.dp).
Text(
    "Layout offset modifier sample",
    Modifier.fillMaxSize().wrapContentSize(Alignment.Center).offset(10.dp, 20.dp),
)

See also
`absoluteOffset`

onConsumedWindowInsetsChanged

Cmn

Artifact: androidx.compose.foundation:foundation-layout

View Source

Added in 1.4.0

fun Modifier.onConsumedWindowInsetsChanged(
    block: (consumedWindowInsets: WindowInsets) -> Unit
): Modifier

Calls block with the WindowInsets that have been consumed, either by consumeWindowInsets or one of the padding Modifiers, such as imePadding.

import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.MutableWindowInsets
import androidx.compose.foundation.layout.PaddingValues
import androidx.compose.foundation.layout.WindowInsets
import androidx.compose.foundation.layout.asPaddingValues
import androidx.compose.foundation.layout.exclude
import androidx.compose.foundation.layout.navigationBars
import androidx.compose.foundation.layout.navigationBarsPadding
import androidx.compose.foundation.layout.onConsumedWindowInsetsChanged
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.layout.safeContent
import androidx.compose.runtime.remember
import androidx.compose.ui.Modifier
import androidx.core.view.WindowCompat

class SampleActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        WindowCompat.setDecorFitsSystemWindows(window, false)
        super.onCreate(savedInstanceState)
        setContent {
            val remainingInsets = remember { MutableWindowInsets() }
            val safeContent = WindowInsets.safeContent
            Box(
                Modifier.navigationBarsPadding().onConsumedWindowInsetsChanged {
                    consumedWindowInsets ->
                    remainingInsets.insets = safeContent.exclude(consumedWindowInsets)
                }
            ) {
                // padding can be used without recomposition when insets change.
                val padding = remainingInsets.asPaddingValues()
                Box(Modifier.padding(padding))
            }
        }
    }
}

only

Cmn

Artifact: androidx.compose.foundation:foundation-layout

View Source

fun WindowInsets.only(sides: WindowInsetsSides): WindowInsets

Returns a WindowInsets that eliminates all dimensions except the ones that are enabled. For example, to have a WindowInsets at the bottom of the screen, pass WindowInsetsSides.Bottom.

padding

Cmn

Artifact: androidx.compose.foundation:foundation-layout

View Source

fun Modifier.padding(all: Dp): Modifier

Apply all dp of additional space along each edge of the content, left, top, right and bottom. Padding is applied before content measurement and takes precedence; content may only be as large as the remaining space.

Negative padding is not permitted — it will cause IllegalArgumentException. See Modifier.offset.

Example usage:

import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.layout.size
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.unit.dp

Box(Modifier.background(color = Color.Gray)) {
    Box(Modifier.padding(all = 20.dp).size(50.dp).background(Color.Blue))
}

padding

Cmn

Artifact: androidx.compose.foundation:foundation-layout

View Source

Added in 1.0.0

fun Modifier.padding(paddingValues: PaddingValues): Modifier

Apply PaddingValues to the component as additional space along each edge of the content's left, top, right and bottom. Padding is applied before content measurement and takes precedence; content may only be as large as the remaining space.

Negative padding is not permitted — it will cause IllegalArgumentException. See Modifier.offset.

Example usage:

import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.PaddingValues
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.layout.size
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.unit.dp

val innerPadding = PaddingValues(top = 10.dp, start = 15.dp)
Box(Modifier.background(color = Color.Gray)) {
    Box(Modifier.padding(innerPadding).size(50.dp).background(Color.Blue))
}

padding

Cmn

Artifact: androidx.compose.foundation:foundation-layout

View Source

fun Modifier.padding(horizontal: Dp = 0.dp, vertical: Dp = 0.dp): Modifier

Apply horizontal dp space along the left and right edges of the content, and vertical dp space along the top and bottom edges. Padding is applied before content measurement and takes precedence; content may only be as large as the remaining space.

Negative padding is not permitted — it will cause IllegalArgumentException. See Modifier.offset.

Example usage:

import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.layout.size
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.unit.dp

Box(Modifier.background(color = Color.Gray)) {
    Box(
        Modifier.padding(horizontal = 20.dp, vertical = 30.dp)
            .size(50.dp)
            .background(Color.Blue)
    )
}

padding

Cmn

Artifact: androidx.compose.foundation:foundation-layout

View Source

fun Modifier.padding(start: Dp = 0.dp, top: Dp = 0.dp, end: Dp = 0.dp, bottom: Dp = 0.dp): Modifier

Apply additional space along each edge of the content in Dp: start, top, end and bottom. The start and end edges will be determined by the current LayoutDirection. Padding is applied before content measurement and takes precedence; content may only be as large as the remaining space.

Negative padding is not permitted — it will cause IllegalArgumentException. See Modifier.offset.

Example usage:

import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.layout.size
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.unit.dp

Box(Modifier.background(color = Color.Gray)) {
    Box(
        Modifier.padding(start = 20.dp, top = 30.dp, end = 20.dp, bottom = 30.dp)
            .size(50.dp)
            .background(Color.Blue)
    )
}

paddingFrom

Cmn

Artifact: androidx.compose.foundation:foundation-layout

View Source

fun Modifier.paddingFrom(
    alignmentLine: AlignmentLine,
    before: Dp = Dp.Unspecified,
    after: Dp = Dp.Unspecified
): Modifier

A Modifier that can add padding to position the content according to specified distances from its bounds to an alignment line. Whether the positioning is vertical or horizontal is defined by the orientation of the given alignmentLine (if the line is horizontal, before and after will refer to distances from top and bottom, otherwise they will refer to distances from start and end). The opposite axis sizing and positioning will remain unaffected. The modified layout will try to include the required padding, subject to the incoming max layout constraints, such that the distance from its bounds to the alignmentLine of the content will be before and after, respectively. When the max constraints do not allow this, satisfying the before requirement will have priority over after. When the modified layout is min constrained in the affected layout direction and the padded layout is smaller than the constraint, the modified layout will satisfy the min constraint and the content will be positioned to satisfy the before requirement if specified, or the after requirement otherwise.

Example usage:

import androidx.compose.foundation.layout.paddingFrom
import androidx.compose.material.Text
import androidx.compose.ui.Modifier
import androidx.compose.ui.layout.FirstBaseline
import androidx.compose.ui.platform.LocalDensity
import androidx.compose.ui.unit.dp
import androidx.compose.ui.unit.sp

// We want to have 30.sp distance from the top of the layout box to the baseline of the
// first line of text.
val distanceToBaseline = 30.sp
// We convert the 30.sp value to dps, which is required for the paddingFrom API.
val distanceToBaselineDp = with(LocalDensity.current) { distanceToBaseline.toDp() }
// The result will be a layout with 30.sp distance from the top of the layout box to the
// baseline of the first line of text.
Text(
    text = "This is an example.",
    modifier = Modifier.paddingFrom(FirstBaseline, before = distanceToBaselineDp),
)

Parameters
`alignmentLine: AlignmentLine`	the alignment line relative to which the padding is defined
`before: Dp = Dp.Unspecified`	the distance between the container's top edge and the horizontal alignment line, or the container's start edge and the vertical alignment line
`after: Dp = Dp.Unspecified`	the distance between the container's bottom edge and the horizontal alignment line, or the container's end edge and the vertical alignment line

See also
`paddingFromBaseline`

paddingFrom

Cmn

Artifact: androidx.compose.foundation:foundation-layout

View Source

fun Modifier.paddingFrom(
    alignmentLine: AlignmentLine,
    before: TextUnit = TextUnit.Unspecified,
    after: TextUnit = TextUnit.Unspecified
): Modifier

Example usage:

import androidx.compose.foundation.layout.paddingFrom
import androidx.compose.material.Text
import androidx.compose.ui.Modifier
import androidx.compose.ui.layout.FirstBaseline
import androidx.compose.ui.platform.LocalDensity
import androidx.compose.ui.unit.dp
import androidx.compose.ui.unit.sp

// We want to have 30.sp distance from the top of the layout box to the baseline of the
// first line of text.
val distanceToBaseline = 30.sp
// We convert the 30.sp value to dps, which is required for the paddingFrom API.
val distanceToBaselineDp = with(LocalDensity.current) { distanceToBaseline.toDp() }
// The result will be a layout with 30.sp distance from the top of the layout box to the
// baseline of the first line of text.
Text(
    text = "This is an example.",
    modifier = Modifier.paddingFrom(FirstBaseline, before = distanceToBaselineDp),
)

Parameters
`alignmentLine: AlignmentLine`	the alignment line relative to which the padding is defined
`before: TextUnit = TextUnit.Unspecified`	the distance between the container's top edge and the horizontal alignment line, or the container's start edge and the vertical alignment line
`after: TextUnit = TextUnit.Unspecified`	the distance between the container's bottom edge and the horizontal alignment line, or the container's end edge and the vertical alignment line

See also
`paddingFromBaseline`

paddingFromBaseline

Cmn

Artifact: androidx.compose.foundation:foundation-layout

View Source

fun Modifier.paddingFromBaseline(
    top: Dp = Dp.Unspecified,
    bottom: Dp = Dp.Unspecified
): Modifier

A Modifier that positions the content in a layout such that the distance from the top of the layout to the baseline of the first line of text in the content is top, and the distance from the baseline of the last line of text in the content to the bottom of the layout is bottom.

When the modified layout is min height constrained and the padded layout is smaller than the constraint, the modified layout will satisfy the min constraint and the content will be positioned to satisfy the top requirement if specified, or the bottom requirement otherwise.

Example usage:

import androidx.compose.foundation.layout.paddingFrom
import androidx.compose.foundation.layout.paddingFromBaseline
import androidx.compose.material.Text
import androidx.compose.ui.Modifier
import androidx.compose.ui.layout.FirstBaseline
import androidx.compose.ui.unit.dp
import androidx.compose.ui.unit.sp

// We want to have 30.dp distance from the top of the layout box to the baseline of the
// first line of text, and a 40.dp distance from the bottom of the layout box to the baseline
// of the last line of text. Note it is good practice to specify these distances in sp for font
// scaling, which can be done with the other overload.
val distanceToFirstBaseline = 30.dp
val distanceFromLastBaseline = 40.dp
Text(
    text = "This line has the first baseline.\nThis line has the last baseline.",
    modifier = Modifier.paddingFromBaseline(distanceToFirstBaseline, distanceFromLastBaseline),
)

See also
`paddingFrom`

paddingFromBaseline

Cmn

Artifact: androidx.compose.foundation:foundation-layout

View Source

fun Modifier.paddingFromBaseline(
    top: TextUnit = TextUnit.Unspecified,
    bottom: TextUnit = TextUnit.Unspecified
): Modifier

Example usage:

import androidx.compose.foundation.layout.paddingFrom
import androidx.compose.foundation.layout.paddingFromBaseline
import androidx.compose.material.Text
import androidx.compose.ui.Modifier
import androidx.compose.ui.layout.FirstBaseline
import androidx.compose.ui.unit.sp

// We want to have 30.sp distance from the top of the layout box to the baseline of the
// first line of text, and a 40.sp distance from the bottom of the layout box to the baseline
// of the last line of text.
val distanceToFirstBaseline = 30.sp
val distanceFromLastBaseline = 40.sp
Text(
    text = "This line has the first baseline.\nThis line has the last baseline.",
    modifier = Modifier.paddingFromBaseline(distanceToFirstBaseline, distanceFromLastBaseline),
)

See also
`paddingFrom`

recalculateWindowInsets

Cmn

Artifact: androidx.compose.foundation:foundation-layout

View Source

Added in 1.8.0

fun Modifier.recalculateWindowInsets(): Modifier

This recalculates the WindowInsets based on the size and position. This only works when Constraints have fixed width and fixed height. This can be accomplished, for example, by having Modifier.size, or Modifier.fillMaxSize, or other size modifier before recalculateWindowInsets. If the Constraints sizes aren't fixed, recalculateWindowInsets won't adjust the WindowInsets and won't have any affect on layout.

recalculateWindowInsets is useful when the parent does not call consumeWindowInsets when it aligns a child. For example, a Column with two children should have different WindowInsets for each child. The top item should exclude insets below its bottom and the bottom item should exclude the top insets, but the Column can't assign different insets for different children.

import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.WindowInsets
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.recalculateWindowInsets
import androidx.compose.foundation.layout.safeDrawingPadding
import androidx.compose.material.Button
import androidx.compose.material.Text
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color

var hasFirstItem by remember { mutableStateOf(true) }
var hasLastItem by remember { mutableStateOf(true) }
Column(Modifier.fillMaxSize()) {
    if (hasFirstItem) {
        Box(Modifier.weight(1f).fillMaxWidth().background(Color.Magenta))
    }
    Box(
        Modifier.fillMaxWidth() // force a fixed size on the content
            .recalculateWindowInsets()
            .weight(1f)
            .background(Color.Yellow)
            .safeDrawingPadding()
    ) {
        Button(
            onClick = { hasFirstItem = !hasFirstItem },
            Modifier.align(Alignment.TopCenter),
        ) {
            val action = if (hasFirstItem) "Remove" else "Add"
            Text("$action First Item")
        }
        Button(
            onClick = { hasLastItem = !hasLastItem },
            Modifier.align(Alignment.BottomCenter),
        ) {
            val action = if (hasLastItem) "Remove" else "Add"
            Text("$action Last Item")
        }
    }
    if (hasLastItem) {
        Box(Modifier.weight(1f).fillMaxWidth().background(Color.Cyan))
    }
}

Another use is when a parent doesn't properly consumeWindowInsets for all space that it consumes. For example, a 3rd-party container has padding that doesn't properly use consumeWindowInsets.

import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.WindowInsets
import androidx.compose.foundation.layout.consumeWindowInsets
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.layout.recalculateWindowInsets
import androidx.compose.foundation.layout.safeContent
import androidx.compose.foundation.layout.safeContentPadding
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.unit.dp

// This outer Box is representing a 3rd-party layout that you don't control. It has a
// padding, but doesn't properly use consumeWindowInsets()
Box(Modifier.padding(10.dp)) {
    // This is the content that you control. You can make sure that the WindowInsets are correct
    // so you can pad your content despite the fact that the parent did not
    // consumeWindowInsets()
    Box(
        Modifier.fillMaxSize() // Force a fixed size on the content
            .recalculateWindowInsets()
            .safeContentPadding()
            .background(Color.Blue)
    )
}

In most cases you should not need to use this API, and the parent should instead use consumeWindowInsets to provide the correct values

import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.WindowInsets
import androidx.compose.foundation.layout.consumeWindowInsets
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.layout.safeContent
import androidx.compose.foundation.layout.safeContentPadding
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.unit.dp

// The outer Box uses padding and properly compensates for it by using consumeWindowInsets()
Box(
    Modifier.fillMaxSize()
        .padding(10.dp)
        .consumeWindowInsets(WindowInsets(10.dp, 10.dp, 10.dp, 10.dp))
) {
    Box(Modifier.fillMaxSize().safeContentPadding().background(Color.Blue))
}

requiredHeight

Cmn

Artifact: androidx.compose.foundation:foundation-layout

View Source

fun Modifier.requiredHeight(height: Dp): Modifier

Declare the height of the content to be exactly heightdp. The incoming measurement Constraints will not override this value. If the content chooses a size that does not satisfy the incoming Constraints, the parent layout will be reported a size coerced in the Constraints, and the position of the content will be automatically offset to be centered on the space assigned to the child by the parent layout under the assumption that Constraints were respected.

See requiredHeightIn and requiredSizeIn to set a size range. See height to set a preferred height, which is only respected when the incoming constraints allow it.

Example usage:

import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.aspectRatio
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.requiredHeight
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.unit.dp

// The result is a 50.dp x 50.dp blue box centered in a 100.dp x 100.dp space.
// Note that although a previous modifier asked it to be 100.dp height, this
// will not be respected. They would be respected if height was used instead of requiredHeight.
Box(
    Modifier.requiredHeight(100.dp).requiredHeight(50.dp).aspectRatio(1f).background(Color.Blue)
)

requiredHeight

Cmn

Artifact: androidx.compose.foundation:foundation-layout

View Source

Added in 1.0.0

fun Modifier.requiredHeight(intrinsicSize: IntrinsicSize): Modifier

Declare the height of the content to be exactly the same as the min or max intrinsic height of the content. The incoming measurement Constraints will not override this value. If the content intrinsic height does not satisfy the incoming Constraints, the parent layout will be reported a size coerced in the Constraints, and the position of the content will be automatically offset to be centered on the space assigned to the child by the parent layout under the assumption that Constraints were respected.

See width for options of sizing to intrinsic width. See height and heightIn for options to set the preferred height. See requiredHeight and requiredHeightIn for other options to set the required height.

requiredHeightIn

Cmn

Artifact: androidx.compose.foundation:foundation-layout

View Source

fun Modifier.requiredHeightIn(min: Dp = Dp.Unspecified, max: Dp = Dp.Unspecified): Modifier

Constrain the height of the content to be between mindp and maxdp. If the content chooses a size that does not satisfy the incoming Constraints, the parent layout will be reported a size coerced in the Constraints, and the position of the content will be automatically offset to be centered on the space assigned to the child by the parent layout under the assumption that Constraints were respected.

requiredSize

Cmn

Artifact: androidx.compose.foundation:foundation-layout

View Source

fun Modifier.requiredSize(size: Dp): Modifier

Declare the size of the content to be exactly sizedp width and height. The incoming measurement Constraints will not override this value. If the content chooses a size that does not satisfy the incoming Constraints, the parent layout will be reported a size coerced in the Constraints, and the position of the content will be automatically offset to be centered on the space assigned to the child by the parent layout under the assumption that Constraints were respected.

See requiredSizeIn to set a size range. See size to set a preferred size, which is only respected when the incoming constraints allow it.

Example usage:

import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.requiredSize
import androidx.compose.foundation.layout.size
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.unit.dp

// The result is a 50.dp x 50.dp red box centered in a 100.dp x 100.dp space.
// Note that although a previous modifier asked it to be 100.dp x 100.dp, this
// will not be respected. They would be respected if size was used instead of requiredSize.
Box(Modifier.requiredSize(100.dp, 100.dp).requiredSize(50.dp, 50.dp).background(Color.Red))

requiredSize

Cmn

Artifact: androidx.compose.foundation:foundation-layout

View Source

fun Modifier.requiredSize(size: DpSize): Modifier

Declare the size of the content to be exactly size. The incoming measurement Constraints will not override this value. If the content chooses a size that does not satisfy the incoming Constraints, the parent layout will be reported a size coerced in the Constraints, and the position of the content will be automatically offset to be centered on the space assigned to the child by the parent layout under the assumption that Constraints were respected.

See requiredSizeIn to set a size range. See size to set a preferred size, which is only respected when the incoming constraints allow it.

requiredSize

Cmn

Artifact: androidx.compose.foundation:foundation-layout

View Source

fun Modifier.requiredSize(width: Dp, height: Dp): Modifier

Declare the size of the content to be exactly widthdp and heightdp. The incoming measurement Constraints will not override this value. If the content chooses a size that does not satisfy the incoming Constraints, the parent layout will be reported a size coerced in the Constraints, and the position of the content will be automatically offset to be centered on the space assigned to the child by the parent layout under the assumption that Constraints were respected.

See requiredSizeIn to set a size range. See size to set a preferred size, which is only respected when the incoming constraints allow it.

requiredSizeIn

Cmn

Artifact: androidx.compose.foundation:foundation-layout

View Source

fun Modifier.requiredSizeIn(
    minWidth: Dp = Dp.Unspecified,
    minHeight: Dp = Dp.Unspecified,
    maxWidth: Dp = Dp.Unspecified,
    maxHeight: Dp = Dp.Unspecified
): Modifier

Constrain the width of the content to be between minWidthdp and maxWidthdp, and the height of the content to be between minHeightdp and maxHeightdp. If the content chooses a size that does not satisfy the incoming Constraints, the parent layout will be reported a size coerced in the Constraints, and the position of the content will be automatically offset to be centered on the space assigned to the child by the parent layout under the assumption that Constraints were respected.

requiredWidth

Cmn

Artifact: androidx.compose.foundation:foundation-layout

View Source

Added in 1.0.0

fun Modifier.requiredWidth(intrinsicSize: IntrinsicSize): Modifier

Declare the width of the content to be exactly the same as the min or max intrinsic width of the content. The incoming measurement Constraints will not override this value. If the content intrinsic width does not satisfy the incoming Constraints, the parent layout will be reported a size coerced in the Constraints, and the position of the content will be automatically offset to be centered on the space assigned to the child by the parent layout under the assumption that Constraints were respected.

See height for options of sizing to intrinsic height. See width and widthIn for options to set the preferred width. See requiredWidth and requiredWidthIn for other options to set the required width.

requiredWidth

Cmn

Artifact: androidx.compose.foundation:foundation-layout

View Source

fun Modifier.requiredWidth(width: Dp): Modifier

Declare the width of the content to be exactly widthdp. The incoming measurement Constraints will not override this value. If the content chooses a size that does not satisfy the incoming Constraints, the parent layout will be reported a size coerced in the Constraints, and the position of the content will be automatically offset to be centered on the space assigned to the child by the parent layout under the assumption that Constraints were respected.

See requiredWidthIn and requiredSizeIn to set a size range. See width to set a preferred width, which is only respected when the incoming constraints allow it.

Example usage:

import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.aspectRatio
import androidx.compose.foundation.layout.requiredWidth
import androidx.compose.foundation.layout.width
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.unit.dp

// The result is a 50.dp x 50.dp magenta box centered in a 100.dp x 100.dp space.
// Note that although a previous modifier asked it to be 100.dp width, this
// will not be respected. They would be respected if width was used instead of requiredWidth.
Box(
    Modifier.requiredWidth(100.dp)
        .requiredWidth(50.dp)
        .aspectRatio(1f)
        .background(Color.Magenta)
)

requiredWidthIn

Cmn

Artifact: androidx.compose.foundation:foundation-layout

View Source

fun Modifier.requiredWidthIn(min: Dp = Dp.Unspecified, max: Dp = Dp.Unspecified): Modifier

Constrain the width of the content to be between mindp and maxdp. If the content chooses a size that does not satisfy the incoming Constraints, the parent layout will be reported a size coerced in the Constraints, and the position of the content will be automatically offset to be centered on the space assigned to the child by the parent layout under the assumption that Constraints were respected.

safeContentPadding

Cmn android

Artifact: androidx.compose.foundation:foundation-layout

View Source

fun Modifier.safeContentPadding(): Modifier

Adds padding to accommodate the safe content insets.

Any insets consumed by other insets padding modifiers or consumeWindowInsets on a parent layout will be excluded from the padding. WindowInsets.Companion.safeContent will be consumed for child layouts as well.

For example, if a parent layout uses navigationBarsPadding, the area that the parent layout pads for the status bars will not be padded again by this safeContentPadding modifier.

When used, the WindowInsets will be consumed.

import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.safeContent
import androidx.compose.foundation.layout.safeContentPadding
import androidx.compose.foundation.layout.systemBars
import androidx.compose.foundation.layout.systemBarsPadding
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.core.view.WindowCompat

class SampleActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        WindowCompat.setDecorFitsSystemWindows(window, false)
        super.onCreate(savedInstanceState)
        setContent {
            Box(Modifier.background(Color.Black).systemBarsPadding()) {
                // The app content will only be drawn where there is no possible
                // gesture confusion and content will not be drawn over.
                // The rest will be plain white
                Box(Modifier.background(Color.White).safeContentPadding()) {
                    // app content
                }
            }
        }
    }
}

safeDrawingPadding

Cmn android

Artifact: androidx.compose.foundation:foundation-layout

View Source

fun Modifier.safeDrawingPadding(): Modifier

Adds padding to accommodate the safe drawing insets.

Any insets consumed by other insets padding modifiers or consumeWindowInsets on a parent layout will be excluded from the padding. WindowInsets.Companion.safeDrawing will be consumed for child layouts as well.

For example, if a parent layout uses statusBarsPadding, the area that the parent pads for the status bars will not be padded again by this safeDrawingPadding modifier.

When used, the WindowInsets will be consumed.

import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.safeDrawingPadding
import androidx.compose.foundation.layout.systemBars
import androidx.compose.foundation.layout.systemBarsPadding
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.core.view.WindowCompat

class SampleActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        WindowCompat.setDecorFitsSystemWindows(window, false)
        super.onCreate(savedInstanceState)
        setContent {
            Box(Modifier.background(Color.Black).systemBarsPadding()) {
                // The app content won't have anything drawing over it, but all the
                // background not in the status bars will be white.
                Box(Modifier.background(Color.White).safeDrawingPadding()) {
                    // app content
                }
            }
        }
    }
}

safeGesturesPadding

Cmn android

Artifact: androidx.compose.foundation:foundation-layout

View Source

fun Modifier.safeGesturesPadding(): Modifier

Adds padding to accommodate the safe gestures insets.

Any insets consumed by other insets padding modifiers or consumeWindowInsets on a parent layout will be excluded from the padding. WindowInsets.Companion.safeGestures will be consumed for child layouts as well.

For example, if a parent layout uses navigationBarsPadding, the area that the parent layout pads for the status bars will not be padded again by this safeGesturesPadding modifier.

When used, the WindowInsets will be consumed.

import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.safeGesturesPadding
import androidx.compose.foundation.layout.systemBars
import androidx.compose.foundation.layout.systemBarsPadding
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.core.view.WindowCompat

class SampleActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        WindowCompat.setDecorFitsSystemWindows(window, false)
        super.onCreate(savedInstanceState)
        setContent {
            Box(Modifier.background(Color.Black).systemBarsPadding()) {
                // The app content will only be drawn where there is no possible
                // gesture confusion. The rest will be plain white
                Box(Modifier.background(Color.White).safeGesturesPadding()) {
                    // app content
                }
            }
        }
    }
}

size

Cmn

Artifact: androidx.compose.foundation:foundation-layout

View Source

fun Modifier.size(size: Dp): Modifier

Declare the preferred size of the content to be exactly sizedp square. The incoming measurement Constraints may override this value, forcing the content to be either smaller or larger.

For a modifier that sets the size of the content regardless of the incoming constraints, see Modifier.requiredSize. See width or height to set width or height alone. See widthIn, heightIn or sizeIn to set a preferred size range.

Example usage:

import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.size
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.unit.dp

Box { Box(Modifier.size(100.dp, 100.dp).background(Color.Red)) }

size

Cmn

Artifact: androidx.compose.foundation:foundation-layout

View Source

fun Modifier.size(size: DpSize): Modifier

Declare the preferred size of the content to be exactly size. The incoming measurement Constraints may override this value, forcing the content to be either smaller or larger.

Example usage:

import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.size
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.unit.DpSize
import androidx.compose.ui.unit.dp

Box { Box(Modifier.size(DpSize(100.dp, 100.dp)).background(Color.Red)) }

size

Cmn

Artifact: androidx.compose.foundation:foundation-layout

View Source

fun Modifier.size(width: Dp, height: Dp): Modifier

Declare the preferred size of the content to be exactly widthdp by heightdp. The incoming measurement Constraints may override this value, forcing the content to be either smaller or larger.

Example usage:

import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.size
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.unit.dp

Box { Box(Modifier.size(100.dp, 100.dp).background(Color.Red)) }

sizeIn

Cmn

Artifact: androidx.compose.foundation:foundation-layout

View Source

fun Modifier.sizeIn(
    minWidth: Dp = Dp.Unspecified,
    minHeight: Dp = Dp.Unspecified,
    maxWidth: Dp = Dp.Unspecified,
    maxHeight: Dp = Dp.Unspecified
): Modifier

Constrain the width of the content to be between minWidthdp and maxWidthdp and the height of the content to be between minHeightdp and maxHeightdp as permitted by the incoming measurement Constraints. If the incoming constraints are more restrictive the requested size will obey the incoming constraints and attempt to be as close as possible to the preferred size.

statusBarsPadding

Cmn android

Artifact: androidx.compose.foundation:foundation-layout

View Source

fun Modifier.statusBarsPadding(): Modifier

Adds padding to accommodate the status bars insets.

Any insets consumed by other insets padding modifiers or consumeWindowInsets on a parent layout will be excluded from the padding. WindowInsets.Companion.statusBars will be consumed for child layouts as well.

For example, if a parent layout uses displayCutoutPadding, the area that the parent layout pads for the status bars will not be padded again by this statusBarsPadding modifier.

When used, the WindowInsets will be consumed.

import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.navigationBars
import androidx.compose.foundation.layout.navigationBarsPadding
import androidx.compose.foundation.layout.statusBars
import androidx.compose.foundation.layout.statusBarsPadding
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.core.view.WindowCompat

class SampleActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        WindowCompat.setDecorFitsSystemWindows(window, false)
        super.onCreate(savedInstanceState)
        setContent {
            Box(Modifier.background(Color.Blue).statusBarsPadding()) {
                Box(Modifier.background(Color.Green).navigationBarsPadding()) {
                    // app content
                }
            }
        }
    }
}

systemBarsPadding

Cmn android

Artifact: androidx.compose.foundation:foundation-layout

View Source

fun Modifier.systemBarsPadding(): Modifier

Adds padding to accommodate the system bars insets.

Any insets consumed by other insets padding modifiers or consumeWindowInsets on a parent layout will be excluded from the padding. WindowInsets.Companion.systemBars will be consumed for child layouts as well.

For example, if a parent layout uses statusBarsPadding, the area that the parent layout pads for the status bars will not be padded again by this systemBarsPadding modifier.

When used, the WindowInsets will be consumed.

import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.systemBars
import androidx.compose.foundation.layout.systemBarsPadding
import androidx.compose.ui.Modifier
import androidx.core.view.WindowCompat

class SampleActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        WindowCompat.setDecorFitsSystemWindows(window, false)
        super.onCreate(savedInstanceState)
        setContent {
            Box(Modifier.systemBarsPadding()) {
                // app content
            }
        }
    }
}

systemGesturesPadding

Cmn android

Artifact: androidx.compose.foundation:foundation-layout

View Source

fun Modifier.systemGesturesPadding(): Modifier

Adds padding to accommodate the system gestures insets.

Any insets consumed by other insets padding modifiers or consumeWindowInsets on a parent layout will be excluded from the padding. WindowInsets.Companion.systemGestures will be consumed for child layouts as well.

For example, if a parent layout uses waterfallPadding, the area that the parent layout pads for the status bars will not be padded again by this systemGesturesPadding modifier.

When used, the WindowInsets will be consumed.

import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.systemBars
import androidx.compose.foundation.layout.systemBarsPadding
import androidx.compose.foundation.layout.systemGesturesPadding
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.core.view.WindowCompat

class SampleActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        WindowCompat.setDecorFitsSystemWindows(window, false)
        super.onCreate(savedInstanceState)
        setContent {
            Box(Modifier.background(Color.Blue).systemBarsPadding()) {
                // The app content won't interfere with the system gestures area.
                // It will just be white.
                Box(Modifier.background(Color.White).systemGesturesPadding()) {
                    // app content
                }
            }
        }
    }
}

union

Cmn

Artifact: androidx.compose.foundation:foundation-layout

View Source

Added in 1.2.0

fun WindowInsets.union(insets: WindowInsets): WindowInsets

Returns a WindowInsets that has the maximum values of this WindowInsets and insets.

waterfallPadding

Cmn android

Artifact: androidx.compose.foundation:foundation-layout

View Source

fun Modifier.waterfallPadding(): Modifier

Adds padding to accommodate the waterfall insets.

Any insets consumed by other insets padding modifiers or consumeWindowInsets on a parent layout will be excluded from the padding. WindowInsets.Companion.waterfall will be consumed for child layouts as well.

For example, if a parent layout uses systemGesturesPadding, the area that the parent layout pads for the status bars will not be padded again by this waterfallPadding modifier.

When used, the WindowInsets will be consumed.

import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.systemBars
import androidx.compose.foundation.layout.systemBarsPadding
import androidx.compose.foundation.layout.waterfallPadding
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.core.view.WindowCompat

class SampleActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        WindowCompat.setDecorFitsSystemWindows(window, false)
        super.onCreate(savedInstanceState)
        setContent {
            Box(Modifier.background(Color.Blue).systemBarsPadding()) {
                // The app content shouldn't spill over the edges. They will be green.
                Box(Modifier.background(Color.Green).waterfallPadding()) {
                    // app content
                }
            }
        }
    }
}

width

Cmn

Artifact: androidx.compose.foundation:foundation-layout

View Source

Added in 1.0.0

fun Modifier.width(intrinsicSize: IntrinsicSize): Modifier

Declare the preferred width of the content to be the same as the min or max intrinsic width of the content. The incoming measurement Constraints may override this value, forcing the content to be either smaller or larger.

See height for options of sizing to intrinsic height. Also see width and widthIn for other options to set the preferred width.

Example usage for min intrinsic:

import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.IntrinsicSize
import androidx.compose.foundation.layout.fillMaxHeight
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.size
import androidx.compose.foundation.layout.width
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.unit.dp

// Builds a layout containing three Box having the same width as the widest one.
//
// Here width min intrinsic is adding a width premeasurement pass for the
// Column, whose minimum intrinsic width will correspond to the preferred width of the largest
// Box. Then width min intrinsic will measure the Column with tight width, the
// same as the premeasured minimum intrinsic width, which due to fillMaxWidth will force
// the Box's to use the same width.
Box {
    Column(Modifier.width(IntrinsicSize.Min).fillMaxHeight()) {
        Box(modifier = Modifier.fillMaxWidth().size(20.dp, 10.dp).background(Color.Gray))
        Box(modifier = Modifier.fillMaxWidth().size(30.dp, 10.dp).background(Color.Blue))
        Box(modifier = Modifier.fillMaxWidth().size(10.dp, 10.dp).background(Color.Magenta))
    }
}

Example usage for max intrinsic:

import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.IntrinsicSize
import androidx.compose.foundation.layout.fillMaxHeight
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.width
import androidx.compose.material.Text
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color

// Builds a layout containing three Text boxes having the same width as the widest one.
//
// Here width max intrinsic is adding a width premeasurement pass for the Column,
// whose maximum intrinsic width will correspond to the preferred width of the largest
// Box. Then width max intrinsic will measure the Column with tight width, the
// same as the premeasured maximum intrinsic width, which due to fillMaxWidth modifiers will
// force the Boxs to use the same width.

Box {
    Column(Modifier.width(IntrinsicSize.Max).fillMaxHeight()) {
        Box(Modifier.fillMaxWidth().background(Color.Gray)) { Text("Short text") }
        Box(Modifier.fillMaxWidth().background(Color.Blue)) {
            Text("Extremely long text giving the width of its siblings")
        }
        Box(Modifier.fillMaxWidth().background(Color.Magenta)) { Text("Medium length text") }
    }
}

width

Cmn

Artifact: androidx.compose.foundation:foundation-layout

View Source

fun Modifier.width(width: Dp): Modifier

Declare the preferred width of the content to be exactly widthdp. The incoming measurement Constraints may override this value, forcing the content to be either smaller or larger.

For a modifier that sets the width of the content regardless of the incoming constraints see Modifier.requiredWidth. See height or size to set other preferred dimensions. See widthIn, heightIn or sizeIn to set a preferred size range.

Example usage:

import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.aspectRatio
import androidx.compose.foundation.layout.width
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.unit.dp

Box { Box(Modifier.width(100.dp).aspectRatio(1f).background(Color.Magenta)) }

widthIn

Cmn

Artifact: androidx.compose.foundation:foundation-layout

View Source

fun Modifier.widthIn(min: Dp = Dp.Unspecified, max: Dp = Dp.Unspecified): Modifier

Constrain the width of the content to be between mindp and maxdp as permitted by the incoming measurement Constraints. If the incoming constraints are more restrictive the requested size will obey the incoming constraints and attempt to be as close as possible to the preferred size.

windowInsetsBottomHeight

Cmn

Artifact: androidx.compose.foundation:foundation-layout

View Source

Added in 1.2.0

fun Modifier.windowInsetsBottomHeight(insets: WindowInsets): Modifier

Sets the height to that of insets at the bottom of the screen.

When used, the android.view.WindowInsets will respect the consumed insets from windowInsetsPadding and consumeWindowInsets, but won't consume any insets.

import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.WindowInsets
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.navigationBars
import androidx.compose.foundation.layout.windowInsetsTopHeight
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.core.view.WindowCompat

class SampleActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        WindowCompat.setDecorFitsSystemWindows(window, false)
        super.onCreate(savedInstanceState)
        setContent {
            Box(Modifier.fillMaxSize()) {
                // Background for navigation bar at the bottom
                Box(
                    Modifier.windowInsetsTopHeight(WindowInsets.navigationBars)
                        .fillMaxWidth()
                        .align(Alignment.BottomCenter)
                        .background(Color.Red)
                )
                // app content
            }
        }
    }
}

windowInsetsEndWidth

Cmn

Artifact: androidx.compose.foundation:foundation-layout

View Source

Added in 1.2.0

fun Modifier.windowInsetsEndWidth(insets: WindowInsets): Modifier

Sets the width to that of insets at the end of the screen, using either left or right, depending on the LayoutDirection.

When used, the android.view.WindowInsets will respect the consumed insets from windowInsetsPadding and consumeWindowInsets, but won't consume any insets.

import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.WindowInsets
import androidx.compose.foundation.layout.fillMaxHeight
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.navigationBars
import androidx.compose.foundation.layout.windowInsetsEndWidth
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.core.view.WindowCompat

class SampleActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        WindowCompat.setDecorFitsSystemWindows(window, false)
        super.onCreate(savedInstanceState)
        setContent {
            Box(Modifier.fillMaxSize()) {
                // Background for navigation bar at the end
                Box(
                    Modifier.windowInsetsEndWidth(WindowInsets.navigationBars)
                        .fillMaxHeight()
                        .align(Alignment.CenterEnd)
                        .background(Color.Red)
                )
                // app content
            }
        }
    }
}

windowInsetsPadding

Cmn

Artifact: androidx.compose.foundation:foundation-layout

View Source

Added in 1.2.0

fun Modifier.windowInsetsPadding(insets: WindowInsets): Modifier

Adds padding so that the content doesn't enter insets space.

Any insets consumed by other insets padding modifiers or consumeWindowInsets on a parent layout will be excluded from insets. insets will be consumed for child layouts as well.

For example, if an ancestor uses statusBarsPadding and this modifier uses WindowInsets.Companion.systemBars, the portion of the system bars that the status bars uses will not be padded again by this modifier.

import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.WindowInsets
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.ime
import androidx.compose.foundation.layout.systemBars
import androidx.compose.foundation.layout.union
import androidx.compose.foundation.layout.windowInsetsPadding
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.core.view.WindowCompat

class SampleActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        WindowCompat.setDecorFitsSystemWindows(window, false)
        super.onCreate(savedInstanceState)
        setContent {
            val insets = WindowInsets.systemBars.union(WindowInsets.ime)
            Box(Modifier.background(Color.White).fillMaxSize().windowInsetsPadding(insets)) {
                // app content
            }
        }
    }
}

See also
`WindowInsets`

windowInsetsStartWidth

Cmn

Artifact: androidx.compose.foundation:foundation-layout

View Source

Added in 1.2.0

fun Modifier.windowInsetsStartWidth(insets: WindowInsets): Modifier

Sets the width to that of insets at the start of the screen, using either left or right, depending on the LayoutDirection.

When used, the android.view.WindowInsets will respect the consumed insets from windowInsetsPadding and consumeWindowInsets, but won't consume any insets.

import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.WindowInsets
import androidx.compose.foundation.layout.fillMaxHeight
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.navigationBars
import androidx.compose.foundation.layout.windowInsetsStartWidth
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.core.view.WindowCompat

class SampleActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        WindowCompat.setDecorFitsSystemWindows(window, false)
        super.onCreate(savedInstanceState)
        setContent {
            Box(Modifier.fillMaxSize()) {
                // Background for navigation bar at the start
                Box(
                    Modifier.windowInsetsStartWidth(WindowInsets.navigationBars)
                        .fillMaxHeight()
                        .align(Alignment.CenterStart)
                        .background(Color.Red)
                )
                // app content
            }
        }
    }
}

windowInsetsTopHeight

Cmn

Artifact: androidx.compose.foundation:foundation-layout

View Source

Added in 1.2.0

fun Modifier.windowInsetsTopHeight(insets: WindowInsets): Modifier

Sets the height to that of insets at the top of the screen.

When used, the android.view.WindowInsets will respect the consumed insets from windowInsetsPadding and consumeWindowInsets, but won't consume any insets.

import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.WindowInsets
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.statusBars
import androidx.compose.foundation.layout.windowInsetsTopHeight
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.core.view.WindowCompat

class SampleActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        WindowCompat.setDecorFitsSystemWindows(window, false)
        super.onCreate(savedInstanceState)
        setContent {
            Box(Modifier.fillMaxSize()) {
                // Background for status bar at the top
                Box(
                    Modifier.windowInsetsTopHeight(WindowInsets.statusBars)
                        .fillMaxWidth()
                        .align(Alignment.TopCenter)
                        .background(Color.Red)
                )
                // app content
            }
        }
    }
}

wrapContentHeight

Cmn

Artifact: androidx.compose.foundation:foundation-layout

View Source

Added in 1.0.0

fun Modifier.wrapContentHeight(
    align: Alignment.Vertical = Alignment.CenterVertically,
    unbounded: Boolean = false
): Modifier

Allow the content to measure at its desired height without regard for the incoming measurement minimum height constraint, and, if unbounded is true, also without regard for the incoming measurement maximum height constraint. If the content's measured size is smaller than the minimum height constraint, align it within that minimum height space. If the content's measured size is larger than the maximum height constraint (only possible when unbounded is true), align over the maximum height space.

Example usage:

import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.size
import androidx.compose.foundation.layout.wrapContentHeight
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.unit.dp

// Here the result will be a 50.dp x 20.dp blue box centered vertically in a 50.dp x 50.dp
// space. Because of the size modifier, if wrapContentHeight did not exist,
// the blue rectangle would actually be 50.dp x 50.dp to satisfy the size set by the modifier.
// However, because we provide wrapContentHeight, the blue rectangle is specified to be wrap
// content in height - if the desired height is smaller than 50.dp, it will be centered
// vertically in this space. Therefore the 50.dp x 20.dp is centered vertically in the space.
Box(
    Modifier.size(50.dp)
        .wrapContentHeight(Alignment.CenterVertically)
        .height(20.dp)
        .background(Color.Blue)
)

wrapContentSize

Cmn

Artifact: androidx.compose.foundation:foundation-layout

View Source

Added in 1.0.0

fun Modifier.wrapContentSize(
    align: Alignment = Alignment.Center,
    unbounded: Boolean = false
): Modifier

Allow the content to measure at its desired size without regard for the incoming measurement minimum width or minimum height constraints, and, if unbounded is true, also without regard for the incoming maximum constraints. If the content's measured size is smaller than the minimum size constraint, align it within that minimum sized space. If the content's measured size is larger than the maximum size constraint (only possible when unbounded is true), align within the maximum space.

Example usage:

import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.size
import androidx.compose.foundation.layout.sizeIn
import androidx.compose.foundation.layout.wrapContentSize
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.unit.dp

// Here the result will be a 20.dp x 20.dp blue box top-centered in a 40.dp x 40.dp space.
// Because of the sizeIn modifier, if wrapContentSize did not exist, the blue rectangle
// would actually be 40.dp x 40.dp to satisfy the min size set by the modifier. However,
// because we provide wrapContentSize, the blue rectangle is specified to be wrap
// content - if the desired size is smaller than 40.dp x 40.dp, it will be top-centered in
// this space. Therefore the 20.dp x 20.dp is top-centered in the space.
Box(
    Modifier.sizeIn(minWidth = 40.dp, minHeight = 40.dp)
        .wrapContentSize(Alignment.TopCenter)
        .size(20.dp)
        .background(Color.Blue)
)

wrapContentWidth

Cmn

Artifact: androidx.compose.foundation:foundation-layout

View Source

Added in 1.0.0

fun Modifier.wrapContentWidth(
    align: Alignment.Horizontal = Alignment.CenterHorizontally,
    unbounded: Boolean = false
): Modifier

Allow the content to measure at its desired width without regard for the incoming measurement minimum width constraint, and, if unbounded is true, also without regard for the incoming measurement maximum width constraint. If the content's measured size is smaller than the minimum width constraint, align it within that minimum width space. If the content's measured size is larger than the maximum width constraint (only possible when unbounded is true), align over the maximum width space.

Example usage:

import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.size
import androidx.compose.foundation.layout.width
import androidx.compose.foundation.layout.wrapContentWidth
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.unit.dp

// Here the result will be a 20.dp x 50.dp blue box centered vertically in a 50.dp x 50.dp
// space. Because of the size modifier, if wrapContentWidth did not exist,
// the blue rectangle would actually be 50.dp x 50.dp to satisfy the size set by the modifier.
// However, because we provide wrapContentWidth, the blue rectangle is specified to be wrap
// content in width - if the desired width is smaller than 50.dp, it will be centered
// horizontally in this space. Therefore the 50.dp x 20.dp is centered horizontally
// in the space.
Box(
    Modifier.size(50.dp)
        .wrapContentWidth(Alignment.CenterHorizontally)
        .width(20.dp)
        .background(Color.Blue)
)

Extension properties

areNavigationBarsVisible

android

Artifact: androidx.compose.foundation:foundation-layout

View Source

@ExperimentalLayoutApi
val WindowInsets.Companion.areNavigationBarsVisible: Boolean

true when the navigationBars are being displayed, irrespective of whether they intersects with the Window.

areStatusBarsVisible

android

Artifact: androidx.compose.foundation:foundation-layout

View Source

@ExperimentalLayoutApi
val WindowInsets.Companion.areStatusBarsVisible: Boolean

true when the statusBars are being displayed, irrespective of whether they intersects with the Window.

areSystemBarsVisible

android

Artifact: androidx.compose.foundation:foundation-layout

View Source

@ExperimentalLayoutApi
val WindowInsets.Companion.areSystemBarsVisible: Boolean

true when the systemBars are being displayed, irrespective of whether they intersects with the Window.

captionBar

Cmn android

Artifact: androidx.compose.foundation:foundation-layout

View Source

val WindowInsets.Companion.captionBar: WindowInsets

An insets type representing the window of a caption bar.

captionBarIgnoringVisibility

android

Artifact: androidx.compose.foundation:foundation-layout

View Source

@ExperimentalLayoutApi
val WindowInsets.Companion.captionBarIgnoringVisibility: WindowInsets

The insets that the WindowInsetsCompat.Type.captionBar will consume if shown. If it cannot be shown then this will be empty.

consumeWindowInsets

android

Artifact: androidx.compose.foundation:foundation-layout

View Source

var AbstractComposeView.consumeWindowInsets: Boolean

Indicates whether access to WindowInsets within the content should consume the Android android.view.WindowInsets. The default value is false, meaning that access to WindowInsets.Companion will not consume all the Android WindowInsets and instead adjust the insets based on the position of child Views.

This property should be set prior to first composition.

displayCutout

Cmn android

Artifact: androidx.compose.foundation:foundation-layout

View Source

val WindowInsets.Companion.displayCutout: WindowInsets

This WindowInsets represents the area with the display cutout (e.g. for camera).

ime

Cmn android

Artifact: androidx.compose.foundation:foundation-layout

View Source

val WindowInsets.Companion.ime: WindowInsets

An insets type representing the window of the software keyboard.

imeAnimationSource

android

Artifact: androidx.compose.foundation:foundation-layout

View Source

@ExperimentalLayoutApi
val WindowInsets.Companion.imeAnimationSource: WindowInsets

The WindowInsets for the IME before the IME started animating in. The current animated value is WindowInsets.Companion.ime.

This will be the same as imeAnimationTarget when there is no IME animation in progress.

imeAnimationTarget

android

Artifact: androidx.compose.foundation:foundation-layout

View Source

@ExperimentalLayoutApi
val WindowInsets.Companion.imeAnimationTarget: WindowInsets

The WindowInsets for the IME when the animation completes, if it is allowed to complete successfully. The current animated value is WindowInsets.Companion.ime.

This will be the same as imeAnimationSource when there is no IME animation in progress.

isCaptionBarVisible

android

Artifact: androidx.compose.foundation:foundation-layout

View Source

@ExperimentalLayoutApi
val WindowInsets.Companion.isCaptionBarVisible: Boolean

true when the caption bar is being displayed, irrespective of whether it intersects with the Window.

isImeVisible

android

Artifact: androidx.compose.foundation:foundation-layout

View Source

@ExperimentalLayoutApi
val WindowInsets.Companion.isImeVisible: Boolean

true when the soft keyboard is being displayed, irrespective of whether it intersects with the Window.

isTappableElementVisible

android

Artifact: androidx.compose.foundation:foundation-layout

View Source

@ExperimentalLayoutApi
val WindowInsets.Companion.isTappableElementVisible: Boolean

true when the tappableElement is being displayed, irrespective of whether they intersects with the Window.

mandatorySystemGestures

Cmn android

Artifact: androidx.compose.foundation:foundation-layout

View Source

val WindowInsets.Companion.mandatorySystemGestures: WindowInsets

These insets represent the space where system gestures have priority over application gestures.

navigationBars

Cmn android

Artifact: androidx.compose.foundation:foundation-layout

View Source

val WindowInsets.Companion.navigationBars: WindowInsets

These insets represent where system UI places navigation bars. Interactive UI should avoid the navigation bars area.

navigationBarsIgnoringVisibility

android

Artifact: androidx.compose.foundation:foundation-layout

View Source

@ExperimentalLayoutApi
val WindowInsets.Companion.navigationBarsIgnoringVisibility: WindowInsets

The insets that WindowInsetsCompat.Type.navigationBars will consume if shown. These insets represent where system UI places navigation bars. Interactive UI should avoid the navigation bars area. If navigation bars cannot be shown, then this will be empty.

safeContent

Cmn android

Artifact: androidx.compose.foundation:foundation-layout

View Source

val WindowInsets.Companion.safeContent: WindowInsets

The insets that include all areas that may be drawn over or have gesture confusion, including everything in safeDrawing and safeGestures.

safeDrawing

Cmn android

Artifact: androidx.compose.foundation:foundation-layout

View Source

val WindowInsets.Companion.safeDrawing: WindowInsets

The insets that include areas where content may be covered by other drawn content. This includes all systemBars, displayCutout, and ime.

safeGestures

Cmn android

Artifact: androidx.compose.foundation:foundation-layout

View Source

val WindowInsets.Companion.safeGestures: WindowInsets

The insets that include areas where gestures may be confused with other input, including systemGestures, mandatorySystemGestures, waterfall, and tappableElement.

statusBars

Cmn android

Artifact: androidx.compose.foundation:foundation-layout

View Source

val WindowInsets.Companion.statusBars: WindowInsets

These insets represent status bar.

statusBarsIgnoringVisibility

android

Artifact: androidx.compose.foundation:foundation-layout

View Source

@ExperimentalLayoutApi
val WindowInsets.Companion.statusBarsIgnoringVisibility: WindowInsets

The insets that WindowInsetsCompat.Type.statusBars will consume if shown. If the status bar can never be shown, then this will be empty.

systemBars

Cmn android

Artifact: androidx.compose.foundation:foundation-layout

View Source

val WindowInsets.Companion.systemBars: WindowInsets

These insets represent all system bars. Includes statusBars, captionBar as well as navigationBars, but not ime.

systemBarsIgnoringVisibility

android

Artifact: androidx.compose.foundation:foundation-layout

View Source

@ExperimentalLayoutApi
val WindowInsets.Companion.systemBarsIgnoringVisibility: WindowInsets

The insets that WindowInsetsCompat.Type.systemBars will consume if shown.

If system bars can never be shown, then this will be empty.

systemGestures

Cmn android

Artifact: androidx.compose.foundation:foundation-layout

View Source

val WindowInsets.Companion.systemGestures: WindowInsets

The systemGestures insets represent the area of a window where system gestures have priority and may consume some or all touch input, e.g. due to the system bar occupying it, or it being reserved for touch-only gestures.

tappableElement

Cmn android

Artifact: androidx.compose.foundation:foundation-layout

View Source

val WindowInsets.Companion.tappableElement: WindowInsets

Returns the tappable element insets.

tappableElementIgnoringVisibility

android

Artifact: androidx.compose.foundation:foundation-layout

View Source

@ExperimentalLayoutApi
val WindowInsets.Companion.tappableElementIgnoringVisibility: WindowInsets

The insets that WindowInsetsCompat.Type.tappableElement will consume if active.

If there are never tappable elements then this is empty.

waterfall

Cmn android

Artifact: androidx.compose.foundation:foundation-layout

View Source

val WindowInsets.Companion.waterfall: WindowInsets

The insets for the curved areas in a waterfall display.