LocalRetainScope

public val LocalRetainScope: ProvidableCompositionLocal<RetainScope>

The RetainScope in which retain values will be tracked in. Since a RetainScope controls retention scenarios and signals when to start and end the retention of objects removed from composition, a composition hierarchy may have several RetainScopes to introduce retention periods to specific pieces of content.

The default implementation is a ForgetfulRetainScope that causes retain to behave the same as remember. On Android, a lifecycle-aware scope is installed at the root of the composition that retains values across configuration changes.

If this CompositionLocal is updated, all values previously returned by retain will be adopted to the new scope and will follow the new scope's retention lifecycle.

RetainScopes should be installed so that their tracked transiently removed content is always removed from composition in the same frame (and by extension, all retained values leave composition in the same frame). If the RetainScope starts keeping exited values and its tracked content is removed in an arbitrary order across several recompositions, it may cause retained values to be restored incorrectly if the retained values from different regions in the composition have the same currentCompositeKeyHashCode.