---
title: "CompositionObserver"
description: "Observe [RecomposeScope] management inside composition.

The expected lifecycle of a [RecomposeScope] in composition is as follows:
```
// In the composition phase:
[onBeginComposition]      ┃
[onScopeEnter] ━┓   // Composition enters a scope               ┃        [onReadInScope]  // Record reads inside the scope               ┃               ┗━ [onScopeEnter]                   ...             // Potentially enter nested function scopes               ┏━ [onScopeExit]               ┃
[onScopeExit]  ━┛   // Composition leaves the scope      ┃
[onEndComposition]

// In the apply changes phase:
[onScopeDisposed]   // Scope is discarded by composition and is no longer used.
```

The scopes can be invalidated at any point either by values previously reported in
[onReadInScope] or by calling [RecomposeScope.invalidate] directly. In these cases,
[onScopeInvalidated] will be called with the associated instance or `null` if the scope was
invalidated directly.

Note that invalidation of the scope does not guarantee it will be composed. Some cases where it
is not composed are:
1) The scope is no longer part of the composition (e.g the parent scope no longer executed the  code branch the scope was a part of)
2) The scope is part of movable content that was moved out of the composition.

In the case of movable content, the scope will be recomposed as part of a different composition
when it is moved to that composition or it might be discarded (with a corresponding
[onScopeDisposed] call) if no other composition claims it."
type: "interface"
---

<div class='type'>Interface</div>


<a id='references'></a>

<div class='sourceset sourceset-common'>Common</div>



```kotlin
@ExperimentalComposeRuntimeApi
public interface CompositionObserver
```


Observe `RecomposeScope` management inside composition.

The expected lifecycle of a `RecomposeScope` in composition is as follows:
```
// In the composition phase:
`onBeginComposition`      ┃
`onScopeEnter` ━┓   // Composition enters a scope               ┃        `onReadInScope`  // Record reads inside the scope               ┃               ┗━ `onScopeEnter`                   ...             // Potentially enter nested function scopes               ┏━ `onScopeExit`               ┃
`onScopeExit`  ━┛   // Composition leaves the scope      ┃
`onEndComposition`

// In the apply changes phase:
`onScopeDisposed`   // Scope is discarded by composition and is no longer used.
```

The scopes can be invalidated at any point either by values previously reported in
`onReadInScope` or by calling `RecomposeScope.invalidate` directly. In these cases,
`onScopeInvalidated` will be called with the associated instance or `null` if the scope was
invalidated directly.

Note that invalidation of the scope does not guarantee it will be composed. Some cases where it
is not composed are:
1) The scope is no longer part of the composition (e.g the parent scope no longer executed the  code branch the scope was a part of)
2) The scope is part of movable content that was moved out of the composition.

In the case of movable content, the scope will be recomposed as part of a different composition
when it is moved to that composition or it might be discarded (with a corresponding
`onScopeDisposed` call) if no other composition claims it.


## Functions

```kotlin
public fun onBeginComposition(composition: ObservableComposition)
```


Called when the composition process begins for `composition` instance.


```kotlin
public fun onScopeEnter(scope: RecomposeScope)
```


Called when `scope` enters the composition.


```kotlin
public fun onReadInScope(scope: RecomposeScope, value: Any)
```


Called when read of `value` is recorded in `scope` during composition.

Reads can be recorded without re-execution of the function associated with the scope, for
example when derived state invalidates the scope with the same value as before.

The instances passed to this method are only tracked between `onScopeEnter` and `onScopeExit`
calls. Previously recorded instances should also be cleared when `onScopeEnter` is called
again, to avoid keeping stale instances that are no longer tracked by composition. For
example, this happens with `remember { state.value }`, with `state` recorded only during
first composition.

#### Parameters

| | |
| --- | --- |
| scope | A `RecomposeScope` that the read occurred in. |
| value | A value that was recorded in `scope` and can invalidate it in the future. In most cases, `value` is a snapshot state instance. |



```kotlin
public fun onScopeExit(scope: RecomposeScope)
```


Called when `RecomposeScope` exits composition.


```kotlin
public fun onEndComposition(composition: ObservableComposition)
```


Called after composition process has been completed for `composition`.


```kotlin
public fun onScopeInvalidated(scope: RecomposeScope, value: Any?)
```


Called when `scope` is invalidated by composition or `RecomposeScope.invalidate` call.

Note that for invalidations caused by a state change, this callback is not called immediately
on the state write. Usually, invalidations from state changes are recorded right before
recomposition starts or during composition (e.g. if `rememberUpdatedState` is used). This
method is always guaranteed to be called before `onScopeEnter` for the corresponding
invalidation is executed. If the scope was invalidated by `RecomposeScope.invalidate`,
however, this callback is executed before `RecomposeScope.invalidate` returns.

#### Parameters

| | |
| --- | --- |
| scope | A `RecomposeScope` that is invalidated. |
| value | A value that invalidated composition. Can be `null` if the scope was invalidated by calling `RecomposeScope.invalidate` directly. |



```kotlin
public fun onScopeDisposed(scope: RecomposeScope)
```


Called when `RecomposeScope` is no longer used in composition. Can be called from any thread
whenever composition applies changes or is disposed.