NEOLearn

Focus and navigation

Drive UI with the keyboard and gamepad: the InputFocus resource, focus rings, AutoFocus, Tab navigation with TabGroup and TabIndex, and directional navigation for gamepads.

Updated October 20, 2026

On this page

Input focus decides which UI element receives keyboard input: which text field you're typing into, which button Enter presses. A game menu that works with a gamepad also needs a way to move focus between buttons with the stick or d-pad. The engine's neo_input_focus crate does both, and NEO's builds include it.

The focused entity#

The InputFocus resource holds the focused entity, if any:

CallWhat it does
focus.get()Option<Entity>: the focused entity.
focus.set(entity, FocusCause::Pressed)Focus an entity. The cause is Navigated, Pressed or Auto.
focus.clear()Focus nothing.

InputFocusVisible(bool) is a resource that says whether to draw a focus indicator. It's set to true when the player navigates with the keyboard and false when they click, matching how browsers show focus rings.

Keyboard and gamepad input are sent to the focused entity as FocusedInput<M> events, which bubble up to its parents (and to the window if nothing is focused). Widgets such as text inputs listen for them, and so can your own observers.

When an entity gains or loses focus it receives FocusGained or FocusLost.

Draw a focus ring#

Rust
use neo::input_focus::{InputFocus, InputFocusVisible};

fn focus_ring(
    mut commands: Commands,
    focus: Res<InputFocus>,
    visible: Res<InputFocusVisible>,
    buttons: Query<Entity, With<neo::ui_widgets::Button>>,
) {
    if !focus.is_changed() && !visible.is_changed() {
        return;
    }
    for button in &buttons {
        if visible.0 && focus.get() == Some(button) {
            commands.entity(button).insert(Outline::new(px(2), px(2), Color::WHITE));
        } else {
            commands.entity(button).remove::<Outline>();
        }
    }
}

Focus something at start#

Add AutoFocus to an entity to focus it when it's spawned: the first button of a menu, the first field of a form, the confirm button of a dialog.

Clicking to focus#

The widget plugins that DefaultPlugins adds include pointer focus: clicking a focusable entity focuses it, and clicking elsewhere clears focus. Entities are focusable when they have Focusable, which Button, TextInput and the other widgets add for you.

Tab navigation#

Tab and Shift+Tab move focus through a form or menu. Add TabNavigationPlugin (it isn't in DefaultPlugins), wrap the elements in a TabGroup, and give each a TabIndex:

src/menu.rs
use neo::{
    input_focus::tab_navigation::{TabGroup, TabIndex, TabNavigationPlugin},
    prelude::*,
    ui_widgets::Button,
};

// in main: app.add_plugins((DefaultPlugins, TabNavigationPlugin));

fn spawn_menu(mut commands: Commands) {
    commands.spawn((
        Node { flex_direction: FlexDirection::Column, row_gap: px(8), ..default() },
        TabGroup::new(0),
        children![
            (Button, TabIndex(0), Node { padding: px(8).all(), ..default() }, children![Text::new("Play")]),
            (Button, TabIndex(1), Node { padding: px(8).all(), ..default() }, children![Text::new("Quit")]),
        ],
    ));
}

The rules follow HTML:

  • Lower TabIndex values come first. Equal values go in hierarchy order.
  • A negative TabIndex can be focused by clicking but is skipped by Tab.
  • A Focusable entity without a TabIndex counts as index 0.
  • Groups are visited in order of TabGroup::new(order). TabGroup::modal() keeps Tab inside the group, for dialogs.

A focused Button activates with Enter or Space, so a tab-navigable menu works without a mouse.

Directional navigation#

For gamepads and arrow keys, focus should move to the nearest element in the direction pressed. Add DirectionalNavigationPlugin and the AutoDirectionalNavigation component to each element; the engine works out the neighbours from where the elements are on screen:

Rust
use neo::{
    input_focus::directional_navigation::DirectionalNavigationPlugin,
    math::{CompassOctant, Dir2},
    prelude::*,
    ui::auto_directional_navigation::{AutoDirectionalNavigation, AutoDirectionalNavigator},
};

// in main: app.add_plugins((DefaultPlugins, DirectionalNavigationPlugin));
// on each button: AutoDirectionalNavigation::default()

fn navigate(keys: Res<ButtonInput<KeyCode>>, mut navigator: AutoDirectionalNavigator) {
    let x = keys.just_pressed(KeyCode::ArrowRight) as i8 - keys.just_pressed(KeyCode::ArrowLeft) as i8;
    let y = keys.just_pressed(KeyCode::ArrowUp) as i8 - keys.just_pressed(KeyCode::ArrowDown) as i8;
    if let Ok(dir) = Dir2::from_xy(x as f32, y as f32) {
        let _ = navigator.navigate(CompassOctant::from(dir));
    }
}

You map your own input to directions, so the same code serves the keyboard, the d-pad and the stick. Run it in PreUpdate, where input is handled. The AutoNavigationConfig resource tunes how neighbours are chosen (min_alignment_factor, max_search_distance, prefer_aligned).

Where automatic neighbours aren't what you want (wrapping from the last item to the first, or linking distant panels), add edges by hand to the DirectionalNavigationMap resource with add_edge, add_symmetrical_edge, add_looping_edges or block_edge. Manual edges win over automatic ones.

In NEO games, the input kit turns the same keyboard and gamepad into character controls. Block those with its InputGate while a menu is open, so navigating the menu doesn't also move the character; see Gameplay kit.

Examples#

ExampleWhat it shows
tab_navigationTab groups, indices and a modal group.
directional_navigationAutomatic directional navigation with keyboard and gamepad.
directional_navigation_overridesAutomatic navigation with manual edges.
text_inputFocus moving between text fields.

Run one from the engine core's workspace: cargo run --example directional_navigation.

Next steps#