Scope for the children of Row.

Summary

Public functions

Modifier

Align the element vertically within the Row.

Cmn
Modifier
Modifier.alignBy(alignmentLineBlock: (Measured) -> Int)

Position the element vertically such that the alignment line for the content as determined by alignmentLineBlock aligns with sibling elements also configured to alignBy.

Cmn
Modifier

Position the element vertically such that its alignmentLine aligns with sibling elements also configured to alignBy.

Cmn
Modifier

Position the element vertically such that its first baseline aligns with sibling elements also configured to alignByBaseline or alignBy.

Cmn
Modifier
Modifier.weight(
    weight: @FloatRange(from = 0.0, fromInclusive = false) Float,
    fill: Boolean
)

Size the element's width proportional to its weight relative to other weighted sibling elements in the Row.

Cmn

Extension functions

Unit
@Composable
RowScope.AnimatedVisibility(
    visible: Boolean,
    modifier: Modifier,
    enter: EnterTransition,
    exit: ExitTransition,
    label: String,
    content: @Composable AnimatedVisibilityScope.() -> Unit
)

RowScope.AnimatedVisibility composable animates the appearance and disappearance of its content when the AnimatedVisibility is in a Row.

Cmn
Unit
@Composable
RowScope.AnimatedVisibility(
    visibleState: MutableTransitionState<Boolean>,
    modifier: Modifier,
    enter: EnterTransition,
    exit: ExitTransition,
    label: String,
    content: @Composable AnimatedVisibilityScope.() -> Unit
)

RowScope.AnimatedVisibility composable animates the appearance and disappearance of its content as visibleState's targetState changes.

Cmn
Unit
@Composable
RowScope.BottomNavigationItem(
    selected: Boolean,
    onClick: () -> Unit,
    icon: @Composable () -> Unit,
    modifier: Modifier,
    enabled: Boolean,
    label: (@Composable () -> Unit)?,
    alwaysShowLabel: Boolean,
    interactionSource: MutableInteractionSource?,
    selectedContentColor: Color,
    unselectedContentColor: Color
)

Material Design bottom navigation item.

Cmn
Unit
@Composable
RowScope.NavigationBarItem(
    selected: Boolean,
    onClick: () -> Unit,
    icon: @Composable () -> Unit,
    modifier: Modifier,
    enabled: Boolean,
    label: (@Composable () -> Unit)?,
    alwaysShowLabel: Boolean,
    colors: NavigationBarItemColors,
    interactionSource: MutableInteractionSource?
)

Material Design navigation bar item.

Cmn

Public functions

fun Modifier.align(alignment: Alignment.Vertical): Modifier

Align the element vertically within the Row. This alignment will have priority over the Row's verticalAlignment parameter.

Example usage:

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

Row(Modifier.fillMaxHeight()) {
    // The child with no align modifier is positioned by default so that its top edge is
    // aligned to the top of the vertical axis.
    Box(Modifier.size(80.dp, 40.dp).background(Color.Magenta))
    // Gravity.Top, the child will be positioned so that its top edge is aligned to the top
    // of the vertical axis.
    Box(
        Modifier.size(80.dp, 40.dp)
            .align(Alignment.Top)
            .background(Color.Red)
    )
    // Gravity.Center, the child will be positioned so that its center is in the middle of
    // the vertical axis.
    Box(
        Modifier.size(80.dp, 40.dp)
            .align(Alignment.CenterVertically)
            .background(Color.Yellow)
    )
    // Gravity.Bottom, the child will be positioned so that its bottom edge is aligned to the
    // bottom of the vertical axis.
    Box(
        Modifier.size(80.dp, 40.dp)
            .align(Alignment.Bottom)
            .background(Color.Green)
    )
}
fun Modifier.alignBy(alignmentLineBlock: (Measured) -> Int): Modifier

Position the element vertically such that the alignment line for the content as determined by alignmentLineBlock aligns with sibling elements also configured to alignBy. alignBy is a form of align, so both modifiers will not work together if specified for the same layout. Within a Row, all components with alignBy will align vertically using the specified HorizontalAlignmentLines or values obtained from alignmentLineBlock, forming a sibling group. At least one element of the sibling group will be placed as it had Alignment.Top align in Row, and the alignment of the other siblings will be then determined such that the alignment lines coincide. Note that if only one element in a Row has the alignBy modifier specified the element will be positioned as if it had Alignment.Top align.

Example usage:

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

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)
    )
}
fun Modifier.alignBy(alignmentLine: HorizontalAlignmentLine): Modifier

