# FocusRequester

Artifact: [androidx.compose.ui:ui](https://developer.android.com/jetpack/androidx/releases/compose-ui) [View Source](https://cs.android.com/search?q=file:androidx/compose/ui/focus/FocusRequester.kt+class:androidx.compose.ui.focus.FocusRequester) Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/compose-ui#1.0.0) Common/All
- Cmn

  ```
  class FocusRequester
  ```

*** ** * ** ***

The `https://developer.android.com/reference/kotlin/androidx/compose/ui/focus/FocusRequester` is used in conjunction with `https://developer.android.com/reference/kotlin/androidx/compose/ui/focus/focusRequester.modifier#(androidx.compose.ui.Modifier).focusRequester(androidx.compose.ui.focus.FocusRequester)` to send requests to change focus.

```kotlin
import androidx.compose.foundation.border
import androidx.compose.foundation.clickable
import androidx.compose.foundation.focusable
import androidx.compose.foundation.layout.Box
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.ui.Modifier
import androidx.compose.ui.focus.FocusRequester
import androidx.compose.ui.focus.focusRequester
import androidx.compose.ui.focus.onFocusChanged
import androidx.compose.ui.graphics.Color.Companion.Black
import androidx.compose.ui.graphics.Color.Companion.Green
import androidx.compose.ui.unit.dp

val focusRequester = remember { FocusRequester() }
var color by remember { mutableStateOf(Black) }
Box(
    Modifier.clickable { focusRequester.requestFocus() }
        .border(2.dp, color)
        // The focusRequester should be added BEFORE the focusable.
        .focusRequester(focusRequester)
        // The onFocusChanged should be added BEFORE the focusable that is being observed.
        .onFocusChanged { color = if (it.isFocused) Green else Black }
        .focusable()
)
```

| See also |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/compose/ui/focus/focusRequester.modifier#(androidx.compose.ui.Modifier).focusRequester(androidx.compose.ui.focus.FocusRequester)` |   |

## Summary

| ### Nested types |
|---|
| `object https://developer.android.com/reference/kotlin/androidx/compose/ui/focus/FocusRequester.Companion` |
| `object https://developer.android.com/reference/kotlin/androidx/compose/ui/focus/FocusRequester.Companion.FocusRequesterFactory` Convenient way to create multiple `https://developer.android.com/reference/kotlin/androidx/compose/ui/focus/FocusRequester` instances. |

| ### Public companion functions |
|---|---|---|
| `https://developer.android.com/reference/kotlin/androidx/compose/ui/focus/FocusRequester.Companion.FocusRequesterFactory` | `https://developer.android.com/reference/kotlin/androidx/compose/ui/focus/FocusRequester#createRefs()()` Convenient way to create multiple `https://developer.android.com/reference/kotlin/androidx/compose/ui/focus/FocusRequester`s, which can to be used to request focus, or to specify a focus traversal order. | Cmn |

| ### Public companion properties |
|---|---|---|
| `https://developer.android.com/reference/kotlin/androidx/compose/ui/focus/FocusRequester` | `https://developer.android.com/reference/kotlin/androidx/compose/ui/focus/FocusRequester#Cancel()` Cancelled `https://developer.android.com/reference/kotlin/androidx/compose/ui/focus/focusRequester.modifier#(androidx.compose.ui.Modifier).focusRequester(androidx.compose.ui.focus.FocusRequester)`, which when used in `https://developer.android.com/reference/kotlin/androidx/compose/ui/focus/focusProperties.modifier#(androidx.compose.ui.Modifier).focusProperties(kotlin.Function1)` implies that we want to block focus search from proceeding in the specified `https://developer.android.com/reference/kotlin/androidx/compose/ui/focus/FocusDirection`. | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/compose/ui/focus/FocusRequester` | `https://developer.android.com/reference/kotlin/androidx/compose/ui/focus/FocusRequester#Default()` Default `https://developer.android.com/reference/kotlin/androidx/compose/ui/focus/focusRequester.modifier#(androidx.compose.ui.Modifier).focusRequester(androidx.compose.ui.focus.FocusRequester)`, which when used in `https://developer.android.com/reference/kotlin/androidx/compose/ui/focus/focusProperties.modifier#(androidx.compose.ui.Modifier).focusProperties(kotlin.Function1)` implies that we want to use the default system focus order, that is based on the position of the items on the screen. | Cmn |

| ### Public constructors |
|---|---|
| `@https://developer.android.com/reference/kotlin/androidx/compose/runtime/annotation/RememberInComposition https://developer.android.com/reference/kotlin/androidx/compose/ui/focus/FocusRequester#FocusRequester()()` | Cmn |

| ### Public functions |
|---|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | `https://developer.android.com/reference/kotlin/androidx/compose/ui/focus/FocusRequester#captureFocus()()` Deny requests to clear focus. | Cmn |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | `https://developer.android.com/reference/kotlin/androidx/compose/ui/focus/FocusRequester#freeFocus()()` Use this function to send a request to free focus when one of the components associated with this `https://developer.android.com/reference/kotlin/androidx/compose/ui/focus/FocusRequester` is in a Captured state. | Cmn |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | `https://developer.android.com/reference/kotlin/androidx/compose/ui/focus/FocusRequester#requestFocus(androidx.compose.ui.focus.FocusDirection)(focusDirection: https://developer.android.com/reference/kotlin/androidx/compose/ui/focus/FocusDirection)` Use this function to request focus with a specific direction. | Cmn |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | `https://developer.android.com/reference/kotlin/androidx/compose/ui/focus/FocusRequester#restoreFocusedChild()()` Use this function to restore focus to one of the children of the node pointed to by this `https://developer.android.com/reference/kotlin/androidx/compose/ui/focus/FocusRequester`. | Cmn |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | `https://developer.android.com/reference/kotlin/androidx/compose/ui/focus/FocusRequester#saveFocusedChild()()` Use this function to request the focus target to save a reference to the currently focused child in its saved instance state. | Cmn |

## Public companion functions

### createRefs

Cmn Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/compose-ui#1.0.0)

```
fun createRefs(): FocusRequester.Companion.FocusRequesterFactory
```

Convenient way to create multiple `https://developer.android.com/reference/kotlin/androidx/compose/ui/focus/FocusRequester`s, which can to be used to request focus, or to specify a focus traversal order.

```kotlin
import androidx.compose.foundation.focusable
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.Column
import androidx.compose.runtime.remember
import androidx.compose.ui.Modifier
import androidx.compose.ui.focus.FocusRequester
import androidx.compose.ui.focus.focusRequester

val (item1, item2, item3, item4) = remember { FocusRequester.createRefs() }
Column {
    Box(Modifier.focusRequester(item1).focusable())
    Box(Modifier.focusRequester(item2).focusable())
    Box(Modifier.focusRequester(item3).focusable())
    Box(Modifier.focusRequester(item4).focusable())
}
```

## Public companion properties

### Cancel

Cmn Added in [1.3.0](https://developer.android.com/jetpack/androidx/releases/compose-ui#1.3.0)

```
val Cancel: FocusRequester
```

Cancelled `https://developer.android.com/reference/kotlin/androidx/compose/ui/focus/focusRequester.modifier#(androidx.compose.ui.Modifier).focusRequester(androidx.compose.ui.focus.FocusRequester)`, which when used in `https://developer.android.com/reference/kotlin/androidx/compose/ui/focus/focusProperties.modifier#(androidx.compose.ui.Modifier).focusProperties(kotlin.Function1)` implies that we want to block focus search from proceeding in the specified `https://developer.android.com/reference/kotlin/androidx/compose/ui/focus/FocusDirection`.

```kotlin
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.Column
import androidx.compose.ui.Modifier
import androidx.compose.ui.focus.FocusRequester.Companion.Cancel
import androidx.compose.ui.focus.focusProperties
import androidx.compose.ui.focus.focusTarget

// If Box 2 is focused, pressing Up will not take focus to Box 1,
// But pressing Down will move focus to Box 3.
Column {
    // Box 1.
    Box(Modifier.focusTarget())
    // Box 2.
    Box(modifier = Modifier.focusProperties { up = Cancel }.focusTarget())
    // Box 3.
    Box(Modifier.focusTarget())
}
```

### Default

Cmn Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/compose-ui#1.0.0)

```
val Default: FocusRequester
```

Default `https://developer.android.com/reference/kotlin/androidx/compose/ui/focus/focusRequester.modifier#(androidx.compose.ui.Modifier).focusRequester(androidx.compose.ui.focus.FocusRequester)`, which when used in `https://developer.android.com/reference/kotlin/androidx/compose/ui/focus/focusProperties.modifier#(androidx.compose.ui.Modifier).focusProperties(kotlin.Function1)` implies that we want to use the default system focus order, that is based on the position of the items on the screen.

## Public constructors

### FocusRequester

Cmn Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/compose-ui#1.0.0)

```
@RememberInComposition
FocusRequester()
```

## Public functions

### captureFocus

Cmn Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/compose-ui#1.0.0)

```
fun captureFocus(): Boolean
```

Deny requests to clear focus.

Use this function to send a request to capture focus. If a component captures focus, it will send a `https://developer.android.com/reference/kotlin/androidx/compose/ui/focus/FocusState` object to its associated `https://developer.android.com/reference/kotlin/androidx/compose/ui/focus/onFocusChanged.modifier#(androidx.compose.ui.Modifier).onFocusChanged(kotlin.Function1)` modifiers where [FocusState.isCaptured]() == true.

When a component is in a Captured state, all focus requests from other components are declined.

```kotlin
import androidx.compose.foundation.border
import androidx.compose.material3.Text
import androidx.compose.material3.TextField
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.ui.Modifier
import androidx.compose.ui.focus.FocusRequester
import androidx.compose.ui.focus.focusRequester
import androidx.compose.ui.focus.onFocusChanged
import androidx.compose.ui.graphics.Color.Companion.Red
import androidx.compose.ui.graphics.Color.Companion.Transparent
import androidx.compose.ui.unit.dp

val focusRequester = remember { FocusRequester() }
var value by remember { mutableStateOf("apple") }
var borderColor by remember { mutableStateOf(Transparent) }
TextField(
    value = value,
    onValueChange = {
        value = it.apply {
            if (length > 5) focusRequester.captureFocus() else focusRequester.freeFocus()
        }
    },
    modifier =
        Modifier.border(2.dp, borderColor).focusRequester(focusRequester).onFocusChanged {
            borderColor = if (it.isCaptured) Red else Transparent
        },
)
```

| Returns |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | true if the focus was successfully captured by one of the `https://developer.android.com/reference/kotlin/androidx/compose/ui/focus/focusTarget.modifier#(androidx.compose.ui.Modifier).focusTarget()` modifiers associated with this `https://developer.android.com/reference/kotlin/androidx/compose/ui/focus/FocusRequester`. False otherwise. |

### freeFocus

Cmn Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/compose-ui#1.0.0)

```
fun freeFocus(): Boolean
```

Use this function to send a request to free focus when one of the components associated with this `https://developer.android.com/reference/kotlin/androidx/compose/ui/focus/FocusRequester` is in a Captured state. If a component frees focus, it will send a `https://developer.android.com/reference/kotlin/androidx/compose/ui/focus/FocusState` object to its associated `https://developer.android.com/reference/kotlin/androidx/compose/ui/focus/onFocusChanged.modifier#(androidx.compose.ui.Modifier).onFocusChanged(kotlin.Function1)` modifiers where [FocusState.isCaptured]() == false.

When a component is in a Captured state, all focus requests from other components are declined. .

```kotlin
import androidx.compose.foundation.border
import androidx.compose.material3.Text
import androidx.compose.material3.TextField
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.ui.Modifier
import androidx.compose.ui.focus.FocusRequester
import androidx.compose.ui.focus.focusRequester
import androidx.compose.ui.focus.onFocusChanged
import androidx.compose.ui.graphics.Color.Companion.Red
import androidx.compose.ui.graphics.Color.Companion.Transparent
import androidx.compose.ui.unit.dp

val focusRequester = remember { FocusRequester() }
var value by remember { mutableStateOf("apple") }
var borderColor by remember { mutableStateOf(Transparent) }
TextField(
    value = value,
    onValueChange = {
        value = it.apply {
            if (length > 5) focusRequester.captureFocus() else focusRequester.freeFocus()
        }
    },
    modifier =
        Modifier.border(2.dp, borderColor).focusRequester(focusRequester).onFocusChanged {
            borderColor = if (it.isCaptured) Red else Transparent
        },
)
```

| Returns |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | true if the captured focus was successfully released. i.e. At the end of this operation, one of the components associated with this `https://developer.android.com/reference/kotlin/androidx/compose/ui/focus/focusRequester.modifier#(androidx.compose.ui.Modifier).focusRequester(androidx.compose.ui.focus.FocusRequester)` freed focus. |

### requestFocus

Cmn Added in [1.10.0](https://developer.android.com/jetpack/androidx/releases/compose-ui#1.10.0)

```
fun requestFocus(focusDirection: FocusDirection = Enter): Boolean
```

Use this function to request focus with a specific direction. If the system grants focus to a component associated with this `https://developer.android.com/reference/kotlin/androidx/compose/ui/focus/FocusRequester`, its `https://developer.android.com/reference/kotlin/androidx/compose/ui/focus/onFocusChanged.modifier#(androidx.compose.ui.Modifier).onFocusChanged(kotlin.Function1)` modifiers will receive a `https://developer.android.com/reference/kotlin/androidx/compose/ui/focus/FocusState` object where `https://developer.android.com/reference/kotlin/androidx/compose/ui/focus/FocusState#isFocused()` is true.

```kotlin
import androidx.compose.foundation.border
import androidx.compose.foundation.clickable
import androidx.compose.foundation.focusable
import androidx.compose.foundation.layout.Box
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.ui.Modifier
import androidx.compose.ui.focus.FocusRequester
import androidx.compose.ui.focus.focusRequester
import androidx.compose.ui.focus.onFocusChanged
import androidx.compose.ui.graphics.Color.Companion.Black
import androidx.compose.ui.graphics.Color.Companion.Green
import androidx.compose.ui.unit.dp

val focusRequester = remember { FocusRequester() }
var color by remember { mutableStateOf(Black) }
Box(
    Modifier.clickable { focusRequester.requestFocus() }
        .border(2.dp, color)
        // The focusRequester should be added BEFORE the focusable.
        .focusRequester(focusRequester)
        // The onFocusChanged should be added BEFORE the focusable that is being observed.
        .onFocusChanged { color = if (it.isFocused) Green else Black }
        .focusable()
)
```

| Parameters |
|---|---|
| `focusDirection: https://developer.android.com/reference/kotlin/androidx/compose/ui/focus/FocusDirection = Enter` | The direction passed to the `https://developer.android.com/reference/kotlin/androidx/compose/ui/focus/FocusTargetModifierNode` to indicate the direction that the focus request comes from. |

| Returns |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | `true` if the focus was successfully requested or `false` if the focus request was canceled. |

### restoreFocusedChild

Cmn Added in [1.6.0](https://developer.android.com/jetpack/androidx/releases/compose-ui#1.6.0)

```
fun restoreFocusedChild(): Boolean
```

Use this function to restore focus to one of the children of the node pointed to by this `https://developer.android.com/reference/kotlin/androidx/compose/ui/focus/FocusRequester`. This restores focus to a previously focused child that was saved by using `https://developer.android.com/reference/kotlin/androidx/compose/ui/focus/FocusRequester#saveFocusedChild()`.

```kotlin
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.lazy.LazyRow
import androidx.compose.material3.Button
import androidx.compose.material3.Text
import androidx.compose.runtime.remember
import androidx.compose.ui.Modifier
import androidx.compose.ui.focus.FocusRequester
import androidx.compose.ui.focus.focusProperties
import androidx.compose.ui.focus.focusRequester

val focusRequester = remember { FocusRequester() }
LazyRow(
    Modifier.focusRequester(focusRequester).focusProperties {
        onExit = { focusRequester.saveFocusedChild() }
        onEnter = { if (focusRequester.restoreFocusedChild()) cancelFocusChange() }
    }
) {
    item { Button(onClick = {}) { Text("1") } }
    item { Button(onClick = {}) { Text("2") } }
    item { Button(onClick = {}) { Text("3") } }
    item { Button(onClick = {}) { Text("4") } }
}
```

| Returns |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | true if we successfully restored focus to one of the children of the `https://developer.android.com/reference/kotlin/androidx/compose/ui/focus/focusTarget.modifier#(androidx.compose.ui.Modifier).focusTarget()` associated with this `https://developer.android.com/reference/kotlin/androidx/compose/ui/focus/FocusRequester` |

### saveFocusedChild

Cmn Added in [1.6.0](https://developer.android.com/jetpack/androidx/releases/compose-ui#1.6.0)

```
fun saveFocusedChild(): Boolean
```

Use this function to request the focus target to save a reference to the currently focused child in its saved instance state. After calling this, focus can be restored to the saved child by making a call to `https://developer.android.com/reference/kotlin/androidx/compose/ui/focus/FocusRequester#restoreFocusedChild()`.

```kotlin
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.lazy.LazyRow
import androidx.compose.material3.Button
import androidx.compose.material3.Text
import androidx.compose.runtime.remember
import androidx.compose.ui.Modifier
import androidx.compose.ui.focus.FocusRequester
import androidx.compose.ui.focus.focusProperties
import androidx.compose.ui.focus.focusRequester

val focusRequester = remember { FocusRequester() }
LazyRow(
    Modifier.focusRequester(focusRequester).focusProperties {
        onExit = { focusRequester.saveFocusedChild() }
        onEnter = { if (focusRequester.restoreFocusedChild()) cancelFocusChange() }
    }
) {
    item { Button(onClick = {}) { Text("1") } }
    item { Button(onClick = {}) { Text("2") } }
    item { Button(onClick = {}) { Text("3") } }
    item { Button(onClick = {}) { Text("4") } }
}
```

| Returns |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | true if the focus target associated with this `https://developer.android.com/reference/kotlin/androidx/compose/ui/focus/FocusRequester` has a focused child and we successfully saved a reference to it. |