AnimatedVisibility

Component in Compose Animation

[AnimatedVisibility] composable animates the appearance and disappearance of its content, as [visible] value changes. Different [EnterTransition]s and [ExitTransition]s 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.

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 the second sample code snippet below for example. These custom animations will be running alongside 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.

By default, the enter transition will be a combination of [fadeIn] and [expandIn] of the content from the bottom end. And the exit transition will be shrinking the content towards the bottom end while fading out (i.e. [fadeOut] + [shrinkOut]). The expanding and shrinking will likely also animate the parent and siblings if they rely on the size of appearing/disappearing content. When the [AnimatedVisibility] composable is put in a [Row] or a [Column], the default enter and exit transitions are tailored to that particular container. See [RowScope.AnimatedVisibility] and [ColumnScope.AnimatedVisibility] for details.

Last updated: 2024-10-22 13:47

Installation

dependencies {
   implementation("androidx.compose.animation:animation:1.8.0-alpha04")
}

Overloads

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

Parameters

name	description
visible	defines whether the content should be visible
modifier	modifier for the [Layout] created to contain the [content]
enter	EnterTransition(s) used for the appearing animation, fading in while expanding by default
exit	ExitTransition(s) used for the disappearing animation, fading out while shrinking by default
content	Content to appear or disappear based on the value of [visible]

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

Parameters

name	description
visibleState	defines whether the content should be visible
modifier	modifier for the [Layout] created to contain the [content]
enter	EnterTransition(s) used for the appearing animation, fading in while expanding by default
exit	ExitTransition(s) used for the disappearing animation, fading out while shrinking by default
content	Content to appear or disappear based on the value of [visibleState]

Code Examples

FullyLoadedTransition

@OptIn(ExperimentalAnimationApi::class)
@Composable
fun FullyLoadedTransition() {
    var visible by remember { mutableStateOf(true) }
    AnimatedVisibility(
        visible = visible,
        enter =
            slideInVertically(
                // Start the slide from 40 (pixels) above where the content is supposed to go, to
                // produce a parallax effect
                initialOffsetY = { -40 }
            ) +
                expandVertically(expandFrom = Alignment.Top) +
                scaleIn(
                    // Animate scale from 0f to 1f using the top center as the pivot point.
                    transformOrigin = TransformOrigin(0.5f, 0f)
                ) +
                fadeIn(initialAlpha = 0.3f),
        exit = slideOutVertically() + shrinkVertically() + fadeOut() + scaleOut(targetScale = 1.2f)
    ) {
        // Content that needs to appear/disappear goes here:
        Text("Content to appear/disappear", Modifier.fillMaxWidth().requiredHeight(200.dp))
    }
}

AnimatedVisibilityWithBooleanVisibleParamNoReceiver

@OptIn(ExperimentalAnimationApi::class)
@Composable
fun AnimatedVisibilityWithBooleanVisibleParamNoReceiver() {
    var visible by remember { mutableStateOf(true) }
    Box(modifier = Modifier.clickable { visible = !visible }) {
        AnimatedVisibility(
            visible = visible,
            modifier = Modifier.align(Alignment.Center),
            enter = fadeIn(),
            exit = fadeOut(animationSpec = tween(200)) + scaleOut()
        ) { // Content that needs to appear/disappear goes here:
            // Here we can optionally define a custom enter/exit animation by creating an animation
            // using the Transition<EnterExitState> object from AnimatedVisibilityScope:

            // As a part of the enter transition, the corner radius will be animated from 0.dp to
            // 50.dp.
            val cornerRadius by
                transition.animateDp {
                    when (it) {
                        EnterExitState.PreEnter -> 0.dp
                        EnterExitState.Visible -> 50.dp
                        // No corner radius change when exiting.
                        EnterExitState.PostExit -> 50.dp
                    }
                }
            Box(
                Modifier.background(Color.Red, shape = RoundedCornerShape(cornerRadius))
                    .height(100.dp)
                    .fillMaxWidth()
            )
        }
    }
}

AnimatedVisibilityLazyColumnSample

@Composable
fun AnimatedVisibilityLazyColumnSample() {
    val turquoiseColors =
        listOf(
            Color(0xff07688C),
            Color(0xff1986AF),
            Color(0xff50B6CD),
            Color(0xffBCF8FF),
            Color(0xff8AEAE9),
            Color(0xff46CECA)
        )

    // MyModel class handles the data change of the items that are displayed in LazyColumn.
    class MyModel {
        private val _items: MutableList<ColoredItem> = mutableStateListOf()
        private var lastItemId = 0
        val items: List<ColoredItem> = _items

        // Each item has a MutableTransitionState field to track as well as to mutate the item's
        // visibility. When the MutableTransitionState's targetState changes, corresponding
        // transition will be fired. MutableTransitionState allows animation lifecycle to be
        // observed through it's [currentState] and [isIdle]. See below for details.
        inner class ColoredItem(val visible: MutableTransitionState<Boolean>, val itemId: Int) {
            val color: Color
                get() = turquoiseColors.let { it[itemId % it.size] }
        }

        fun addNewItem() {
            lastItemId++
            _items.add(
                ColoredItem(
                    // Here the initial state of the MutableTransitionState is set to false, and
                    // target state is set to true. This will result in an enter transition for
                    // the newly added item.
                    MutableTransitionState(false).apply { targetState = true },
                    lastItemId
                )
            )
        }

        fun removeItem(item: ColoredItem) {
            // By setting the targetState to false, this will effectively trigger an exit
            // animation in AnimatedVisibility.
            item.visible.targetState = false
        }

        fun pruneItems() {
            // Inspect the animation status through MutableTransitionState. If isIdle == true,
            // all animations have finished for the transition.
            _items.removeAll(
                items.filter {
                    // This checks that the animations have finished && the animations are exit
                    // transitions. In other words, the item has finished animating out.
                    it.visible.isIdle && !it.visible.targetState
                }
            )
        }

        fun removeAll() {
            _items.forEach { it.visible.targetState = false }
        }
    }

    @Composable
    fun AnimatedVisibilityInLazyColumn() {
        Column {
            val model = remember { MyModel() }
            Row(Modifier.fillMaxWidth()) {
                Button({ model.addNewItem() }, modifier = Modifier.padding(15.dp).weight(1f)) {
                    Text("Add")
                }
            }

            // This sets up a flow to check whether any item has finished animating out. If yes,
            // notify the model to prune the list.
            LaunchedEffect(model) {
                snapshotFlow {
                        model.items.firstOrNull { it.visible.isIdle && !it.visible.targetState }
                    }
                    .collect {
                        if (it != null) {
                            model.pruneItems()
                        }
                    }
            }
            LazyColumn {
                items(model.items, key = { it.itemId }) { item ->
                    AnimatedVisibility(
                        item.visible,
                        enter = expandVertically(),
                        exit = shrinkVertically()
                    ) {
                        Box(Modifier.fillMaxWidth().requiredHeight(90.dp).background(item.color)) {
                            Button(
                                { model.removeItem(item) },
                                modifier = Modifier.align(Alignment.CenterEnd).padding(15.dp)
                            ) {
                                Text("Remove")
                            }
                        }
                    }
                }
            }

            Button({ model.removeAll() }, modifier = Modifier.align(Alignment.End).padding(15.dp)) {
                Text("Clear All")
            }
        }
    }
}