# BackHandler

## Functions summary

|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `@https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable https://developer.android.com/reference/kotlin/androidx/activity/compose/BackHandler.composable#BackHandler(kotlin.Boolean,kotlin.Function0)(enabled: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html, onBack: () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html)` An effect for handling presses of the system back button. |

## Functions

### BackHandler

Artifact: [androidx.activity:activity-compose](https://developer.android.com/jetpack/androidx/releases/activity) [View Source](https://cs.android.com/search?q=file:androidx/activity/compose/BackHandler.kt+function:BackHandler) Added in [1.3.0](https://developer.android.com/jetpack/androidx/releases/activity#1.3.0)

```
@Composable
fun BackHandler(enabled: Boolean = true, onBack: () -> Unit): Unit
```

An effect for handling presses of the system back button.

This effect registers a callback to be invoked when the system back button is pressed. The `https://developer.android.com/reference/kotlin/androidx/activity/compose/package-summary#BackHandler(kotlin.Boolean,kotlin.Function0)` will be invoked when the system back button is pressed (that is, `onCompleted`).

The handler is registered once and stays attached for the lifetime of the `https://developer.android.com/reference/kotlin/androidx/lifecycle/LifecycleOwner`. Its `https://developer.android.com/reference/kotlin/androidx/activity/OnBackPressedCallback#isEnabled()` state automatically follows the lifecycle: it becomes enabled when the lifecycle is at least `https://developer.android.com/reference/kotlin/androidx/lifecycle/Lifecycle.State#STARTED` and disabled otherwise.

## Precedence

If multiple `https://developer.android.com/reference/kotlin/androidx/activity/compose/BackHandler.composable#BackHandler(kotlin.Boolean,kotlin.Function0)` are present in the composition, the one that is composed **last** among all enabled handlers will be invoked.

## Usage

It is important to call this composable **unconditionally** . Use the `enabled` parameter to control whether the handler is active. This is preferable to conditionally calling `https://developer.android.com/reference/kotlin/androidx/activity/compose/BackHandler.composable#BackHandler(kotlin.Boolean,kotlin.Function0)` (e.g., inside an `if` block), as conditional calls can change the order of composition, leading to unpredictable behavior where different handlers are invoked after recomposition.

## Legacy Behavior

To restore the legacy add/remove behavior, set `https://developer.android.com/reference/kotlin/androidx/activity/ActivityFlags#isOnBackPressedLifecycleOrderMaintained()` to `false`. In legacy mode, the handler is added on `https://developer.android.com/reference/kotlin/androidx/lifecycle/Lifecycle.Event#ON_START` and removed on `https://developer.android.com/reference/kotlin/androidx/lifecycle/Lifecycle.Event#ON_STOP`, which may change dispatch ordering across lifecycle transitions.

```kotlin
import androidx.activity.compose.BackHandler
import androidx.compose.material.TextField
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember

var text by remember { mutableStateOf("") }

TextField(value = text, onValueChange = { text = it })

BackHandler(text.isNotEmpty()) {
    // handle back event
}
```

| Parameters |
|---|---|
| `enabled: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html = true` | If `true`, this handler will be enabled and eligible to handle the back press. |
| `onBack: () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | The action to be invoked when the system back button is pressed. |