Compose state hoisting

Core principle

Hoist state only as far as the logic needs it. Keep simple UI element state local, move shared UI element state to the lowest common composable owner, extract a plain state holder when UI-only behavior becomes a concept, and use a screen state holder when business logic or app data is involved.

Decision guide

UI element state includes things like expansion, sheet visibility, scroll position, focus, text field editing state, selection, and animation/interaction state. Screen UI state is app data prepared for display.

If UI element state is an input to business logic, it may need to live in the screen state holder too. For example, text used to query repository-backed suggestions belongs with the state holder that produces those suggestions.

Plain state holder trigger

Extract a plain state holder when several of these are true:

• Multiple related remember values are coordinated by the same callbacks.
• Scroll, focus, text, selection, or sheet state needs named operations such as clear, submit, jumpToTop, or openFilters.
• Derived UI flags are scattered through the composable.
• Child composables receive mechanics they do not conceptually own.
• Previews or tests must drive a long sequence of UI details to check one behavior.
• Helper functions need many state parameters just to keep the composable readable.

Do not extract for one boolean, one text field, or trivial show/hide logic. Ceremony is not separation of concerns.

Pattern

Use a plain class for UI element state and UI logic, plus a remember...State function for composition-owned objects:

@Stable
class ProductSearchState(
    query: String,
    private val listState: LazyListState,
    private val focusRequester: FocusRequester,
) {
    var query by mutableStateOf(query)
        private set

    var filtersOpen by mutableStateOf(false)
        private set

    val canClear: Boolean
        get() = query.isNotEmpty()

    fun updateQuery(value: String) {
        query = value
    }

    fun clear() {
        query = ""
        focusRequester.requestFocus()
    }

    suspend fun jumpToTop() {
        listState.animateScrollToItem(0)
    }
}

@Composable
fun rememberProductSearchState(
    initialQuery: String = "",
    listState: LazyListState = rememberLazyListState(),
    focusRequester: FocusRequester = remember { FocusRequester() },
): ProductSearchState {
    return remember(listState, focusRequester) {
        ProductSearchState(initialQuery, listState, focusRequester)
    }
}

The composable renders from the state holder and calls intent-style methods. If a parent needs to coordinate the same UI behavior, accept the state holder as a parameter with a default:

@Composable
fun ProductSearchPanel(
    state: ProductSearchState = rememberProductSearchState(),
    modifier: Modifier = Modifier,
) {
    val scope = rememberCoroutineScope()

    SearchField(
        query = state.query,
        onQueryChange = state::updateQuery,
        onClear = state::clear,
    )

    JumpToTopButton(onClick = {
        scope.launch { state.jumpToTop() }
    })
}

Composition ownership

Plain state holders created with remember follow the composable lifecycle. This makes them a good home for Compose UI objects such as LazyListState, FocusRequester, PagerState, DrawerState, and TextFieldState.

Keep suspend UI operations that require a frame clock, such as scroll or drawer animations, in a composition-scoped coroutine (rememberCoroutineScope, LaunchedEffect, or another composition-owned scope). Do not move those calls to viewModelScope.

Saving state

Use rememberSaveable or a custom Saver only for values that should survive Activity or process recreation, such as a query string, selected filter IDs, or a current tab key.

Do not try to save runtime objects like LazyListState, FocusRequester, coroutine scopes, or callbacks directly. Save the minimal serializable values needed to rebuild behavior.

Common mistakes

Related

• compose-state-authoring — correct local remember and mutable state authoring.
• compose-state-holder-ui-split — split screen state-holder wiring from plain state-driven UI rendering.
• compose-side-effects — choose effect APIs and composition-scoped coroutine boundaries.
• compose-focus-navigation — focus state, requesters, and keyboard/D-pad behavior.