skip to content

In Compose, a bouquet card should grow into its detail screen through SharedTransitionLayout but only fades; why does the shared element not match, and how do you fix it?

level: seniorimportance: should knowfreq 32%

answer

  1. same scope, same key, both composed
  2. rememberSharedContentState(key) must be equal
  3. the AnimatedVisibilityScope that swaps them
  4. isMatchFound to check the pairing
  5. stable since Compose 1.10, no opt-in

basics

~20 s

A shared element animates only when two Modifier.sharedElement calls inside one SharedTransitionLayout use equal keys and each gets the AnimatedVisibilityScope of the AnimatedContent or AnimatedVisibility that swaps them. Without a match, each side just fades.

solid answer

~40 s

Put one `SharedTransitionLayout` above the `AnimatedContent` (or `AnimatedVisibility`) that switches between grid and detail. On both sides, in `SharedTransitionScope`, apply `Modifier.sharedElement(rememberSharedContentState(key = ...), animatedVisibilityScope = this@AnimatedContent)`. Matching is by key equality, so `"photo"` on the tile and `"photo-$id"` on the detail never match, and a list where every tile uses `"photo"` is ambiguous. Use a data-class key such as `BouquetKey(id, Part.Photo)`. Pass the scope of the switching container, not one from an unrelated inner `AnimatedVisibility`. Swapping with a plain `if` gives no scope at all. `isMatchFound` on the `SharedContentState` confirms the pairing. Use `sharedBounds` when the two sides look different. Since Compose 1.10 these APIs are stable, so 1.12 code needs no `@OptIn`.

code

kotlin · 26 lines
kotlin
data class BouquetKey(val bouquetId: Long, val part: String)

@Composable
fun SharedTransitionScope.BouquetPhoto(
    bouquetId: Long,
    animatedScope: AnimatedVisibilityScope,
    modifier: Modifier = Modifier,
) {
    Box(
        modifier
            .sharedElement(
                sharedContentState = rememberSharedContentState(key = BouquetKey(bouquetId, "photo")),
                animatedVisibilityScope = animatedScope,
            )
            .size(120.dp)
            .background(Color.Magenta)
    )
}

// One SharedTransitionLayout above the AnimatedContent that swaps grid and detail.
SharedTransitionLayout {
    AnimatedContent(targetState = selectedId, label = "bouquet") { id ->
        if (id == null) BouquetGrid(onOpen = { selectedId = it }, animatedScope = this)
        else BouquetPhoto(bouquetId = id, animatedScope = this)
    }
}

go deeper

for a junior

Recall the three APIs: SharedTransitionLayout provides the scope, sharedElement matches identical content, sharedBounds matches a shared area.

for a middle

Explain that matching needs one shared layout, equal keys and the AnimatedVisibilityScope of the switching container, and how sharedBounds differs from sharedElement.

for a senior

Diagnose a non-matching transition with isMatchFound, unique data-class keys per item and origin, consistent modifier order, and clipping after the shared modifier.

for a principal

Adopt a shared key type and scope-passing convention across feature modules, so screens built by different teams can match elements without string coordination.