Position the element vertically such that its alignmentLine aligns with sibling elements also configured to alignBy. alignBy is a form of align, so both modifiers will not work together if specified for the same layout. alignBy can be used to align two layouts by baseline inside a Row, using alignBy(FirstBaseline). Within a Row, all components with alignBy will align vertically using the specified HorizontalAlignmentLines or values provided using the other alignBy overload, forming a sibling group. At least one element of the sibling group will be placed as it had Alignment.Top align in Row, and the alignment of the other siblings will be then determined such that the alignment lines coincide. Note that if only one element in a Row has the alignBy modifier specified the element will be positioned as if it had Alignment.Top align.

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

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)
    )
}
See also
alignByBaseline

Example usage:

alignByBaseline

fun Modifier.alignByBaseline(): Modifier

Position the element vertically such that its first baseline aligns with sibling elements also configured to alignByBaseline or alignBy. This modifier is a form of align, so both modifiers will not work together if specified for the same layout. alignByBaseline is a particular case of alignBy. See alignBy for more details.

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

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)
    )
}
See also
alignBy

Example usage:

fun Modifier.weight(
    weight: @FloatRange(from = 0.0, fromInclusive = false) Float,
    fill: Boolean = true
): Modifier

Size the element's width proportional to its weight relative to other weighted sibling elements in the Row. The parent will divide the horizontal space remaining after measuring unweighted child elements and distribute it according to this weight. When fill is true, the element will be forced to occupy the whole width allocated to it. Otherwise, the element is allowed to be smaller - this will result in Row being smaller, as the unused allocated width will not be redistributed to other siblings.

Parameters
weight: @FloatRange(from = 0.0, fromInclusive = false) Float

The proportional width to give to this element, as related to the total of all weighted siblings. Must be positive.

fill: Boolean = true

When true, the element will occupy the whole width allocated.

Extension functions

AnimatedVisibility

@Composable
fun RowScope.AnimatedVisibility(
    visible: Boolean,
    modifier: Modifier = Modifier,
    enter: EnterTransition = fadeIn() + expandHorizontally(),
    exit: ExitTransition = fadeOut() + shrinkHorizontally(),
    label: String = "AnimatedVisibility",
    content: @Composable AnimatedVisibilityScope.() -> Unit
): Unit

RowScope.AnimatedVisibility composable animates the appearance and disappearance of its content when the AnimatedVisibility is in a Row. The default animations are tailored specific to the Row layout. See more details below.

Different EnterTransitions and ExitTransitions can be defined in enter and exit for the appearance and disappearance animation. There are 4 types of EnterTransition and ExitTransition: Fade, Expand/Shrink, Scale, and Slide. The enter transitions can be combined using +. Same for exit transitions. The order of the combination does not matter, as the transition animations will start simultaneously. See EnterTransition and ExitTransition for details on the three types of transition.

The default enter and exit transition is configured based on the horizontal layout of a Row. enter defaults to a combination of fading in and expanding the content horizontally. (The end of the content will be the leading edge as the content expands to its full width.) And exit defaults to shrinking the content horizontally with the end of the content being the leading edge while fading out. The expanding and shrinking will likely also animate the parent and siblings in the row since they rely on the size of appearing/disappearing content.

Aside from these three types of EnterTransition and ExitTransition, AnimatedVisibility also supports custom enter/exit animations. Some use cases may benefit from custom enter/exit animations on shape, scale, color, etc. Custom enter/exit animations can be created using the Transition<EnterExitState> object from the AnimatedVisibilityScope (i.e. AnimatedVisibilityScope.transition). See EnterExitState for an example of custom animations. These custom animations will be running along side of the built-in animations specified in enter and exit. In cases where the enter/exit animation needs to be completely customized, enter and/or exit can be specified as EnterTransition.None and/or ExitTransition.None as needed. AnimatedVisibility will wait until all of enter/exit animations to finish before it considers itself idle. content will only be removed after all the (built-in and custom) exit animations have finished.

AnimatedVisibility creates a custom Layout for its content. The size of the custom layout is determined by the largest width and largest height of the children. All children will be aligned to the top start of the Layout.

Note: Once the exit transition is finished, the content composable will be removed from the tree, and disposed. If there's a need to observe the state change of the enter/exit transition and follow up additional action (e.g. remove data, sequential animation, etc), consider the AnimatedVisibility API variant that takes a MutableTransitionState parameter.

