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?
answer
- same scope, same key, both composed
- rememberSharedContentState(key) must be equal
- the AnimatedVisibilityScope that swaps them
- isMatchFound to check the pairing
- stable since Compose 1.10, no opt-in
basics
~20 sA 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 sPut 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 linesdata 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
Recall the three APIs: SharedTransitionLayout provides the scope, sharedElement matches identical content, sharedBounds matches a shared area.
Explain that matching needs one shared layout, equal keys and the AnimatedVisibilityScope of the switching container, and how sharedBounds differs from sharedElement.
Diagnose a non-matching transition with isMatchFound, unique data-class keys per item and origin, consistent modifier order, and clipping after the shared modifier.
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).