focus-trap

A focus trap occurs when keyboard focus gets stuck cycling within a group of elements, and users cannot move on to other parts of the UI. Everything outside the loop becomes unreachable with the keyboard. This often happens when a custom focus order is set with nextFocusForward or the other nextFocus attributes, and the chain leads back to an earlier element instead of continuing through the screen. In most cases, don't override the default focus order. If you do, make sure the chain reaches every interactive element and lets focus continue past the last one.

Focus traps on iOS and in Flutter

The examples below use Android's nextFocus attributes, Jetpack Compose's focusProperties, and React Native's Android-only nextFocusForward prop. Other platforms have no single attribute that causes this issue, but focus traps can still happen:

• UIKit and SwiftUI: iOS has no per-element "next focus" attribute. Keyboard focus is managed with focus groups and focus guides, and in SwiftUI also with focus sections and @FocusState. A trap usually comes from custom focus logic, such as code that moves focus back whenever it leaves an area.
• Flutter: Focus order is managed with FocusTraversalGroup, traversal policies, and FocusScope. A misconfigured scope or custom traversal logic can keep focus inside part of the screen.

On these platforms, review any custom focus logic and test it with a keyboard, as described in Try It Yourself.

Pass Patterns

Android

<LinearLayout
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:orientation="vertical">


    <Button
        android:id="@+id/button1"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:text="Button 1" />


    <Button
        android:id="@+id/button2"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:text="Button 2" />


    <Button
        android:id="@+id/button3"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:text="Button 3" />


    <Button
        android:id="@+id/continueButton"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:text="Continue" />
</LinearLayout>

Fail Patterns

Android

<LinearLayout
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:orientation="vertical">


    <Button
        android:id="@+id/button1"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:nextFocusForward="@id/button3"
        android:text="Button 1" />


    <Button
        android:id="@+id/button2"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:text="Button 2" />


    <Button
        android:id="@+id/button3"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:nextFocusForward="@id/button1"
        android:text="Button 3" />


    <Button
        android:id="@+id/continueButton"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:text="Continue" />
</LinearLayout>

Try It Yourself

Using a keyboard

1. Connect an external keyboard to the device. On iOS, also turn on Settings > Accessibility > Keyboards > Full Keyboard Access.
2. Press Tab repeatedly to move focus through the screen. You may also need to use the arrow keys within a container.
3. Check whether focus reaches every interactive element and can move past each group of elements.

Expected results: Focus moves through all the interactive elements on the screen and does not get stuck in a loop.

Actual results: Focus cycles within a group of elements, and some elements on the screen can never receive focus.

FAQ

Standards and Regulations

Personas impacted by this issue

• Keyboard

Learn More

• Understanding Success Criterion 2.1.2: No Keyboard Trap
• Android: Support keyboard navigation (Views)
• Android: Change focus traversal order in Jetpack Compose
• React Native: View props (nextFocusForward)
• Apple: Focus-based navigation (UIKit)
• Apple: Focus (SwiftUI)
• Flutter: Understanding focus
• Flutter: FocusTraversalGroup class

Related Issues

• focus-order
• keyboard-focusable
• visible-focus-indication