Here's an example of using RowScope.AnimatedVisibility in a Row:

import androidx.compose.animation.AnimatedVisibility
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.layout.requiredHeight
import androidx.compose.material.FloatingActionButton
import androidx.compose.material.Icon
import androidx.compose.material.Text
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember

var expanded by remember { mutableStateOf(true) }
FloatingActionButton(
    onClick = { expanded = !expanded },
    modifier = Modifier.align(Alignment.CenterHorizontally)
) {
    Row(Modifier.padding(start = 12.dp, end = 12.dp)) {
        Icon(
            Icons.Default.Favorite,
            contentDescription = "Favorite",
            modifier = Modifier.align(Alignment.CenterVertically)
        )
        AnimatedVisibility(
            expanded,
            modifier = Modifier.align(Alignment.CenterVertically)
        ) {
            Text(modifier = Modifier.padding(start = 12.dp), text = "Favorite")
        }
    }
}
Spacer(Modifier.requiredHeight(20.dp))
Parameters
visible: Boolean

defines whether the content should be visible

modifier: Modifier = Modifier

modifier for the Layout created to contain the content

enter: EnterTransition = fadeIn() + expandHorizontally()

EnterTransition(s) used for the appearing animation, fading in while expanding horizontally by default

exit: ExitTransition = fadeOut() + shrinkHorizontally()

ExitTransition(s) used for the disappearing animation, fading out while shrinking horizontally by default

content: @Composable AnimatedVisibilityScope.() -> Unit

Content to appear or disappear based on the value of visible

AnimatedVisibility

@Composable
fun RowScope.AnimatedVisibility(
    visibleState: MutableTransitionState<Boolean>,
    modifier: Modifier = Modifier,
    enter: EnterTransition = expandHorizontally() + fadeIn(),
    exit: ExitTransition = shrinkHorizontally() + fadeOut(),
    label: String = "AnimatedVisibility",
    content: @Composable AnimatedVisibilityScope.() -> Unit
): Unit

RowScope.AnimatedVisibility composable animates the appearance and disappearance of its content as visibleState's targetState changes. The default enter and exit transitions are tailored specific to the Row layout. See more details below. The visibleState can also be used to observe the state of AnimatedVisibility. For example: visibleState.isIdle indicates whether all the animations have finished in AnimatedVisibility, and visibleState.currentState returns the initial state of the current animations.

Different EnterTransitions and ExitTransitions can be defined in enter and exit for the appearance and disappearance animation. There are 4 types of EnterTransition and ExitTransition: Fade, Expand/Shrink, Scale and Slide. The enter transitions can be combined using +. Same for exit transitions. The order of the combination does not matter, as the transition animations will start simultaneously. See EnterTransition and ExitTransition for details on the three types of transition.

The default enter and exit transition is configured based on the horizontal layout of a Row. enter defaults to a combination of fading in and expanding the content horizontally. (The end of the content will be the leading edge as the content expands to its full width.) And exit defaults to shrinking the content horizontally with the end of the content being the leading edge while fading out. The expanding and shrinking will likely also animate the parent and siblings in the row since they rely on the size of appearing/disappearing content.

Aside from these three types of EnterTransition and ExitTransition, AnimatedVisibility also supports custom enter/exit animations. Some use cases may benefit from custom enter/exit animations on shape, scale, color, etc. Custom enter/exit animations can be created using the Transition<EnterExitState> object from the AnimatedVisibilityScope (i.e. AnimatedVisibilityScope.transition). See EnterExitState for an example of custom animations. These custom animations will be running along side of the built-in animations specified in enter and exit. In cases where the enter/exit animation needs to be completely customized, enter and/or exit can be specified as EnterTransition.None and/or ExitTransition.None as needed. AnimatedVisibility will wait until all of enter/exit animations to finish before it considers itself idle. content will only be removed after all the (built-in and custom) exit animations have finished.

AnimatedVisibility creates a custom Layout for its content. The size of the custom layout is determined by the largest width and largest height of the children. All children will be aligned to the top start of the Layout.

Note: Once the exit transition is finished, the content composable will be removed from the tree, and disposed. Both currentState and targetState will be false for visibleState.

Parameters
visibleState: MutableTransitionState<Boolean>

defines whether the content should be visible

modifier: Modifier = Modifier

modifier for the Layout created to contain the content

enter: EnterTransition = expandHorizontally() + fadeIn()

EnterTransition(s) used for the appearing animation, fading in while expanding vertically by default

