> ## Documentation Index
> Fetch the complete documentation index at: https://rive.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Focus

> Let users move through your file with a keyboard or gamepad, and control which element receives their input.

export const UseCase = ({title, children}) => {
  return <aside class="callout my-4 px-5 py-4 overflow-hidden rounded-2xl flex gap-3 border border-neutral-200 bg-neutral-50 dark:border-neutral-700 dark:bg-white/10" data-callout-type="info">
      <div class="mt-0.5 w-4" data-component-part="callout-icon">
        <svg width="11" height="14" viewBox="0 0 11 14" fill="currentColor" xmlns="http://www.w3.org/2000/svg" class="text-neutral-800 dark:text-neutral-300 w-3.5 h-auto" aria-label="Tip"><path d="M3.12794 12.4232C3.12794 12.5954 3.1776 12.7634 3.27244 12.907L3.74114 13.6095C3.88471 13.8248 4.21067 14 4.46964 14H6.15606C6.41415 14 6.74017 13.825 6.88373 13.6095L7.3508 12.9073C7.43114 12.7859 7.49705 12.569 7.49705 12.4232L7.50055 11.3513H3.12521L3.12794 12.4232ZM5.31288 0C2.52414 0.00875889 0.5 2.26889 0.5 4.78826C0.5 6.00188 0.949566 7.10829 1.69119 7.95492C2.14321 8.47011 2.84901 9.54727 3.11919 10.4557C3.12005 10.4625 3.12175 10.4698 3.12261 10.4771H7.50342C7.50427 10.4698 7.50598 10.463 7.50684 10.4557C7.77688 9.54727 8.48281 8.47011 8.93484 7.95492C9.67728 7.13181 10.1258 6.02703 10.1258 4.78826C10.1258 2.15486 7.9709 0.000106649 5.31288 0ZM7.94902 7.11267C7.52078 7.60079 6.99082 8.37878 6.6077 9.18794H4.02051C3.63739 8.37878 3.10743 7.60079 2.67947 7.11294C2.11997 6.47551 1.8126 5.63599 1.8126 4.78826C1.8126 3.09829 3.12794 1.31944 5.28827 1.3126C7.2435 1.3126 8.81315 2.88226 8.81315 4.78826C8.81315 5.63599 8.50688 6.47551 7.94902 7.11267ZM4.87534 2.18767C3.66939 2.18767 2.68767 3.16939 2.68767 4.37534C2.68767 4.61719 2.88336 4.81288 3.12521 4.81288C3.36705 4.81288 3.56274 4.61599 3.56274 4.37534C3.56274 3.6515 4.1515 3.06274 4.87534 3.06274C5.11719 3.06274 5.31288 2.86727 5.31288 2.62548C5.31288 2.38369 5.11599 2.18767 4.87534 2.18767Z"></path></svg>
      </div>
      <div class="text-sm prose dark:prose-invert min-w-0 w-full [&_kbd]:bg-background-light dark:[&_kbd]:bg-background-dark [&_code]:!text-current [&_kbd]:!text-current [&_a]:!text-current [&_a]:border-current [&_strong]:!text-current text-neutral-800 dark:text-neutral-300" data-component-part="callout-content">
        <strong>Example{title && ` - ${title}`}</strong>

        {children}
      </div>
    </aside>;
};