## The pieces of a shared element transition A **shared element transition** visually connects the same piece of content across two composables, such as a bouquet photo in a grid tile that grows into the header of the bouquet's detail screen. Compose provides three APIs, all **stable since Compose 1.10**, so no opt-in is needed in 1.12: - **`SharedTransitionLayout`** is the outermost layout. It provides a **`SharedTransitionScope`**, and the shared modifiers exist only inside that scope. - **`Modifier.sharedElement(sharedContentState, animatedVisibilityScope)`** marks content that should be matched with **identical-looking** content elsewhere. During the transition, only the target content is drawn in the moving bounds. - **`Modifier.sharedBounds(...)`** marks content that is **visually different** but should share the same area, the container-transform pattern. Both entering and exiting content are visible during the change, with `enter` and `exit` transitions (`fadeIn()` and `fadeOut()` by default) and a `resizeMode` (by default `scaleToBounds(ContentScale.FillWidth, Center)`). ## How matching works, and why it fails With `sharedElement` under `AnimatedContent` or `AnimatedVisibility`, a match needs all of the following: 1. **One `SharedTransitionLayout` above both sides.** Two separate layouts are two separate scopes, and their elements never meet. 2. **Equal keys.** `rememberSharedContentState(key)` stores the key, and keys are compared by equality. `"photo"` and `"photo-42"` do not match. The documentation recommends non-string keys, and data classes because they implement `equals()` and `hashCode()`. In a list, every key must be unique per item, or include the item's identifier and its origin section. 3. **The right `AnimatedVisibilityScope`.** The scope tells the system whether each side is entering or leaving. Pass the scope of the container that actually swaps the two: `this@AnimatedContent`, the `AnimatedVisibility` content scope, or the scope a navigation host gives each destination. Passing a scope from some unrelated nested `AnimatedVisibility`, or switching with a plain `if` that provides no scope, breaks the enter-or-exit signal. 4. **Both sides composed at the same moment.** `AnimatedContent` keeps outgoing and incoming content composed during its transform, which is what makes the pairing possible. When there is **no match**, the KDoc is plain: `sharedElement` and `sharedBounds` have no animation. Each side just takes part in its parent's enter or exit, which is why the card "only fades" under `AnimatedContent`'s default fade-through. To diagnose, keep the `SharedContentState` in a variable and read **`isMatchFound`**. It becomes true only after the second element with that key has been composed, which in a lazy list happens during measure and layout. ## Other causes of a broken-looking transition | Symptom | Likely cause | Fix | |---|---|---| | Card fades instead of growing | keys differ, scopes differ, or no shared layout | equal data-class keys, the switching container's scope, one `SharedTransitionLayout` | | Element jumps in size or position | modifiers ordered differently on the two sides | same order; size modifiers after the shared modifier | | Rounded corners vanish mid-flight | clip placed before `sharedElement` | clip after it, or `clipInOverlayDuringTransition` | | Text style or shape change looks wrong | `sharedElement` on visually different content | `sharedBounds` with `animateEnterExit` on the children | | Element inside a dialog never animates | the documentation lists View interop, including `Dialog` and `ModalBottomSheet`, as unsupported | keep both sides in one Compose hierarchy | Two of these deserve a closer look: - **Overlay rendering.** A matched shared element renders in the `SharedTransitionScope` overlay during the transition, so it is not faded or clipped by its parents. Any clip or fade you want must come **after** `sharedElement` in the modifier chain. - **Modifier order.** The documentation warns that modifiers before the shared modifier supply the constraints for the initial and target bounds. Inconsistent order between the two sides causes visual jumps. ## Fixing the flower-shop card 1. Wrap the grid-and-detail `AnimatedContent` in `SharedTransitionLayout`. 2. Define `data class BouquetKey(val bouquetId: Long, val part: String)`. 3. On the tile photo and the detail header, apply `sharedElement(rememberSharedContentState(BouquetKey(id, "photo")), animatedVisibilityScope = this@AnimatedContent)`. 4. For the card background growing into the detail page, use `sharedBounds` with a different key part, so the surface transforms while its contents cross-fade. 5. Pass the two scopes down as parameters, or provide them through `CompositionLocal`s when the hierarchy is deep. Navigation hosts that supply an `AnimatedContentScope` per destination use the same modifiers. Wiring them to a navigation library is covered with that library.

  • The same bouquet appears in both a 'Popular' row and a 'Seasonal' row; which tile should grow into the detail screen?
    Only the one the user tapped. Include the origin in the key, for example `BouquetKey(id, origin, part)`, and have the detail screen use the origin it was opened from. Otherwise two tiles share a key and the match is ambiguous.
  • How do you share an element when you are not switching with AnimatedContent or AnimatedVisibility?
    Use `Modifier.sharedElementWithCallerManagedVisibility(sharedContentState, visible)` and supply the visibility yourself. The documentation notes that the invisible element stays in the tree. Remove it once `isTransitionActive` turns false, or it keeps matching when its size or position changes.

  • Shared elements match by position on screen, not by key.
  • 1.12 code must opt in with ExperimentalSharedTransitionApi.
  • Any AnimatedVisibilityScope in the tree will do for the modifier.
  • sharedElement is the right choice when the two sides look different.
  • A clip placed before sharedElement still clips it during the transition.

Assumes Compose 1.12; SharedTransitionLayout, sharedElement and sharedBounds are stable since Compose 1.10 and earlier releases required @OptIn(ExperimentalSharedTransitionApi::class).