exit: ExitTransition = shrinkHorizontally() + fadeOut()

ExitTransition(s) used for the disappearing animation, fading out while shrinking vertically by default

content: @Composable AnimatedVisibilityScope.() -> Unit

Content to appear or disappear based on the value of visibleState

BottomNavigationItem

@Composable
fun RowScope.BottomNavigationItem(
    selected: Boolean,
    onClick: () -> Unit,
    icon: @Composable () -> Unit,
    modifier: Modifier = Modifier,
    enabled: Boolean = true,
    label: (@Composable () -> Unit)? = null,
    alwaysShowLabel: Boolean = true,
    interactionSource: MutableInteractionSource? = null,
    selectedContentColor: Color = LocalContentColor.current,
    unselectedContentColor: Color = selectedContentColor.copy(alpha = ContentAlpha.medium)
): Unit

Material Design bottom navigation item.

The recommended configuration for a BottomNavigationItem depends on how many items there are inside a BottomNavigation:

  • Three destinations: Display icons and text labels for all destinations.

  • Four destinations: Active destinations display an icon and text label. Inactive destinations display icons, and text labels are recommended.

  • Five destinations: Active destinations display an icon and text label. Inactive destinations use icons, and use text labels if space permits.

A BottomNavigationItem always shows text labels (if it exists) when selected. Showing text labels if not selected is controlled by alwaysShowLabel.

Parameters
selected: Boolean

whether this item is selected

onClick: () -> Unit

the callback to be invoked when this item is selected

icon: @Composable () -> Unit

icon for this item, typically this will be an Icon

modifier: Modifier = Modifier

optional Modifier for this item

enabled: Boolean = true

controls the enabled state of this item. When false, this item will not be clickable and will appear disabled to accessibility services.

label: (@Composable () -> Unit)? = null

optional text label for this item

alwaysShowLabel: Boolean = true

whether to always show the label for this item. If false, the label will only be shown when this item is selected.

interactionSource: MutableInteractionSource? = null

an optional hoisted MutableInteractionSource for observing and emitting Interactions for this item. You can use this to change the item's appearance or preview the item in different states. Note that if null is provided, interactions will still happen internally.

selectedContentColor: Color = LocalContentColor.current

the color of the text label and icon when this item is selected, and the color of the ripple.

unselectedContentColor: Color = selectedContentColor.copy(alpha = ContentAlpha.medium)

the color of the text label and icon when this item is not selected

NavigationBarItem

@Composable
fun RowScope.NavigationBarItem(
    selected: Boolean,
    onClick: () -> Unit,
    icon: @Composable () -> Unit,
    modifier: Modifier = Modifier,
    enabled: Boolean = true,
    label: (@Composable () -> Unit)? = null,
    alwaysShowLabel: Boolean = true,
    colors: NavigationBarItemColors = NavigationBarItemDefaults.colors(),
    interactionSource: MutableInteractionSource? = null
): Unit

Material Design navigation bar item.

Navigation bars offer a persistent and convenient way to switch between primary destinations in an app.

The recommended configuration for a NavigationBarItem depends on how many items there are inside a NavigationBar:

  • Three destinations: Display icons and text labels for all destinations.

  • Four destinations: Active destinations display an icon and text label. Inactive destinations display icons, and text labels are recommended.

  • Five destinations: Active destinations display an icon and text label. Inactive destinations use icons, and use text labels if space permits.

A NavigationBarItem always shows text labels (if it exists) when selected. Showing text labels if not selected is controlled by alwaysShowLabel.

Parameters
selected: Boolean

whether this item is selected

onClick: () -> Unit

called when this item is clicked

icon: @Composable () -> Unit

icon for this item, typically an Icon

modifier: Modifier = Modifier

the Modifier to be applied to this item

enabled: Boolean = true

controls the enabled state of this item. When false, this component will not respond to user input, and it will appear visually disabled and disabled to accessibility services.

label: (@Composable () -> Unit)? = null

optional text label for this item

alwaysShowLabel: Boolean = true

whether to always show the label for this item. If false, the label will only be shown when this item is selected.

colors: NavigationBarItemColors = NavigationBarItemDefaults.colors()

NavigationBarItemColors that will be used to resolve the colors used for this item in different states. See NavigationBarItemDefaults.colors.

interactionSource: MutableInteractionSource? = null

an optional hoisted MutableInteractionSource for observing and emitting Interactions for this item. You can use this to change the item's appearance or preview the item in different states. Note that if null is provided, interactions will still happen internally.