<Note>
  Focus requires a runtime that supports it. See [Focus Feature Support](/docs/feature-support#focus).
</Note>

Focus determines which element receives keyboard, text, and gamepad input. Only one element has primary focus at a time, but its focusable ancestors are also considered focused. For example, when a button inside a focusable menu has primary focus, the menu has focus too.

Users move focus by clicking an element, pressing **Tab** and **Shift+Tab**, or using the arrow keys, and your state machine can move focus with listener actions.

Focus is what makes your file usable without a pointer. Keyboard users, switch users, and gamepad players all rely on a predictable focus order to reach buttons, inputs, and other interactive elements.

## Making an element focusable

Any element in the hierarchy can receive focus once you add a focus node to it.

<Steps>
  <Step>
    Select the element you want to make focusable.
  </Step>

  <Step>
    In the Inspector, click **+** in the **Focus** section.
  </Step>

  <Step>
    Configure the [focus properties](#focus-properties).
  </Step>
</Steps>

<Tip>
  [Text inputs](/docs/editor/state-machine/listeners#text-input) and other elements need focus before they can receive typed text or key presses. If a **Keyboard** or **Text Input** listener isn't firing, check that its target has a focus node.
</Tip>

### Focus properties

| Property | Description |
| - | - |
| **Focusable** | Turns focus on or off for the element. When off, the element can't receive focus at all. |
| **Traversable** | Includes the element in **Tab**, **Shift+Tab**, and arrow-key navigation. When off, the element can still receive focus from a click or a **Focus** action, but users can't tab to it. |
| **Behavior** | Controls what happens when focus reaches the first or last element inside this one. See [Focus scopes](#focus-scopes). |

**Focusable** and **Traversable** can be keyed on the timeline and data bound, so you can turn focus on or off as your file changes state. For example, turn off **Focusable** on buttons behind a modal while the modal is open.

## Focus order

**Tab** moves focus to the next traversable element and **Shift+Tab** moves it to the previous one. The order follows the [hierarchy](/docs/editor/interface-overview/hierarchy), from top to bottom. To change the order, reorder the elements in the hierarchy.

The arrow keys move focus directionally, to the nearest focusable element in that direction on the canvas.

An element can't hold focus while it's hidden. If the focused element is collapsed, hidden, or has an opacity of 0, focus moves to the nearest focusable ancestor.

## Focus scopes

When an element with a focus node contains other focusable elements, it acts as a scope: its children form a group in the focus order. The scope's **Behavior** decides what happens when focus reaches the edge of the group.

| Behavior | Description |
| - | - |
| **Parent Scope** | Focus leaves the group and continues to the next element outside it. This is the default. |
| **Closed Loop** | Focus wraps from the last element back to the first, and from the first back to the last. Focus can't leave the group by tabbing. |
| **Stop** | Focus stays on the first or last element. |

<UseCase title="Trapping focus in a dialog">
  When a dialog is open, keyboard users shouldn't be able to tab to the content behind it. Add a focus node to the dialog's group and set **Behavior** to **Closed Loop**. Tabbing now cycles through the dialog's buttons until the dialog closes.
</UseCase>

## Reacting to focus

Use the [State Machine](/docs/editor/state-machine/state-machine) to show focus and respond to it.

* **Focus** and **Blur** [listeners](/docs/editor/state-machine/listeners#focus) fire when an element gains or loses focus. Because ancestors share focus, a **Focus** listener on a container fires when focus first enters it, and its **Blur** listener fires when focus leaves it. Moving focus between children inside the container doesn't fire either listener on the container. Use them to show a focus ring, highlight, or other visible focus indicator.
* A **Focus** [transition condition](/docs/editor/state-machine/transitions) checks whether a specific element currently has focus. The condition is true when the element or any of its focusable descendants has primary focus.
* **Keyboard** and **Text Input** listeners respond to input on the element with primary focus. If that element doesn't handle a key, the key passes up to its nearest focusable ancestor.

<Warning>
  Always give focused elements a visible focus indicator. Without one, keyboard users can't tell where they are.
</Warning>

## Moving focus with listener actions

Add a **Focus** action to a listener to move focus from your state machine. Choose a mode from the dropdown:

| Mode | Description |
| - | - |
| **target** | Moves focus to a specific element. The target must have a focus node. |
| **traverse** | Moves focus in a direction: **next**, **previous**, **up**, **down**, **left**, or **right**. |
| **clear** | Removes focus from the current element. |

For example, use **target** to focus a search field when a search button is clicked, or **clear** to remove focus when a menu closes.

## Previewing focus in the editor

When you play your file, the editor draws brackets around the element that has focus. Toggle **Focus Indicator** in the viewport options to show or hide them.

To send keys to your file instead of triggering editor shortcuts, press **Option+Space** to play with keyboard capture on, or click **Toggle Keyboard Capture** in the playback header.

## Focus and screen readers

Elements with a focus node automatically get the **Focusable** trait in the [Semantics](/docs/editor/accessibility/semantics) panel. Combine focus with semantics so assistive technologies can describe the focused element, such as announcing it as a button with a label.
