From 45a49c1b4e6751ae9a0d5987801f1b6ff9a11f61 Mon Sep 17 00:00:00 2001
From: Kevin Chen <chen.kevin.f@gmail.com>
Date: Sun, 4 Jan 2026 16:22:22 -0500
Subject: [PATCH 01/25] docs: adds example combining auto and manual
 directional nav

---
 Cargo.toml                |  12 +
 examples/ui/navigation.rs | 503 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 515 insertions(+)
 create mode 100644 examples/ui/navigation.rs

diff --git a/Cargo.toml b/Cargo.toml
index dd904e1217590..6709c4a3e03c9 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -5103,6 +5103,18 @@ description = "Demonstration of automatic directional navigation graph generatio
 category = "UI (User Interface)"
 wasm = true
 
+[[example]]
+name = "navigation"
+path = "examples/ui/navigation.rs"
+# Causes an ICE on docs.rs
+doc-scrape-examples = false
+
+[package.metadata.example.navigation]
+name = "Navigation"
+description = "Demonstration of automatic and manual directional navigation between UI elements"
+category = "UI (User Interface)"
+wasm = true
+
 [[example]]
 name = "clustered_decals"
 path = "examples/3d/clustered_decals.rs"
diff --git a/examples/ui/navigation.rs b/examples/ui/navigation.rs
new file mode 100644
index 0000000000000..5de059179bfb0
--- /dev/null
+++ b/examples/ui/navigation.rs
@@ -0,0 +1,503 @@
+//! Demonstrates a combination of automatic directional navigation and manual directional navigation.
+//!
+//! This example shows how to leverage both automatic navigation and manual navigation to create
+//! a desired user navigation experience without much boilerplate code. The `AutoDirectionalNavigation`
+//! component is used to add basic, intuitive navigation to UI elements. Manual edges between certain
+//! UI elements are added to the `DirectionalNavigationMap` to override auto navigation and to add
+//! special navigation rules.
+//!
+//! The directional navigation system provided by `AutoDirectionalNavigator` uses manually defined edges
+//! first. If no manual edge is defined, automatic navigation is used.
+
+use core::time::Duration;
+
+use bevy::{
+    camera::NormalizedRenderTarget,
+    input_focus::{
+        directional_navigation::{
+            AutoNavigationConfig, DirectionalNavigationMap, DirectionalNavigationPlugin,
+        },
+        InputDispatchPlugin, InputFocus, InputFocusVisible,
+    },
+    math::{CompassOctant, Dir2},
+    picking::{
+        backend::HitData,
+        pointer::{Location, PointerId},
+    },
+    platform::collections::HashSet,
+    prelude::*,
+    ui::auto_directional_navigation::{AutoDirectionalNavigation, AutoDirectionalNavigator}
+};
+
+fn main() {
+    App::new()
+        // Input focus is not enabled by default, so we need to add the corresponding plugins
+        // The navigation system's resources are initialized by the DirectionalNavigationPlugin.
+        .add_plugins((
+            DefaultPlugins,
+            InputDispatchPlugin,
+            DirectionalNavigationPlugin,
+        ))
+        // This resource is canonically used to track whether or not to render a focus indicator
+        // It starts as false, but we set it to true here as we would like to see the focus indicator
+        .insert_resource(InputFocusVisible(true))
+        // Configure auto-navigation behavior
+        .insert_resource(AutoNavigationConfig {
+            // Require at least 10% overlap in perpendicular axis for cardinal directions
+            min_alignment_factor: 0.1,
+            // Don't connect nodes more than 500 pixels apart
+            max_search_distance: Some(500.0),
+            // Do not prefer nodes that are well-aligned. In a cascading layout, nodes may not be well-aligned.
+            prefer_aligned: false,
+        })
+        .init_resource::<ActionState>()
+        // For automatic navigation, UI entities will have the component `AutoDirectionalNavigation`
+        // and will be automatically connected by the navigation system.
+        // To override some automatically created navigation edges, manual edges are created
+        // in `setup_cascading_ui`. We will also add some new edges that the automatic navigation system
+        // does not create.
+        .add_systems(Startup, setup_cascading_ui)
+        // Input is generally handled during PreUpdate
+        .add_systems(PreUpdate, (process_inputs, navigate).chain())
+        .add_systems(
+            Update,
+            (
+                highlight_focused_element,
+                interact_with_focused_button,
+                reset_button_after_interaction,
+                update_focus_display,
+                update_key_display,
+            ),
+        )
+        .add_observer(universal_button_click_behavior)
+        .run();
+}
+
+const NORMAL_BUTTON: Srgba = bevy::color::palettes::tailwind::BLUE_400;
+const PRESSED_BUTTON: Srgba = bevy::color::palettes::tailwind::BLUE_500;
+const FOCUSED_BORDER: Srgba = bevy::color::palettes::tailwind::BLUE_50;
+
+/// Marker component for the text that displays the currently focused button
+#[derive(Component)]
+struct FocusDisplay;
+
+/// Marker component for the text that displays the last key pressed
+#[derive(Component)]
+struct KeyDisplay;
+
+// Observer for button clicks
+fn universal_button_click_behavior(
+    mut click: On<Pointer<Click>>,
+    mut button_query: Query<(&mut BackgroundColor, &mut ResetTimer)>,
+) {
+    let button_entity = click.entity;
+    if let Ok((mut color, mut reset_timer)) = button_query.get_mut(button_entity) {
+        color.0 = PRESSED_BUTTON.into();
+        reset_timer.0 = Timer::from_seconds(0.3, TimerMode::Once);
+        click.propagate(false);
+    }
+}
+
+#[derive(Component, Default, Deref, DerefMut)]
+struct ResetTimer(Timer);
+
+fn reset_button_after_interaction(
+    time: Res<Time>,
+    mut query: Query<(&mut ResetTimer, &mut BackgroundColor)>,
+) {
+    for (mut reset_timer, mut color) in query.iter_mut() {
+        reset_timer.tick(time.delta());
+        if reset_timer.just_finished() {
+            color.0 = NORMAL_BUTTON.into();
+        }
+    }
+}
+
+/// Spawn a cascading layout of buttons to demonstrate automatic and manual navigation.
+///
+/// This will create a grid of buttons, but each row cascades from the top left to the bottom right.
+/// Manual navigation will connect the end of one row with the beginning of the next row.
+/// Manual navigation will also make vertical navigation inverted (pressing down moves up)
+fn setup_cascading_ui(
+    mut commands: Commands,
+    mut manual_directional_nav_map: ResMut<DirectionalNavigationMap>,
+    mut input_focus: ResMut<InputFocus>,
+) {
+    commands.spawn(Camera2d);
+
+    // Create a full-screen background node
+    let root_node = commands
+        .spawn(Node {
+            width: percent(100),
+            height: percent(100),
+            ..default()
+        })
+        .id();
+
+    // Instructions
+    let instructions = commands
+        .spawn((
+            Text::new(
+                "Navigation Demo\n\n\
+                 Use arrow keys or D-pad to navigate.\n\
+                 Press Enter or A button to interact.\n\n\
+                 Buttons are scattered in cascading rows:\n\
+                 Horizontal navigation within rows is automatic.\n\
+                 Horizontal navigation between rows is manual.\n\
+                 Vertical navigation between rows is inverted and manual.",
+            ),
+            Node {
+                position_type: PositionType::Absolute,
+                left: px(20),
+                top: px(20),
+                width: px(280),
+                padding: UiRect::all(px(12)),
+                border_radius: BorderRadius::all(px(8)),
+                ..default()
+            },
+            BackgroundColor(Color::srgba(0.1, 0.1, 0.1, 0.8)),
+        ))
+        .id();
+
+    // Focus display - shows which button is currently focused
+    commands.spawn((
+        Text::new("Focused: None"),
+        FocusDisplay,
+        Node {
+            position_type: PositionType::Absolute,
+            left: px(20),
+            bottom: px(80),
+            width: px(280),
+            padding: UiRect::all(px(12)),
+            border_radius: BorderRadius::all(px(8)),
+            ..default()
+        },
+        BackgroundColor(Color::srgba(0.1, 0.5, 0.1, 0.8)),
+        TextFont {
+            font_size: 20.0,
+            ..default()
+        },
+    ));
+
+    // Key display - shows the last key pressed
+    commands.spawn((
+        Text::new("Last Key: None"),
+        KeyDisplay,
+        Node {
+            position_type: PositionType::Absolute,
+            left: px(20),
+            bottom: px(20),
+            width: px(280),
+            padding: UiRect::all(px(12)),
+            border_radius: BorderRadius::all(px(8)),
+            ..default()
+        },
+        BackgroundColor(Color::srgba(0.5, 0.1, 0.5, 0.8)),
+        TextFont {
+            font_size: 20.0,
+            ..default()
+        },
+    ));
+
+    // Spawn buttons in cascading rows
+    // Auto-navigation will configure navigation within rows.
+    let button_positions = [
+        // Row 0
+        [(350.0, 80.0), (550.0, 125.0), (750.0, 170.0)],
+        // Row 1
+        [(350.0, 215.0), (550.0, 260.0), (750.0, 305.0)],
+        // Row 2
+        [(350.0, 350.0), (550.0, 395.0), (750.0, 440.0)],
+        // Row 3
+        [(350.0, 485.0), (550.0, 530.0), (750.0, 575.0)],
+    ];
+
+    let mut first_button = None;
+    let mut entities = Vec::with_capacity(4);
+    for (i, row) in button_positions.iter().enumerate() {
+        for (j, (x, y)) in row.iter().enumerate() {
+            let button_entity = commands
+                .spawn((
+                    Button,
+                    Node {
+                        position_type: PositionType::Absolute,
+                        left: px(*x),
+                        top: px(*y),
+                        width: px(140),
+                        height: px(90),
+                        border: UiRect::all(px(4)),
+                        justify_content: JustifyContent::Center,
+                        align_items: AlignItems::Center,
+                        border_radius: BorderRadius::all(px(12)),
+                        ..default()
+                    },
+                    // This is the key: just add this component for automatic navigation!
+                    AutoDirectionalNavigation::default(),
+                    ResetTimer::default(),
+                    BackgroundColor::from(NORMAL_BUTTON),
+                    Name::new(format!("Row {}, Button {}", i + 1, j + 1)),
+                ))
+                .with_child((
+                    Text::new(format!("Row {}, Button {}", i + 1, j + 1)),
+                    TextLayout {
+                        justify: Justify::Center,
+                        ..default()
+                    },
+                ))
+                .id();
+
+            if first_button.is_none() {
+                first_button = Some(button_entity);
+            }
+            entities.push(button_entity);
+        }
+    }
+
+    // Add manual edges for inverted vertical navigation
+    // These manual edges override any automatic navigation vertically
+    let mut col = Vec::with_capacity(4);
+    for col_index in 0..=2 {
+        for (i, &entity) in entities.iter().enumerate() {
+            if i % 3 == col_index {
+                col.push(entity);
+            }
+        }
+        // edges are connected in the opposite vertical direction
+        manual_directional_nav_map.add_looping_edges(&col, CompassOctant::North);
+        col.clear();
+    }
+
+    // Add manual edges for navigation between rows
+    // These manual edges do not override any automatic navigation
+    let entity_pairs = [
+        // the end of the first row should connect to the beginning of the second
+        ((0, 2), (1, 0)),
+        // the end of the second row should connect to the beginning of the third
+        ((1, 2), (2, 0)),
+        // the end of the third row should connect to the beginning of the fourth
+        ((2, 2), (3, 0)),
+        // the end of the fourth row should connect to the beginning of the first (the end wraps to the beginning)
+        ((3, 2), (0, 0)),
+    ];
+    for ((entity_a_row, entity_a_col), (entity_b_row, entity_b_col)) in entity_pairs.iter() {
+        manual_directional_nav_map.add_symmetrical_edge(
+            entities[entity_a_row * 3 + entity_a_col],
+            entities[entity_b_row * 3 + entity_b_col],
+            CompassOctant::East,
+        );
+    }
+
+    commands.entity(root_node).add_children(&[instructions]);
+
+    // Set initial focus
+    if let Some(button) = first_button {
+        input_focus.set(button);
+    }
+}
+
+// Action state and input handling (same as the manual navigation example)
+#[derive(Debug, PartialEq, Eq, Hash)]
+enum DirectionalNavigationAction {
+    Up,
+    Down,
+    Left,
+    Right,
+    Select,
+}
+
+impl DirectionalNavigationAction {
+    fn variants() -> Vec<Self> {
+        vec![
+            DirectionalNavigationAction::Up,
+            DirectionalNavigationAction::Down,
+            DirectionalNavigationAction::Left,
+            DirectionalNavigationAction::Right,
+            DirectionalNavigationAction::Select,
+        ]
+    }
+
+    fn keycode(&self) -> KeyCode {
+        match self {
+            DirectionalNavigationAction::Up => KeyCode::ArrowUp,
+            DirectionalNavigationAction::Down => KeyCode::ArrowDown,
+            DirectionalNavigationAction::Left => KeyCode::ArrowLeft,
+            DirectionalNavigationAction::Right => KeyCode::ArrowRight,
+            DirectionalNavigationAction::Select => KeyCode::Enter,
+        }
+    }
+
+    fn gamepad_button(&self) -> GamepadButton {
+        match self {
+            DirectionalNavigationAction::Up => GamepadButton::DPadUp,
+            DirectionalNavigationAction::Down => GamepadButton::DPadDown,
+            DirectionalNavigationAction::Left => GamepadButton::DPadLeft,
+            DirectionalNavigationAction::Right => GamepadButton::DPadRight,
+            DirectionalNavigationAction::Select => GamepadButton::South,
+        }
+    }
+}
+
+#[derive(Default, Resource)]
+struct ActionState {
+    pressed_actions: HashSet<DirectionalNavigationAction>,
+}
+
+fn process_inputs(
+    mut action_state: ResMut<ActionState>,
+    keyboard_input: Res<ButtonInput<KeyCode>>,
+    gamepad_input: Query<&Gamepad>,
+) {
+    action_state.pressed_actions.clear();
+
+    for action in DirectionalNavigationAction::variants() {
+        if keyboard_input.just_pressed(action.keycode()) {
+            action_state.pressed_actions.insert(action);
+        }
+    }
+
+    for gamepad in gamepad_input.iter() {
+        for action in DirectionalNavigationAction::variants() {
+            if gamepad.just_pressed(action.gamepad_button()) {
+                action_state.pressed_actions.insert(action);
+            }
+        }
+    }
+}
+
+fn navigate(action_state: Res<ActionState>, mut auto_directional_navigator: AutoDirectionalNavigator) {
+    let net_east_west = action_state
+        .pressed_actions
+        .contains(&DirectionalNavigationAction::Right) as i8
+        - action_state
+            .pressed_actions
+            .contains(&DirectionalNavigationAction::Left) as i8;
+
+    let net_north_south = action_state
+        .pressed_actions
+        .contains(&DirectionalNavigationAction::Up) as i8
+        - action_state
+            .pressed_actions
+            .contains(&DirectionalNavigationAction::Down) as i8;
+
+    // Use Dir2::from_xy to convert input to direction, then convert to CompassOctant
+    let maybe_direction = Dir2::from_xy(net_east_west as f32, net_north_south as f32)
+        .ok()
+        .map(CompassOctant::from);
+
+    if let Some(direction) = maybe_direction {
+        match auto_directional_navigator.navigate(direction) {
+            Ok(_entity) => {
+                // Successfully navigated
+            }
+            Err(_e) => {
+                // Navigation failed (no neighbor in that direction)
+            }
+        }
+    }
+}
+
+fn update_focus_display(
+    input_focus: Res<InputFocus>,
+    button_query: Query<&Name, With<Button>>,
+    mut display_query: Query<&mut Text, With<FocusDisplay>>,
+) {
+    if let Ok(mut text) = display_query.single_mut() {
+        if let Some(focused_entity) = input_focus.0 {
+            if let Ok(name) = button_query.get(focused_entity) {
+                **text = format!("Focused: {}", name);
+            } else {
+                **text = "Focused: Unknown".to_string();
+            }
+        } else {
+            **text = "Focused: None".to_string();
+        }
+    }
+}
+
+fn update_key_display(
+    keyboard_input: Res<ButtonInput<KeyCode>>,
+    gamepad_input: Query<&Gamepad>,
+    mut display_query: Query<&mut Text, With<KeyDisplay>>,
+) {
+    if let Ok(mut text) = display_query.single_mut() {
+        // Check for keyboard inputs
+        for action in DirectionalNavigationAction::variants() {
+            if keyboard_input.just_pressed(action.keycode()) {
+                let key_name = match action {
+                    DirectionalNavigationAction::Up => "Up Arrow",
+                    DirectionalNavigationAction::Down => "Down Arrow",
+                    DirectionalNavigationAction::Left => "Left Arrow",
+                    DirectionalNavigationAction::Right => "Right Arrow",
+                    DirectionalNavigationAction::Select => "Enter",
+                };
+                **text = format!("Last Key: {}", key_name);
+                return;
+            }
+        }
+
+        // Check for gamepad inputs
+        for gamepad in gamepad_input.iter() {
+            for action in DirectionalNavigationAction::variants() {
+                if gamepad.just_pressed(action.gamepad_button()) {
+                    let button_name = match action {
+                        DirectionalNavigationAction::Up => "D-Pad Up",
+                        DirectionalNavigationAction::Down => "D-Pad Down",
+                        DirectionalNavigationAction::Left => "D-Pad Left",
+                        DirectionalNavigationAction::Right => "D-Pad Right",
+                        DirectionalNavigationAction::Select => "A Button",
+                    };
+                    **text = format!("Last Key: {}", button_name);
+                    return;
+                }
+            }
+        }
+    }
+}
+
+fn highlight_focused_element(
+    input_focus: Res<InputFocus>,
+    input_focus_visible: Res<InputFocusVisible>,
+    mut query: Query<(Entity, &mut BorderColor)>,
+) {
+    for (entity, mut border_color) in query.iter_mut() {
+        if input_focus.0 == Some(entity) && input_focus_visible.0 {
+            *border_color = BorderColor::all(FOCUSED_BORDER);
+        } else {
+            *border_color = BorderColor::DEFAULT;
+        }
+    }
+}
+
+fn interact_with_focused_button(
+    action_state: Res<ActionState>,
+    input_focus: Res<InputFocus>,
+    mut commands: Commands,
+) {
+    if action_state
+        .pressed_actions
+        .contains(&DirectionalNavigationAction::Select)
+        && let Some(focused_entity) = input_focus.0
+    {
+        commands.trigger(Pointer::<Click> {
+            entity: focused_entity,
+            pointer_id: PointerId::Mouse,
+            pointer_location: Location {
+                target: NormalizedRenderTarget::None {
+                    width: 0,
+                    height: 0,
+                },
+                position: Vec2::ZERO,
+            },
+            event: Click {
+                button: PointerButton::Primary,
+                hit: HitData {
+                    camera: Entity::PLACEHOLDER,
+                    depth: 0.0,
+                    position: None,
+                    normal: None,
+                },
+                duration: Duration::from_secs_f32(0.1),
+            },
+        });
+    }
+}

From 6603d48c83ae375ed148bdc0c2ea3563c55dca34 Mon Sep 17 00:00:00 2001
From: Kevin Chen <chen.kevin.f@gmail.com>
Date: Tue, 6 Jan 2026 16:39:46 -0500
Subject: [PATCH 02/25] style: fmts and docs: update README with new example

---
 examples/README.md        | 1 +
 examples/ui/navigation.rs | 7 +++++--
 2 files changed, 6 insertions(+), 2 deletions(-)

diff --git a/examples/README.md b/examples/README.md
index 487832ecb3543..93b4c3e589192 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -582,6 +582,7 @@ Example | Description
 [Font Weights](../examples/ui/font_weights.rs) | Demonstrates how to use font weights.
 [Ghost Nodes](../examples/ui/ghost_nodes.rs) | Demonstrates the use of Ghost Nodes to skip entities in the UI layout hierarchy
 [Gradients](../examples/ui/gradients.rs) | An example demonstrating gradients
+[Navigation](../examples/ui/navigation.rs) | Demonstration of automatic and manual directional navigation between UI elements
 [Overflow](../examples/ui/overflow.rs) | Simple example demonstrating overflow behavior
 [Overflow Clip Margin](../examples/ui/overflow_clip_margin.rs) | Simple example demonstrating the OverflowClipMargin style property
 [Overflow and Clipping Debug](../examples/ui/overflow_debug.rs) | An example to debug overflow and clipping behavior
diff --git a/examples/ui/navigation.rs b/examples/ui/navigation.rs
index 5de059179bfb0..f220f48729bc6 100644
--- a/examples/ui/navigation.rs
+++ b/examples/ui/navigation.rs
@@ -26,7 +26,7 @@ use bevy::{
     },
     platform::collections::HashSet,
     prelude::*,
-    ui::auto_directional_navigation::{AutoDirectionalNavigation, AutoDirectionalNavigator}
+    ui::auto_directional_navigation::{AutoDirectionalNavigation, AutoDirectionalNavigator},
 };
 
 fn main() {
@@ -364,7 +364,10 @@ fn process_inputs(
     }
 }
 
-fn navigate(action_state: Res<ActionState>, mut auto_directional_navigator: AutoDirectionalNavigator) {
+fn navigate(
+    action_state: Res<ActionState>,
+    mut auto_directional_navigator: AutoDirectionalNavigator,
+) {
     let net_east_west = action_state
         .pressed_actions
         .contains(&DirectionalNavigationAction::Right) as i8

From 5df493d748ae7c00f6ecc85f1f079be1fe410c23 Mon Sep 17 00:00:00 2001
From: Kevin Chen <chen.kevin.f@gmail.com>
Date: Sun, 11 Jan 2026 14:35:11 -0500
Subject: [PATCH 03/25] refactor: renames and moves around navigation examples.
 edits some comments

---
 Cargo.toml                                    | 28 +++++++++----------
 examples/README.md                            |  6 ++--
 .../auto_navigation.rs}                       |  8 ++++--
 .../combined_navigation.rs}                   |  0
 .../manual_navigation.rs}                     |  7 +++--
 5 files changed, 26 insertions(+), 23 deletions(-)
 rename examples/ui/{auto_directional_navigation.rs => navigation/auto_navigation.rs} (98%)
 rename examples/ui/{navigation.rs => navigation/combined_navigation.rs} (100%)
 rename examples/ui/{directional_navigation.rs => navigation/manual_navigation.rs} (98%)

diff --git a/Cargo.toml b/Cargo.toml
index 6709c4a3e03c9..b1ed944dbb1a0 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -5080,38 +5080,38 @@ category = "UI (User Interface)"
 wasm = true
 
 [[example]]
-name = "directional_navigation"
-path = "examples/ui/directional_navigation.rs"
+name = "manual_navigation"
+path = "examples/ui/navigation/manual_navigation.rs"
 # Causes an ICE on docs.rs
 doc-scrape-examples = false
 
-[package.metadata.example.directional_navigation]
-name = "Directional Navigation"
-description = "Demonstration of Directional Navigation between UI elements"
+[package.metadata.example.manual_navigation]
+name = "Manual Directional Navigation"
+description = "Demonstration of manually-defined navigation between UI elements"
 category = "UI (User Interface)"
 wasm = true
 
 [[example]]
-name = "auto_directional_navigation"
-path = "examples/ui/auto_directional_navigation.rs"
+name = "auto_navigation"
+path = "examples/ui/navigation/auto_navigation.rs"
 # Causes an ICE on docs.rs
 doc-scrape-examples = false
 
-[package.metadata.example.auto_directional_navigation]
+[package.metadata.example.auto_navigation]
 name = "Automatic Directional Navigation"
-description = "Demonstration of automatic directional navigation graph generation based on UI element positions"
+description = "Demonstration of automatic navigation based on UI element positions"
 category = "UI (User Interface)"
 wasm = true
 
 [[example]]
-name = "navigation"
-path = "examples/ui/navigation.rs"
+name = "combined_navigation"
+path = "examples/ui/navigation/combined_navigation.rs"
 # Causes an ICE on docs.rs
 doc-scrape-examples = false
 
-[package.metadata.example.navigation]
-name = "Navigation"
-description = "Demonstration of automatic and manual directional navigation between UI elements"
+[package.metadata.example.combined_navigation]
+name = "Combined (Automatic + Manual) Directional Navigation"
+description = "Demonstration of combining both automatic and manual directional navigation between UI elements"
 category = "UI (User Interface)"
 wasm = true
 
diff --git a/examples/README.md b/examples/README.md
index 93b4c3e589192..da8971267a5f5 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -567,12 +567,12 @@ Example | Description
 Example | Description
 --- | ---
 [Anchor Layout](../examples/ui/anchor_layout.rs) | Shows an 'anchor layout' style of ui layout
-[Automatic Directional Navigation](../examples/ui/auto_directional_navigation.rs) | Demonstration of automatic directional navigation graph generation based on UI element positions
+[Automatic Directional Navigation](../examples/ui/navigation/auto_navigation.rs) | Demonstration of automatic navigation based on UI element positions
 [Borders](../examples/ui/borders.rs) | Demonstrates how to create a node with a border
 [Box Shadow](../examples/ui/box_shadow.rs) | Demonstrates how to create a node with a shadow
 [Button](../examples/ui/button.rs) | Illustrates creating and updating a button
 [CSS Grid](../examples/ui/grid.rs) | An example for CSS Grid layout
-[Directional Navigation](../examples/ui/directional_navigation.rs) | Demonstration of Directional Navigation between UI elements
+[Combined (Automatic + Manual) Directional Navigation](../examples/ui/navigation/combined_navigation.rs) | Demonstration of combining both automatic and manual directional navigation between UI elements
 [Display and Visibility](../examples/ui/display_and_visibility.rs) | Demonstrates how Display and Visibility work in the UI.
 [Drag to Scroll](../examples/ui/drag_to_scroll.rs) | This example tests scale factor, dragging and scrolling
 [Feathers Widgets](../examples/ui/feathers.rs) | Gallery of Feathers Widgets
@@ -582,7 +582,7 @@ Example | Description
 [Font Weights](../examples/ui/font_weights.rs) | Demonstrates how to use font weights.
 [Ghost Nodes](../examples/ui/ghost_nodes.rs) | Demonstrates the use of Ghost Nodes to skip entities in the UI layout hierarchy
 [Gradients](../examples/ui/gradients.rs) | An example demonstrating gradients
-[Navigation](../examples/ui/navigation.rs) | Demonstration of automatic and manual directional navigation between UI elements
+[Manual Directional Navigation](../examples/ui/navigation/manual_navigation.rs) | Demonstration of manually-defined navigation between UI elements
 [Overflow](../examples/ui/overflow.rs) | Simple example demonstrating overflow behavior
 [Overflow Clip Margin](../examples/ui/overflow_clip_margin.rs) | Simple example demonstrating the OverflowClipMargin style property
 [Overflow and Clipping Debug](../examples/ui/overflow_debug.rs) | An example to debug overflow and clipping behavior
diff --git a/examples/ui/auto_directional_navigation.rs b/examples/ui/navigation/auto_navigation.rs
similarity index 98%
rename from examples/ui/auto_directional_navigation.rs
rename to examples/ui/navigation/auto_navigation.rs
index 4bd63946f6f44..d834060a78129 100644
--- a/examples/ui/auto_directional_navigation.rs
+++ b/examples/ui/navigation/auto_navigation.rs
@@ -1,8 +1,8 @@
 //! Demonstrates automatic directional navigation with zero configuration.
 //!
-//! Unlike the manual `directional_navigation` example, this shows how to use automatic
+//! Unlike the `manual_navigation` example, this shows how to use automatic
 //! navigation by simply adding the `AutoDirectionalNavigation` component to UI elements.
-//! The navigation graph is automatically built and maintained based on screen positions.
+//! Navigation is automatically calculated based on screen positions.
 //!
 //! This is especially useful for:
 //! - Dynamic UIs where elements may be added, removed, or repositioned
@@ -11,6 +11,9 @@
 //!
 //! The automatic system finds the nearest neighbor in each compass direction for every node,
 //! completely eliminating the need to manually specify navigation relationships.
+//!
+//! For an example that combines automatic and manual navigation, refer to the
+//! `combined_navigation` example.
 
 use core::time::Duration;
 
@@ -52,7 +55,6 @@ fn main() {
         })
         .init_resource::<ActionState>()
         .add_systems(Startup, setup_scattered_ui)
-        // Navigation graph is automatically maintained by DirectionalNavigationPlugin!
         // No manual system needed - just add AutoDirectionalNavigation to entities.
         // Input is generally handled during PreUpdate
         .add_systems(PreUpdate, (process_inputs, navigate).chain())
diff --git a/examples/ui/navigation.rs b/examples/ui/navigation/combined_navigation.rs
similarity index 100%
rename from examples/ui/navigation.rs
rename to examples/ui/navigation/combined_navigation.rs
diff --git a/examples/ui/directional_navigation.rs b/examples/ui/navigation/manual_navigation.rs
similarity index 98%
rename from examples/ui/directional_navigation.rs
rename to examples/ui/navigation/manual_navigation.rs
index 9592ef984743a..05c328ff521d0 100644
--- a/examples/ui/directional_navigation.rs
+++ b/examples/ui/navigation/manual_navigation.rs
@@ -1,12 +1,13 @@
-//! Demonstrates how to set up the directional navigation system to allow for navigation between widgets.
+//! Demonstrates how to set up a manual directional navigation system to allow for navigation between widgets.
 //!
 //! Directional navigation is generally used to move between widgets in a user interface using arrow keys or gamepad input.
 //! When compared to tab navigation, directional navigation is generally more direct, and less aware of the structure of the UI.
 //!
 //! In this example, we will set up a simple UI with a grid of buttons that can be navigated using the arrow keys or gamepad input.
 //!
-//! **Note:** This example shows manual graph construction for full control. For automatic graph generation
-//! based on node positions, see the `auto_directional_navigation` example.
+//! **Note:** This example shows manual graph construction for full control. For automatic navigation
+//! based on node positions, see the `auto_navigation` example. For combining both automatic and manual navigation,
+//! see the `combined_navigation` example.
 
 use std::time::Duration;
 

From 665f8b82edc68c40add28c01ce1d4337803594f3 Mon Sep 17 00:00:00 2001
From: Kevin Chen <chen.kevin.f@gmail.com>
Date: Sun, 11 Jan 2026 16:31:14 -0500
Subject: [PATCH 04/25] fix: update_focus_display only if changed

---
 examples/ui/navigation/auto_navigation.rs     | 3 ++-
 examples/ui/navigation/combined_navigation.rs | 3 ++-
 2 files changed, 4 insertions(+), 2 deletions(-)

diff --git a/examples/ui/navigation/auto_navigation.rs b/examples/ui/navigation/auto_navigation.rs
index d834060a78129..6508d750b5b42 100644
--- a/examples/ui/navigation/auto_navigation.rs
+++ b/examples/ui/navigation/auto_navigation.rs
@@ -64,7 +64,8 @@ fn main() {
                 highlight_focused_element,
                 interact_with_focused_button,
                 reset_button_after_interaction,
-                update_focus_display,
+                update_focus_display
+                    .run_if(|input_focus: Res<InputFocus>| input_focus.is_changed()),
                 update_key_display,
             ),
         )
diff --git a/examples/ui/navigation/combined_navigation.rs b/examples/ui/navigation/combined_navigation.rs
index f220f48729bc6..cf799dd64a672 100644
--- a/examples/ui/navigation/combined_navigation.rs
+++ b/examples/ui/navigation/combined_navigation.rs
@@ -65,7 +65,8 @@ fn main() {
                 highlight_focused_element,
                 interact_with_focused_button,
                 reset_button_after_interaction,
-                update_focus_display,
+                update_focus_display
+                    .run_if(|input_focus: Res<InputFocus>| input_focus.is_changed()),
                 update_key_display,
             ),
         )

From c08a59f9a9b8871aabcc832b5261be6958037580 Mon Sep 17 00:00:00 2001
From: Kevin Chen <chen.kevin.f@gmail.com>
Date: Sun, 11 Jan 2026 19:46:42 -0500
Subject: [PATCH 05/25] docs: updates combined example to use pages of buttons

---
 examples/ui/navigation/combined_navigation.rs | 176 +++++++++++-------
 1 file changed, 107 insertions(+), 69 deletions(-)

diff --git a/examples/ui/navigation/combined_navigation.rs b/examples/ui/navigation/combined_navigation.rs
index cf799dd64a672..1b95574544260 100644
--- a/examples/ui/navigation/combined_navigation.rs
+++ b/examples/ui/navigation/combined_navigation.rs
@@ -1,18 +1,23 @@
-//! Demonstrates a combination of automatic directional navigation and manual directional navigation.
+//! Demonstrates a combination of automatic and manual directional navigation.
 //!
 //! This example shows how to leverage both automatic navigation and manual navigation to create
-//! a desired user navigation experience without much boilerplate code. The `AutoDirectionalNavigation`
-//! component is used to add basic, intuitive navigation to UI elements. Manual edges between certain
-//! UI elements are added to the `DirectionalNavigationMap` to override auto navigation and to add
-//! special navigation rules.
-//!
-//! The directional navigation system provided by `AutoDirectionalNavigator` uses manually defined edges
-//! first. If no manual edge is defined, automatic navigation is used.
+//! a desired user navigation experience without much boilerplate code. In this example, there are
+//! multiple pages of UI Buttons. The desired navigation experience cycles through buttons like
+//! reading a book written in English: from left to right. Navigation transitions to a new row
+//! after moving right at the end of the previous row. At the end of a page, moving right goes
+//! to the next page. Navigation within a row uses automatic navigation. Navigation between rows
+//! and between pages can only be setup manually.
+//! 
+//! The `AutoDirectionalNavigation` component is used to add basic, intuitive navigation to UI
+//! elements within a page. Manual edges between rows and between pages are added to the 
+//! `DirectionalNavigationMap` to add special navigation rules. The `AutoDirectionalNavigator`
+//! system parameter navigates with the map and the components.
 
 use core::time::Duration;
 
 use bevy::{
     camera::NormalizedRenderTarget,
+    color::palettes::css::*,
     input_focus::{
         directional_navigation::{
             AutoNavigationConfig, DirectionalNavigationMap, DirectionalNavigationPlugin,
@@ -142,10 +147,9 @@ fn setup_cascading_ui(
                 "Navigation Demo\n\n\
                  Use arrow keys or D-pad to navigate.\n\
                  Press Enter or A button to interact.\n\n\
-                 Buttons are scattered in cascading rows:\n\
-                 Horizontal navigation within rows is automatic.\n\
-                 Horizontal navigation between rows is manual.\n\
-                 Vertical navigation between rows is inverted and manual.",
+                 Horizontal navigation within rows is defined automatically.\n\
+                 Horizontal navigation between rows is defined manually.\n\
+                 Navigation between pages is defined manually.",
             ),
             Node {
                 position_type: PositionType::Absolute,
@@ -204,19 +208,81 @@ fn setup_cascading_ui(
     // Auto-navigation will configure navigation within rows.
     let button_positions = [
         // Row 0
-        [(350.0, 80.0), (550.0, 125.0), (750.0, 170.0)],
+        [(500.0, 80.0), (700.0, 80.0), (900.0, 80.0)],
         // Row 1
-        [(350.0, 215.0), (550.0, 260.0), (750.0, 305.0)],
+        [(500.0, 215.0), (700.0, 215.0), (900.0, 215.0)],
         // Row 2
-        [(350.0, 350.0), (550.0, 395.0), (750.0, 440.0)],
+        [(500.0, 350.0), (700.0, 350.0), (900.0, 350.0)],
         // Row 3
-        [(350.0, 485.0), (550.0, 530.0), (750.0, 575.0)],
+        [(500.0, 485.0), (700.0, 485.0), (900.0, 485.0)],
+    ];
+
+    let mut pages = [Vec::with_capacity(12), Vec::with_capacity(12), Vec::with_capacity(12)];
+    for (page_num, page_entities) in pages.iter_mut().enumerate() {
+        setup_buttons_for_page(&mut commands, page_num, page_entities, &button_positions);
+
+        // Only the first page is visible at setup.
+        let visibility = if page_num == 0 {
+            Visibility::Visible
+        } else {
+            Visibility::Hidden
+        };
+        let page = commands.spawn((Node {
+            width: percent(100),
+            height: percent(100),
+            ..default()
+        }, visibility))
+        .id();
+        commands.entity(page).add_children(&page_entities);
+    }
+    let first_button = Some(pages[0][0]);
+
+    // Add manual edges within each page for navigation between rows
+    let entity_pairs = [
+        // the end of the first row should connect to the beginning of the second
+        ((0, 2), (1, 0)),
+        // the end of the second row should connect to the beginning of the third
+        ((1, 2), (2, 0)),
+        // the end of the third row should connect to the beginning of the fourth
+        ((2, 2), (3, 0)),
     ];
+    for page_entities in pages.iter() {
+        for ((entity_a_row, entity_a_col), (entity_b_row, entity_b_col)) in entity_pairs.iter() {
+            manual_directional_nav_map.add_symmetrical_edge(
+                page_entities[entity_a_row * 3 + entity_a_col],
+                page_entities[entity_b_row * 3 + entity_b_col],
+                CompassOctant::East,
+            );
+        }
+    }
+
+    // Add manual edges between pages
+    manual_directional_nav_map.add_symmetrical_edge(pages[0][11], pages[1][0], CompassOctant::East); 
+    manual_directional_nav_map.add_symmetrical_edge(pages[1][11], pages[2][0], CompassOctant::East); 
+    manual_directional_nav_map.add_symmetrical_edge(pages[2][11], pages[0][0], CompassOctant::East); 
 
-    let mut first_button = None;
-    let mut entities = Vec::with_capacity(4);
+    commands.entity(root_node).add_children(&[instructions]);
+
+    // Set initial focus
+    if let Some(button) = first_button {
+        input_focus.set(button);
+    }
+}
+
+fn setup_buttons_for_page(
+    commands: &mut Commands,
+    page_num: usize,
+    page_entities: &mut Vec<Entity>, 
+    button_positions: &[[(f64, f64); 3]; 4]) {
     for (i, row) in button_positions.iter().enumerate() {
         for (j, (x, y)) in row.iter().enumerate() {
+            let background_color = if page_num == 0 {
+                RED.into()
+            } else if page_num == 1 {
+                GREEN.into()
+            } else {
+                BLUE.into()
+            };
             let button_entity = commands
                 .spawn((
                     Button,
@@ -225,74 +291,29 @@ fn setup_cascading_ui(
                         left: px(*x),
                         top: px(*y),
                         width: px(140),
-                        height: px(90),
+                        height: px(100),
                         border: UiRect::all(px(4)),
                         justify_content: JustifyContent::Center,
                         align_items: AlignItems::Center,
                         border_radius: BorderRadius::all(px(12)),
                         ..default()
                     },
+                    BackgroundColor(background_color),
                     // This is the key: just add this component for automatic navigation!
                     AutoDirectionalNavigation::default(),
                     ResetTimer::default(),
-                    BackgroundColor::from(NORMAL_BUTTON),
-                    Name::new(format!("Row {}, Button {}", i + 1, j + 1)),
+                    Name::new(format!("Page {},\nRow {},\nButton {}", page_num + 1, i + 1, j + 1)),
                 ))
                 .with_child((
-                    Text::new(format!("Row {}, Button {}", i + 1, j + 1)),
+                    Text::new(format!("Page {},\nRow {},\nButton {}", page_num + 1, i + 1, j + 1)),
                     TextLayout {
                         justify: Justify::Center,
                         ..default()
                     },
                 ))
                 .id();
-
-            if first_button.is_none() {
-                first_button = Some(button_entity);
-            }
-            entities.push(button_entity);
-        }
-    }
-
-    // Add manual edges for inverted vertical navigation
-    // These manual edges override any automatic navigation vertically
-    let mut col = Vec::with_capacity(4);
-    for col_index in 0..=2 {
-        for (i, &entity) in entities.iter().enumerate() {
-            if i % 3 == col_index {
-                col.push(entity);
-            }
+            page_entities.push(button_entity);
         }
-        // edges are connected in the opposite vertical direction
-        manual_directional_nav_map.add_looping_edges(&col, CompassOctant::North);
-        col.clear();
-    }
-
-    // Add manual edges for navigation between rows
-    // These manual edges do not override any automatic navigation
-    let entity_pairs = [
-        // the end of the first row should connect to the beginning of the second
-        ((0, 2), (1, 0)),
-        // the end of the second row should connect to the beginning of the third
-        ((1, 2), (2, 0)),
-        // the end of the third row should connect to the beginning of the fourth
-        ((2, 2), (3, 0)),
-        // the end of the fourth row should connect to the beginning of the first (the end wraps to the beginning)
-        ((3, 2), (0, 0)),
-    ];
-    for ((entity_a_row, entity_a_col), (entity_b_row, entity_b_col)) in entity_pairs.iter() {
-        manual_directional_nav_map.add_symmetrical_edge(
-            entities[entity_a_row * 3 + entity_a_col],
-            entities[entity_b_row * 3 + entity_b_col],
-            CompassOctant::East,
-        );
-    }
-
-    commands.entity(root_node).add_children(&[instructions]);
-
-    // Set initial focus
-    if let Some(button) = first_button {
-        input_focus.set(button);
     }
 }
 
@@ -367,6 +388,8 @@ fn process_inputs(
 
 fn navigate(
     action_state: Res<ActionState>,
+    parent_query: Query<&ChildOf>,
+    mut visibility_query: Query<&mut Visibility>,
     mut auto_directional_navigator: AutoDirectionalNavigator,
 ) {
     let net_east_west = action_state
@@ -388,10 +411,25 @@ fn navigate(
         .ok()
         .map(CompassOctant::from);
 
+    let previous_focus = auto_directional_navigator.manual_directional_navigation.focus.0;
     if let Some(direction) = maybe_direction {
         match auto_directional_navigator.navigate(direction) {
-            Ok(_entity) => {
+            Ok(new_focus) => {
                 // Successfully navigated
+
+                // If switching between pages, change visibilities of pages.
+                if let Ok(current_child_of) = parent_query.get(new_focus) && 
+                   let Ok(mut current_page_visibility) = visibility_query.get_mut(current_child_of.parent())  {
+                    *current_page_visibility = Visibility::Visible;
+
+                    if let Some(previous_focus_entity) = previous_focus &&
+                    let Ok(previous_child_of) = parent_query.get(previous_focus_entity) && 
+                    previous_child_of.parent() != current_child_of.parent() &&
+                    let Ok(mut previous_page_visibility) = visibility_query.get_mut(previous_child_of.parent()) 
+                    {
+                        *previous_page_visibility = Visibility::Hidden;
+                    }
+                }
             }
             Err(_e) => {
                 // Navigation failed (no neighbor in that direction)

From 04223e2e6330f2453ba712c9a8f5858405418d88 Mon Sep 17 00:00:00 2001
From: Kevin Chen <chen.kevin.f@gmail.com>
Date: Sun, 11 Jan 2026 22:38:40 -0500
Subject: [PATCH 06/25] docs: adds finishing ui touches to example

---
 examples/ui/navigation/combined_navigation.rs | 229 +++++++++++++-----
 1 file changed, 165 insertions(+), 64 deletions(-)

diff --git a/examples/ui/navigation/combined_navigation.rs b/examples/ui/navigation/combined_navigation.rs
index 1b95574544260..51df65c875c6f 100644
--- a/examples/ui/navigation/combined_navigation.rs
+++ b/examples/ui/navigation/combined_navigation.rs
@@ -2,14 +2,14 @@
 //!
 //! This example shows how to leverage both automatic navigation and manual navigation to create
 //! a desired user navigation experience without much boilerplate code. In this example, there are
-//! multiple pages of UI Buttons. The desired navigation experience cycles through buttons like
-//! reading a book written in English: from left to right. Navigation transitions to a new row
-//! after moving right at the end of the previous row. At the end of a page, moving right goes
-//! to the next page. Navigation within a row uses automatic navigation. Navigation between rows
-//! and between pages can only be setup manually.
-//! 
+//! multiple pages of UI Buttons. When navigating within the button grid on a page (up, down, left
+//! and right), automatic navigation is used. Manual navigation is added to create transitions
+//! between rows i.e. moving right at the end of the previous row navigates to the beginning of
+//! the next row. At the end of a page (the bottom right most button), moving right navigates to
+//! the first button on the next page.
+//!
 //! The `AutoDirectionalNavigation` component is used to add basic, intuitive navigation to UI
-//! elements within a page. Manual edges between rows and between pages are added to the 
+//! elements within a page. Manual edges between rows and between pages are added to the
 //! `DirectionalNavigationMap` to add special navigation rules. The `AutoDirectionalNavigator`
 //! system parameter navigates with the map and the components.
 
@@ -17,7 +17,6 @@ use core::time::Duration;
 
 use bevy::{
     camera::NormalizedRenderTarget,
-    color::palettes::css::*,
     input_focus::{
         directional_navigation::{
             AutoNavigationConfig, DirectionalNavigationMap, DirectionalNavigationPlugin,
@@ -58,10 +57,9 @@ fn main() {
         .init_resource::<ActionState>()
         // For automatic navigation, UI entities will have the component `AutoDirectionalNavigation`
         // and will be automatically connected by the navigation system.
-        // To override some automatically created navigation edges, manual edges are created
-        // in `setup_cascading_ui`. We will also add some new edges that the automatic navigation system
-        // does not create.
-        .add_systems(Startup, setup_cascading_ui)
+        // We will also add some new edges that the automatic navigation system
+        // cannot create by itself.
+        .add_systems(Startup, setup_paged_ui)
         // Input is generally handled during PreUpdate
         .add_systems(PreUpdate, (process_inputs, navigate).chain())
         .add_systems(
@@ -79,9 +77,33 @@ fn main() {
         .run();
 }
 
-const NORMAL_BUTTON: Srgba = bevy::color::palettes::tailwind::BLUE_400;
-const PRESSED_BUTTON: Srgba = bevy::color::palettes::tailwind::BLUE_500;
-const FOCUSED_BORDER: Srgba = bevy::color::palettes::tailwind::BLUE_50;
+const PAGE_1_NORMAL_BUTTON: Srgba = bevy::color::palettes::tailwind::BLUE_400;
+const PAGE_1_PRESSED_BUTTON: Srgba = bevy::color::palettes::tailwind::BLUE_500;
+const PAGE_1_FOCUSED_BORDER: Srgba = bevy::color::palettes::tailwind::BLUE_50;
+
+const PAGE_2_NORMAL_BUTTON: Srgba = bevy::color::palettes::tailwind::RED_400;
+const PAGE_2_PRESSED_BUTTON: Srgba = bevy::color::palettes::tailwind::RED_500;
+const PAGE_2_FOCUSED_BORDER: Srgba = bevy::color::palettes::tailwind::RED_50;
+
+const PAGE_3_NORMAL_BUTTON: Srgba = bevy::color::palettes::tailwind::GREEN_400;
+const PAGE_3_PRESSED_BUTTON: Srgba = bevy::color::palettes::tailwind::GREEN_500;
+const PAGE_3_FOCUSED_BORDER: Srgba = bevy::color::palettes::tailwind::GREEN_50;
+
+const NORMAL_BUTTON_COLORS: [Srgba; 3] = [
+    PAGE_1_NORMAL_BUTTON,
+    PAGE_2_NORMAL_BUTTON,
+    PAGE_3_NORMAL_BUTTON,
+];
+const PRESSED_BUTTON_COLORS: [Srgba; 3] = [
+    PAGE_1_PRESSED_BUTTON,
+    PAGE_2_PRESSED_BUTTON,
+    PAGE_3_PRESSED_BUTTON,
+];
+const FOCUSED_BORDER_COLORS: [Srgba; 3] = [
+    PAGE_1_FOCUSED_BORDER,
+    PAGE_2_FOCUSED_BORDER,
+    PAGE_3_FOCUSED_BORDER,
+];
 
 /// Marker component for the text that displays the currently focused button
 #[derive(Component)]
@@ -91,14 +113,18 @@ struct FocusDisplay;
 #[derive(Component)]
 struct KeyDisplay;
 
+/// Component that stores what page a button is on
+#[derive(Component)]
+struct Page(usize);
+
 // Observer for button clicks
 fn universal_button_click_behavior(
     mut click: On<Pointer<Click>>,
-    mut button_query: Query<(&mut BackgroundColor, &mut ResetTimer)>,
+    mut button_query: Query<(&mut BackgroundColor, &Page, &mut ResetTimer)>,
 ) {
     let button_entity = click.entity;
-    if let Ok((mut color, mut reset_timer)) = button_query.get_mut(button_entity) {
-        color.0 = PRESSED_BUTTON.into();
+    if let Ok((mut color, page, mut reset_timer)) = button_query.get_mut(button_entity) {
+        color.0 = PRESSED_BUTTON_COLORS[page.0].into();
         reset_timer.0 = Timer::from_seconds(0.3, TimerMode::Once);
         click.propagate(false);
     }
@@ -109,22 +135,24 @@ struct ResetTimer(Timer);
 
 fn reset_button_after_interaction(
     time: Res<Time>,
-    mut query: Query<(&mut ResetTimer, &mut BackgroundColor)>,
+    mut query: Query<(&mut ResetTimer, &mut BackgroundColor, &Page)>,
 ) {
-    for (mut reset_timer, mut color) in query.iter_mut() {
+    for (mut reset_timer, mut color, page) in query.iter_mut() {
         reset_timer.tick(time.delta());
         if reset_timer.just_finished() {
-            color.0 = NORMAL_BUTTON.into();
+            color.0 = NORMAL_BUTTON_COLORS[page.0].into();
         }
     }
 }
 
-/// Spawn a cascading layout of buttons to demonstrate automatic and manual navigation.
+/// Spawn pages of buttons to demonstrate automatic and manual navigation.
 ///
-/// This will create a grid of buttons, but each row cascades from the top left to the bottom right.
-/// Manual navigation will connect the end of one row with the beginning of the next row.
-/// Manual navigation will also make vertical navigation inverted (pressing down moves up)
-fn setup_cascading_ui(
+/// This will create three grid of buttons. Within rows and columns, automatic navigation
+/// that calculates the closest neighbor will be used. Between rows of the same page, manual
+/// navigation will connect the end of one row with the beginning of the next row. Between
+/// pages themselves, manual navigation will connect the button on the bottom right with
+/// the next page's button on the top top.
+fn setup_paged_ui(
     mut commands: Commands,
     mut manual_directional_nav_map: ResMut<DirectionalNavigationMap>,
     mut input_focus: ResMut<InputFocus>,
@@ -144,7 +172,7 @@ fn setup_cascading_ui(
     let instructions = commands
         .spawn((
             Text::new(
-                "Navigation Demo\n\n\
+                "Combined Navigation Demo\n\n\
                  Use arrow keys or D-pad to navigate.\n\
                  Press Enter or A button to interact.\n\n\
                  Horizontal navigation within rows is defined automatically.\n\
@@ -217,9 +245,18 @@ fn setup_cascading_ui(
         [(500.0, 485.0), (700.0, 485.0), (900.0, 485.0)],
     ];
 
-    let mut pages = [Vec::with_capacity(12), Vec::with_capacity(12), Vec::with_capacity(12)];
-    for (page_num, page_entities) in pages.iter_mut().enumerate() {
-        setup_buttons_for_page(&mut commands, page_num, page_entities, &button_positions);
+    let mut pages = [
+        Vec::with_capacity(12),
+        Vec::with_capacity(12),
+        Vec::with_capacity(12),
+    ];
+    for (page_num, page_button_entities) in pages.iter_mut().enumerate() {
+        setup_buttons_for_page(
+            &mut commands,
+            page_num,
+            page_button_entities,
+            &button_positions,
+        );
 
         // Only the first page is visible at setup.
         let visibility = if page_num == 0 {
@@ -227,13 +264,66 @@ fn setup_cascading_ui(
         } else {
             Visibility::Hidden
         };
-        let page = commands.spawn((Node {
-            width: percent(100),
-            height: percent(100),
-            ..default()
-        }, visibility))
-        .id();
-        commands.entity(page).add_children(&page_entities);
+        let page = commands
+            .spawn((
+                Node {
+                    width: percent(100),
+                    height: percent(100),
+                    ..default()
+                },
+                visibility,
+            ))
+            .id();
+
+        // Prompt to go to the previous page, placed left of the top-left button.
+        let previous_page = if page_num == 0 { 3 } else { page_num };
+        let previous_page_node = commands
+            .spawn((
+                Text::new(format!("Page {} << ", previous_page)),
+                KeyDisplay,
+                Node {
+                    position_type: PositionType::Absolute,
+                    left: px(360),
+                    top: px(120),
+                    width: px(140),
+                    padding: UiRect::all(px(12)),
+                    ..default()
+                },
+                TextLayout {
+                    justify: Justify::Right,
+                    ..default()
+                },
+                TextFont {
+                    font_size: 20.0,
+                    ..default()
+                },
+            ))
+            .id();
+
+        // Prompt to go to the next page, placed right of the bottom-right button.
+        let next_page_node = commands
+            .spawn((
+                Text::new(format!(">> Page {}", (page_num + 1) % 3 + 1)),
+                KeyDisplay,
+                Node {
+                    position_type: PositionType::Absolute,
+                    left: px(1050),
+                    top: px(525),
+                    width: px(140),
+                    padding: UiRect::all(px(12)),
+                    ..default()
+                },
+                TextFont {
+                    font_size: 20.0,
+                    ..default()
+                },
+            ))
+            .id();
+
+        commands
+            .entity(page)
+            .add_children(&page_button_entities)
+            .add_children(&[previous_page_node, next_page_node]);
     }
     let first_button = Some(pages[0][0]);
 
@@ -256,10 +346,10 @@ fn setup_cascading_ui(
         }
     }
 
-    // Add manual edges between pages
-    manual_directional_nav_map.add_symmetrical_edge(pages[0][11], pages[1][0], CompassOctant::East); 
-    manual_directional_nav_map.add_symmetrical_edge(pages[1][11], pages[2][0], CompassOctant::East); 
-    manual_directional_nav_map.add_symmetrical_edge(pages[2][11], pages[0][0], CompassOctant::East); 
+    // Add manual edges between pages.
+    manual_directional_nav_map.add_symmetrical_edge(pages[0][11], pages[1][0], CompassOctant::East);
+    manual_directional_nav_map.add_symmetrical_edge(pages[1][11], pages[2][0], CompassOctant::East);
+    manual_directional_nav_map.add_symmetrical_edge(pages[2][11], pages[0][0], CompassOctant::East);
 
     commands.entity(root_node).add_children(&[instructions]);
 
@@ -272,17 +362,11 @@ fn setup_cascading_ui(
 fn setup_buttons_for_page(
     commands: &mut Commands,
     page_num: usize,
-    page_entities: &mut Vec<Entity>, 
-    button_positions: &[[(f64, f64); 3]; 4]) {
+    page_entities: &mut Vec<Entity>,
+    button_positions: &[[(f64, f64); 3]; 4],
+) {
     for (i, row) in button_positions.iter().enumerate() {
         for (j, (x, y)) in row.iter().enumerate() {
-            let background_color = if page_num == 0 {
-                RED.into()
-            } else if page_num == 1 {
-                GREEN.into()
-            } else {
-                BLUE.into()
-            };
             let button_entity = commands
                 .spawn((
                     Button,
@@ -298,14 +382,25 @@ fn setup_buttons_for_page(
                         border_radius: BorderRadius::all(px(12)),
                         ..default()
                     },
-                    BackgroundColor(background_color),
+                    Page(page_num),
+                    BackgroundColor(NORMAL_BUTTON_COLORS[page_num].into()),
                     // This is the key: just add this component for automatic navigation!
                     AutoDirectionalNavigation::default(),
                     ResetTimer::default(),
-                    Name::new(format!("Page {},\nRow {},\nButton {}", page_num + 1, i + 1, j + 1)),
+                    Name::new(format!(
+                        "Page {},\nRow {},\nButton {}",
+                        page_num + 1,
+                        i + 1,
+                        j + 1
+                    )),
                 ))
                 .with_child((
-                    Text::new(format!("Page {},\nRow {},\nButton {}", page_num + 1, i + 1, j + 1)),
+                    Text::new(format!(
+                        "Page {},\nRow {},\nButton {}",
+                        page_num + 1,
+                        i + 1,
+                        j + 1
+                    )),
                     TextLayout {
                         justify: Justify::Center,
                         ..default()
@@ -411,21 +506,27 @@ fn navigate(
         .ok()
         .map(CompassOctant::from);
 
-    let previous_focus = auto_directional_navigator.manual_directional_navigation.focus.0;
+    let previous_focus = auto_directional_navigator
+        .manual_directional_navigation
+        .focus
+        .0;
     if let Some(direction) = maybe_direction {
         match auto_directional_navigator.navigate(direction) {
             Ok(new_focus) => {
                 // Successfully navigated
 
-                // If switching between pages, change visibilities of pages.
-                if let Ok(current_child_of) = parent_query.get(new_focus) && 
-                   let Ok(mut current_page_visibility) = visibility_query.get_mut(current_child_of.parent())  {
+                // If navigation switches between pages, change the visibilities of pages as necessary.
+                if let Ok(current_child_of) = parent_query.get(new_focus)
+                    && let Ok(mut current_page_visibility) =
+                        visibility_query.get_mut(current_child_of.parent())
+                {
                     *current_page_visibility = Visibility::Visible;
 
-                    if let Some(previous_focus_entity) = previous_focus &&
-                    let Ok(previous_child_of) = parent_query.get(previous_focus_entity) && 
-                    previous_child_of.parent() != current_child_of.parent() &&
-                    let Ok(mut previous_page_visibility) = visibility_query.get_mut(previous_child_of.parent()) 
+                    if let Some(previous_focus_entity) = previous_focus
+                        && let Ok(previous_child_of) = parent_query.get(previous_focus_entity)
+                        && previous_child_of.parent() != current_child_of.parent()
+                        && let Ok(mut previous_page_visibility) =
+                            visibility_query.get_mut(previous_child_of.parent())
                     {
                         *previous_page_visibility = Visibility::Hidden;
                     }
@@ -499,11 +600,11 @@ fn update_key_display(
 fn highlight_focused_element(
     input_focus: Res<InputFocus>,
     input_focus_visible: Res<InputFocusVisible>,
-    mut query: Query<(Entity, &mut BorderColor)>,
+    mut query: Query<(Entity, &mut BorderColor, &Page)>,
 ) {
-    for (entity, mut border_color) in query.iter_mut() {
+    for (entity, mut border_color, page) in query.iter_mut() {
         if input_focus.0 == Some(entity) && input_focus_visible.0 {
-            *border_color = BorderColor::all(FOCUSED_BORDER);
+            *border_color = BorderColor::all(FOCUSED_BORDER_COLORS[page.0]);
         } else {
             *border_color = BorderColor::DEFAULT;
         }

From 0d5c210f673037615cb1df4e3ad39ddf39047d6f Mon Sep 17 00:00:00 2001
From: Kevin Chen <chen.kevin.f@gmail.com>
Date: Sun, 11 Jan 2026 22:46:34 -0500
Subject: [PATCH 07/25] docs: updates comments

---
 examples/ui/navigation/combined_navigation.rs | 45 ++++++++++++-------
 1 file changed, 30 insertions(+), 15 deletions(-)

diff --git a/examples/ui/navigation/combined_navigation.rs b/examples/ui/navigation/combined_navigation.rs
index 51df65c875c6f..792a053802921 100644
--- a/examples/ui/navigation/combined_navigation.rs
+++ b/examples/ui/navigation/combined_navigation.rs
@@ -51,7 +51,7 @@ fn main() {
             min_alignment_factor: 0.1,
             // Don't connect nodes more than 500 pixels apart
             max_search_distance: Some(500.0),
-            // Do not prefer nodes that are well-aligned. In a cascading layout, nodes may not be well-aligned.
+            // Prefer nodes that are well-aligned
             prefer_aligned: false,
         })
         .init_resource::<ActionState>()
@@ -113,7 +113,7 @@ struct FocusDisplay;
 #[derive(Component)]
 struct KeyDisplay;
 
-/// Component that stores what page a button is on
+/// Component that stores which page a button is on
 #[derive(Component)]
 struct Page(usize);
 
@@ -147,11 +147,11 @@ fn reset_button_after_interaction(
 
 /// Spawn pages of buttons to demonstrate automatic and manual navigation.
 ///
-/// This will create three grid of buttons. Within rows and columns, automatic navigation
-/// that calculates the closest neighbor will be used. Between rows of the same page, manual
+/// This will create three pages of buttons. Within the rows and columns of a page,
+/// automatic navigation will be utilized. Between rows of the same page, manual
 /// navigation will connect the end of one row with the beginning of the next row. Between
 /// pages themselves, manual navigation will connect the button on the bottom right with
-/// the next page's button on the top top.
+/// the next page's button on the top left.
 fn setup_paged_ui(
     mut commands: Commands,
     mut manual_directional_nav_map: ResMut<DirectionalNavigationMap>,
@@ -245,12 +245,12 @@ fn setup_paged_ui(
         [(500.0, 485.0), (700.0, 485.0), (900.0, 485.0)],
     ];
 
-    let mut pages = [
+    let mut pages_entities = [
         Vec::with_capacity(12),
         Vec::with_capacity(12),
         Vec::with_capacity(12),
     ];
-    for (page_num, page_button_entities) in pages.iter_mut().enumerate() {
+    for (page_num, page_button_entities) in pages_entities.iter_mut().enumerate() {
         setup_buttons_for_page(
             &mut commands,
             page_num,
@@ -325,7 +325,7 @@ fn setup_paged_ui(
             .add_children(&page_button_entities)
             .add_children(&[previous_page_node, next_page_node]);
     }
-    let first_button = Some(pages[0][0]);
+    let first_button = Some(pages_entities[0][0]);
 
     // Add manual edges within each page for navigation between rows
     let entity_pairs = [
@@ -336,7 +336,7 @@ fn setup_paged_ui(
         // the end of the third row should connect to the beginning of the fourth
         ((2, 2), (3, 0)),
     ];
-    for page_entities in pages.iter() {
+    for page_entities in pages_entities.iter() {
         for ((entity_a_row, entity_a_col), (entity_b_row, entity_b_col)) in entity_pairs.iter() {
             manual_directional_nav_map.add_symmetrical_edge(
                 page_entities[entity_a_row * 3 + entity_a_col],
@@ -346,10 +346,23 @@ fn setup_paged_ui(
         }
     }
 
-    // Add manual edges between pages.
-    manual_directional_nav_map.add_symmetrical_edge(pages[0][11], pages[1][0], CompassOctant::East);
-    manual_directional_nav_map.add_symmetrical_edge(pages[1][11], pages[2][0], CompassOctant::East);
-    manual_directional_nav_map.add_symmetrical_edge(pages[2][11], pages[0][0], CompassOctant::East);
+    // Add manual edges between pages. When navigating right (east) from the last button of a page,
+    // go to the first button of the next page.
+    manual_directional_nav_map.add_symmetrical_edge(
+        pages_entities[0][11],
+        pages_entities[1][0],
+        CompassOctant::East,
+    );
+    manual_directional_nav_map.add_symmetrical_edge(
+        pages_entities[1][11],
+        pages_entities[2][0],
+        CompassOctant::East,
+    );
+    manual_directional_nav_map.add_symmetrical_edge(
+        pages_entities[2][11],
+        pages_entities[0][0],
+        CompassOctant::East,
+    );
 
     commands.entity(root_node).add_children(&[instructions]);
 
@@ -359,6 +372,7 @@ fn setup_paged_ui(
     }
 }
 
+/// Creates the button entities for a page_num and places the entities into page_entities.
 fn setup_buttons_for_page(
     commands: &mut Commands,
     page_num: usize,
@@ -506,6 +520,7 @@ fn navigate(
         .ok()
         .map(CompassOctant::from);
 
+    // Store the previous focus in case navigation switches pages.
     let previous_focus = auto_directional_navigator
         .manual_directional_navigation
         .focus
@@ -513,9 +528,9 @@ fn navigate(
     if let Some(direction) = maybe_direction {
         match auto_directional_navigator.navigate(direction) {
             Ok(new_focus) => {
-                // Successfully navigated
+                // Successfully navigated!
 
-                // If navigation switches between pages, change the visibilities of pages as necessary.
+                // If navigation switches between pages, change the visibilities of pages
                 if let Ok(current_child_of) = parent_query.get(new_focus)
                     && let Ok(mut current_page_visibility) =
                         visibility_query.get_mut(current_child_of.parent())

From c4f2d16938e028528df1f9981cff8af004facba0 Mon Sep 17 00:00:00 2001
From: Kevin Chen <chen.kevin.f@gmail.com>
Date: Sun, 11 Jan 2026 22:53:49 -0500
Subject: [PATCH 08/25] style: clippy and rename example

---
 Cargo.toml                                    | 2 +-
 examples/README.md                            | 2 +-
 examples/ui/navigation/combined_navigation.rs | 4 ++--
 3 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/Cargo.toml b/Cargo.toml
index b1ed944dbb1a0..fe1c146022ff2 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -5110,7 +5110,7 @@ path = "examples/ui/navigation/combined_navigation.rs"
 doc-scrape-examples = false
 
 [package.metadata.example.combined_navigation]
-name = "Combined (Automatic + Manual) Directional Navigation"
+name = "Combined (Automatic & Manual) Directional Navigation"
 description = "Demonstration of combining both automatic and manual directional navigation between UI elements"
 category = "UI (User Interface)"
 wasm = true
diff --git a/examples/README.md b/examples/README.md
index da8971267a5f5..003bc06330e45 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -572,7 +572,7 @@ Example | Description
 [Box Shadow](../examples/ui/box_shadow.rs) | Demonstrates how to create a node with a shadow
 [Button](../examples/ui/button.rs) | Illustrates creating and updating a button
 [CSS Grid](../examples/ui/grid.rs) | An example for CSS Grid layout
-[Combined (Automatic + Manual) Directional Navigation](../examples/ui/navigation/combined_navigation.rs) | Demonstration of combining both automatic and manual directional navigation between UI elements
+[Combined (Automatic & Manual) Directional Navigation](../examples/ui/navigation/combined_navigation.rs) | Demonstration of combining both automatic and manual directional navigation between UI elements
 [Display and Visibility](../examples/ui/display_and_visibility.rs) | Demonstrates how Display and Visibility work in the UI.
 [Drag to Scroll](../examples/ui/drag_to_scroll.rs) | This example tests scale factor, dragging and scrolling
 [Feathers Widgets](../examples/ui/feathers.rs) | Gallery of Feathers Widgets
diff --git a/examples/ui/navigation/combined_navigation.rs b/examples/ui/navigation/combined_navigation.rs
index 792a053802921..6b3bb2a912427 100644
--- a/examples/ui/navigation/combined_navigation.rs
+++ b/examples/ui/navigation/combined_navigation.rs
@@ -322,7 +322,7 @@ fn setup_paged_ui(
 
         commands
             .entity(page)
-            .add_children(&page_button_entities)
+            .add_children(page_button_entities)
             .add_children(&[previous_page_node, next_page_node]);
     }
     let first_button = Some(pages_entities[0][0]);
@@ -372,7 +372,7 @@ fn setup_paged_ui(
     }
 }
 
-/// Creates the button entities for a page_num and places the entities into page_entities.
+/// Creates the button entities for a page and places the entities into `page_entities`.
 fn setup_buttons_for_page(
     commands: &mut Commands,
     page_num: usize,

From 425a63b03d8556f92a508eba5367e54649c6cc30 Mon Sep 17 00:00:00 2001
From: Kevin Chen <chen.kevin.f@gmail.com>
Date: Sun, 11 Jan 2026 23:03:54 -0500
Subject: [PATCH 09/25] nit: use input_focus method

---
 examples/ui/navigation/combined_navigation.rs | 5 +----
 1 file changed, 1 insertion(+), 4 deletions(-)

diff --git a/examples/ui/navigation/combined_navigation.rs b/examples/ui/navigation/combined_navigation.rs
index 6b3bb2a912427..00c3a9cb29414 100644
--- a/examples/ui/navigation/combined_navigation.rs
+++ b/examples/ui/navigation/combined_navigation.rs
@@ -521,10 +521,7 @@ fn navigate(
         .map(CompassOctant::from);
 
     // Store the previous focus in case navigation switches pages.
-    let previous_focus = auto_directional_navigator
-        .manual_directional_navigation
-        .focus
-        .0;
+    let previous_focus = auto_directional_navigator.input_focus();
     if let Some(direction) = maybe_direction {
         match auto_directional_navigator.navigate(direction) {
             Ok(new_focus) => {

From b418a3bd70173b2e32716d038d2af32f00f66f88 Mon Sep 17 00:00:00 2001
From: Kevin Chen <chen.kevin.f@gmail.com>
Date: Sun, 11 Jan 2026 23:09:21 -0500
Subject: [PATCH 10/25] docs: remove KeyDisplay component from next/prev page

---
 examples/ui/navigation/combined_navigation.rs | 2 --
 1 file changed, 2 deletions(-)

diff --git a/examples/ui/navigation/combined_navigation.rs b/examples/ui/navigation/combined_navigation.rs
index 00c3a9cb29414..477e4fd21643e 100644
--- a/examples/ui/navigation/combined_navigation.rs
+++ b/examples/ui/navigation/combined_navigation.rs
@@ -280,7 +280,6 @@ fn setup_paged_ui(
         let previous_page_node = commands
             .spawn((
                 Text::new(format!("Page {} << ", previous_page)),
-                KeyDisplay,
                 Node {
                     position_type: PositionType::Absolute,
                     left: px(360),
@@ -304,7 +303,6 @@ fn setup_paged_ui(
         let next_page_node = commands
             .spawn((
                 Text::new(format!(">> Page {}", (page_num + 1) % 3 + 1)),
-                KeyDisplay,
                 Node {
                     position_type: PositionType::Absolute,
                     left: px(1050),

From 26fde3ed96b5e3d0707e56ddb2858689def07095 Mon Sep 17 00:00:00 2001
From: Kevin Chen <chen.kevin.f@gmail.com>
Date: Sun, 11 Jan 2026 23:13:01 -0500
Subject: [PATCH 11/25] docs: nit rewording

---
 examples/ui/navigation/combined_navigation.rs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/examples/ui/navigation/combined_navigation.rs b/examples/ui/navigation/combined_navigation.rs
index 477e4fd21643e..75816234680c3 100644
--- a/examples/ui/navigation/combined_navigation.rs
+++ b/examples/ui/navigation/combined_navigation.rs
@@ -175,7 +175,7 @@ fn setup_paged_ui(
                 "Combined Navigation Demo\n\n\
                  Use arrow keys or D-pad to navigate.\n\
                  Press Enter or A button to interact.\n\n\
-                 Horizontal navigation within rows is defined automatically.\n\
+                 Horizontal navigation within rows is configured automatically.\n\
                  Horizontal navigation between rows is defined manually.\n\
                  Navigation between pages is defined manually.",
             ),

From b25d7d6c2df8f6e417aa50103a45c13fe011ce5a Mon Sep 17 00:00:00 2001
From: Kevin Chen <chen.kevin.f@gmail.com>
Date: Sun, 11 Jan 2026 23:23:59 -0500
Subject: [PATCH 12/25] docs: refine the comments more

---
 examples/ui/navigation/combined_navigation.rs | 17 ++++++++++-------
 1 file changed, 10 insertions(+), 7 deletions(-)

diff --git a/examples/ui/navigation/combined_navigation.rs b/examples/ui/navigation/combined_navigation.rs
index 75816234680c3..02c693acc209f 100644
--- a/examples/ui/navigation/combined_navigation.rs
+++ b/examples/ui/navigation/combined_navigation.rs
@@ -3,15 +3,18 @@
 //! This example shows how to leverage both automatic navigation and manual navigation to create
 //! a desired user navigation experience without much boilerplate code. In this example, there are
 //! multiple pages of UI Buttons. When navigating within the button grid on a page (up, down, left
-//! and right), automatic navigation is used. Manual navigation is added to create transitions
-//! between rows i.e. moving right at the end of the previous row navigates to the beginning of
-//! the next row. At the end of a page (the bottom right most button), moving right navigates to
-//! the first button on the next page.
+//! and right), automatic navigation is used. However, to add more bespoke navigation that cannot
+//! be automatically detected by screen position proximity alone, manual navigation must be used.
+//! 
+//! Manual navigation is needed to create transitions between rows and between pages.
+//! These transitions are not created by the automatic navigation system. Moving right at the
+//! end of the previous row navigates to the beginning of the next row. At the end of a page
+//! (the bottom right most button), moving right navigates to the first button on the next page.
 //!
 //! The `AutoDirectionalNavigation` component is used to add basic, intuitive navigation to UI
 //! elements within a page. Manual edges between rows and between pages are added to the
-//! `DirectionalNavigationMap` to add special navigation rules. The `AutoDirectionalNavigator`
-//! system parameter navigates with the map and the components.
+//! `DirectionalNavigationMap` to allow special navigation rules. The `AutoDirectionalNavigator`
+//! system parameter navigates using manual navigation first and automatic navigation second.
 
 use core::time::Duration;
 
@@ -58,7 +61,7 @@ fn main() {
         // For automatic navigation, UI entities will have the component `AutoDirectionalNavigation`
         // and will be automatically connected by the navigation system.
         // We will also add some new edges that the automatic navigation system
-        // cannot create by itself.
+        // cannot create by itself by inserting them into `DirectionalNavigationMap`
         .add_systems(Startup, setup_paged_ui)
         // Input is generally handled during PreUpdate
         .add_systems(PreUpdate, (process_inputs, navigate).chain())

From 41f9ac6ed743906a697d66bb61d8b6f79272f75c Mon Sep 17 00:00:00 2001
From: Kevin Chen <chen.kevin.f@gmail.com>
Date: Sun, 11 Jan 2026 23:26:01 -0500
Subject: [PATCH 13/25] style: fmt

---
 examples/ui/navigation/combined_navigation.rs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/examples/ui/navigation/combined_navigation.rs b/examples/ui/navigation/combined_navigation.rs
index 02c693acc209f..0154bcb5d7fa9 100644
--- a/examples/ui/navigation/combined_navigation.rs
+++ b/examples/ui/navigation/combined_navigation.rs
@@ -5,7 +5,7 @@
 //! multiple pages of UI Buttons. When navigating within the button grid on a page (up, down, left
 //! and right), automatic navigation is used. However, to add more bespoke navigation that cannot
 //! be automatically detected by screen position proximity alone, manual navigation must be used.
-//! 
+//!
 //! Manual navigation is needed to create transitions between rows and between pages.
 //! These transitions are not created by the automatic navigation system. Moving right at the
 //! end of the previous row navigates to the beginning of the next row. At the end of a page

From 1c9946fb7294ac2aa9675b0b3f8431c71d786169 Mon Sep 17 00:00:00 2001
From: Kevin Chen <chen.kevin.f@gmail.com>
Date: Tue, 13 Jan 2026 01:29:46 -0500
Subject: [PATCH 14/25] docs: each page shows a diff technique for manual
 overrides

---
 examples/ui/navigation/combined_navigation.rs | 462 +++++++++++++-----
 1 file changed, 329 insertions(+), 133 deletions(-)

diff --git a/examples/ui/navigation/combined_navigation.rs b/examples/ui/navigation/combined_navigation.rs
index 0154bcb5d7fa9..810ed98382400 100644
--- a/examples/ui/navigation/combined_navigation.rs
+++ b/examples/ui/navigation/combined_navigation.rs
@@ -2,19 +2,20 @@
 //!
 //! This example shows how to leverage both automatic navigation and manual navigation to create
 //! a desired user navigation experience without much boilerplate code. In this example, there are
-//! multiple pages of UI Buttons. When navigating within the button grid on a page (up, down, left
-//! and right), automatic navigation is used. However, to add more bespoke navigation that cannot
-//! be automatically detected by screen position proximity alone, manual navigation must be used.
+//! multiple pages of UI Buttons that depict different scenarios in which both automatic and manual
+//! navigation are leveraged to produce a desired navigation experience.
 //!
-//! Manual navigation is needed to create transitions between rows and between pages.
-//! These transitions are not created by the automatic navigation system. Moving right at the
-//! end of the previous row navigates to the beginning of the next row. At the end of a page
-//! (the bottom right most button), moving right navigates to the first button on the next page.
+//! Manual navigation can also be used to define navigation in any situation where automatic
+//! navigation fails to create an edge due to lack of proximity. For example, when creating
+//! navigation that loops around to an opposite side, manual navigation should be used to define
+//! this behavior. If one input is too far away from the others and `AutoNavigationConfig`
+//! cannot be tweaked, manual navigation can connect that input to the others. Manual navigation
+//! can also be used to override any undesired navigation.
 //!
-//! The `AutoDirectionalNavigation` component is used to add basic, intuitive navigation to UI
-//! elements within a page. Manual edges between rows and between pages are added to the
-//! `DirectionalNavigationMap` to allow special navigation rules. The `AutoDirectionalNavigator`
-//! system parameter navigates using manual navigation first and automatic navigation second.
+//! The `AutoDirectionalNavigation` component is used to create basic, intuitive navigation to UI
+//! elements within a page. Manual navigation edges are added to the `DirectionalNavigationMap`
+//! to create special navigation rules. The `AutoDirectionalNavigator` system parameter navigates
+//! using manual navigation rules first and automatic navigation second.
 
 use core::time::Duration;
 
@@ -52,10 +53,10 @@ fn main() {
         .insert_resource(AutoNavigationConfig {
             // Require at least 10% overlap in perpendicular axis for cardinal directions
             min_alignment_factor: 0.1,
-            // Don't connect nodes more than 500 pixels apart
-            max_search_distance: Some(500.0),
+            // Don't connect nodes more than 200 pixels apart
+            max_search_distance: Some(200.0),
             // Prefer nodes that are well-aligned
-            prefer_aligned: false,
+            prefer_aligned: true,
         })
         .init_resource::<ActionState>()
         // For automatic navigation, UI entities will have the component `AutoDirectionalNavigation`
@@ -178,9 +179,8 @@ fn setup_paged_ui(
                 "Combined Navigation Demo\n\n\
                  Use arrow keys or D-pad to navigate.\n\
                  Press Enter or A button to interact.\n\n\
-                 Horizontal navigation within rows is configured automatically.\n\
-                 Horizontal navigation between rows is defined manually.\n\
-                 Navigation between pages is defined manually.",
+                 Navigation on each page is a combination of \
+                 both automatic and manual navigation.",
             ),
             Node {
                 position_type: PositionType::Absolute,
@@ -235,31 +235,28 @@ fn setup_paged_ui(
         },
     ));
 
-    // Spawn buttons in cascading rows
-    // Auto-navigation will configure navigation within rows.
-    let button_positions = [
-        // Row 0
-        [(500.0, 80.0), (700.0, 80.0), (900.0, 80.0)],
-        // Row 1
-        [(500.0, 215.0), (700.0, 215.0), (900.0, 215.0)],
-        // Row 2
-        [(500.0, 350.0), (700.0, 350.0), (900.0, 350.0)],
-        // Row 3
-        [(500.0, 485.0), (700.0, 485.0), (900.0, 485.0)],
-    ];
-
     let mut pages_entities = [
         Vec::with_capacity(12),
         Vec::with_capacity(12),
         Vec::with_capacity(12),
     ];
+    let mut text_entities = Vec::with_capacity(6);
     for (page_num, page_button_entities) in pages_entities.iter_mut().enumerate() {
-        setup_buttons_for_page(
-            &mut commands,
-            page_num,
-            page_button_entities,
-            &button_positions,
-        );
+        if page_num == 1 {
+            // the second page
+            setup_buttons_for_triangle_page(
+                &mut commands,
+                page_num,
+                (page_button_entities, &mut text_entities),
+            )
+        } else {
+            // the first and third pages are regular grids
+            setup_buttons_for_grid_page(
+                &mut commands,
+                page_num,
+                (page_button_entities, &mut text_entities),
+            );
+        }
 
         // Only the first page is visible at setup.
         let visibility = if page_num == 0 {
@@ -278,57 +275,16 @@ fn setup_paged_ui(
             ))
             .id();
 
-        // Prompt to go to the previous page, placed left of the top-left button.
-        let previous_page = if page_num == 0 { 3 } else { page_num };
-        let previous_page_node = commands
-            .spawn((
-                Text::new(format!("Page {} << ", previous_page)),
-                Node {
-                    position_type: PositionType::Absolute,
-                    left: px(360),
-                    top: px(120),
-                    width: px(140),
-                    padding: UiRect::all(px(12)),
-                    ..default()
-                },
-                TextLayout {
-                    justify: Justify::Right,
-                    ..default()
-                },
-                TextFont {
-                    font_size: 20.0,
-                    ..default()
-                },
-            ))
-            .id();
-
-        // Prompt to go to the next page, placed right of the bottom-right button.
-        let next_page_node = commands
-            .spawn((
-                Text::new(format!(">> Page {}", (page_num + 1) % 3 + 1)),
-                Node {
-                    position_type: PositionType::Absolute,
-                    left: px(1050),
-                    top: px(525),
-                    width: px(140),
-                    padding: UiRect::all(px(12)),
-                    ..default()
-                },
-                TextFont {
-                    font_size: 20.0,
-                    ..default()
-                },
-            ))
-            .id();
-
         commands
             .entity(page)
             .add_children(page_button_entities)
-            .add_children(&[previous_page_node, next_page_node]);
+            .add_children(&text_entities);
+
+        text_entities.clear();
     }
     let first_button = Some(pages_entities[0][0]);
 
-    // Add manual edges within each page for navigation between rows
+    // For Pages 1 and 3, add manual edges within the grid page for navigation between rows.
     let entity_pairs = [
         // the end of the first row should connect to the beginning of the second
         ((0, 2), (1, 0)),
@@ -337,7 +293,11 @@ fn setup_paged_ui(
         // the end of the third row should connect to the beginning of the fourth
         ((2, 2), (3, 0)),
     ];
-    for page_entities in pages_entities.iter() {
+    for (page_num, page_entities) in pages_entities.iter().enumerate() {
+        // Skip Page 2; we are only adding these manual edges for the grid pages.
+        if page_num == 1 {
+            continue;
+        }
         for ((entity_a_row, entity_a_col), (entity_b_row, entity_b_col)) in entity_pairs.iter() {
             manual_directional_nav_map.add_symmetrical_edge(
                 page_entities[entity_a_row * 3 + entity_a_col],
@@ -347,18 +307,62 @@ fn setup_paged_ui(
         }
     }
 
-    // Add manual edges between pages. When navigating right (east) from the last button of a page,
-    // go to the first button of the next page.
+    // Add manual edges within the triangle page (Page 2) between buttons 3 and 4.
+    // The `AutoNavigationConfig` is set to our desired values, but automatic
+    // navigation does not connect Button 3 to Button 4, so we have to add
+    // this navigation manually.
+    manual_directional_nav_map.add_symmetrical_edge(
+        pages_entities[1][2],
+        pages_entities[1][3],
+        CompassOctant::East,
+    );
+    manual_directional_nav_map.add_symmetrical_edge(
+        pages_entities[1][2],
+        pages_entities[1][3],
+        CompassOctant::South,
+    );
+    manual_directional_nav_map.add_symmetrical_edge(
+        pages_entities[1][2],
+        pages_entities[1][3],
+        CompassOctant::SouthEast,
+    );
+
+    // For Page 3, we override the navigation North and South to be inverted.
+    let mut col_entities = Vec::with_capacity(4);
+    for col in 0..=2 {
+        for row in 0..=3 {
+            col_entities.push(pages_entities[2][row * 3 + col])
+        }
+        manual_directional_nav_map.add_looping_edges(&col_entities, CompassOctant::North);
+        col_entities.clear();
+    }
+
+    // Add manual edges between pages.
+    // When navigating east (right) from the last button of page 1,
+    // go to the first button of page 2. This edge is symmetrical.
     manual_directional_nav_map.add_symmetrical_edge(
         pages_entities[0][11],
         pages_entities[1][0],
         CompassOctant::East,
     );
-    manual_directional_nav_map.add_symmetrical_edge(
-        pages_entities[1][11],
+    // When navigating south (down) from the last button of page 2,
+    // go to the first button of page 3. This edge is NOT symmetrical.
+    // This means going north (up) from the first button of page 3 does
+    // NOT go to the last button of page 2.
+    manual_directional_nav_map.add_edge(
+        pages_entities[1][3],
         pages_entities[2][0],
-        CompassOctant::East,
+        CompassOctant::South,
     );
+    // When navigating west (left) from the first button of page 3,
+    // go back to the last button of page 2. This edge is NOT symmetrical.
+    manual_directional_nav_map.add_edge(
+        pages_entities[2][0],
+        pages_entities[1][3],
+        CompassOctant::West,
+    );
+    // When navigating east (right) from the last button of page 1,
+    // go to the first button of page 2. This edge is symmetrical.
     manual_directional_nav_map.add_symmetrical_edge(
         pages_entities[2][11],
         pages_entities[0][0],
@@ -373,58 +377,250 @@ fn setup_paged_ui(
     }
 }
 
-/// Creates the button entities for a page and places the entities into `page_entities`.
-fn setup_buttons_for_page(
+/// Creates the buttons and text for a grid page and places the ids into their
+/// respective Vecs in `entities`.
+fn setup_buttons_for_grid_page(
     commands: &mut Commands,
     page_num: usize,
-    page_entities: &mut Vec<Entity>,
-    button_positions: &[[(f64, f64); 3]; 4],
+    entities: (&mut Vec<Entity>, &mut Vec<Entity>),
 ) {
+    let (page_button_entities, text_entities) = entities;
+
+    // Spawn buttons in a grid
+    // Auto-navigation will automatically configure navigation within rows.
+    let button_positions = [
+        // Row 0
+        [(450.0, 80.0), (650.0, 80.0), (850.0, 80.0)],
+        // Row 1
+        [(450.0, 215.0), (650.0, 215.0), (850.0, 215.0)],
+        // Row 2
+        [(450.0, 350.0), (650.0, 350.0), (850.0, 350.0)],
+        // Row 3
+        [(450.0, 485.0), (650.0, 485.0), (850.0, 485.0)],
+    ];
     for (i, row) in button_positions.iter().enumerate() {
-        for (j, (x, y)) in row.iter().enumerate() {
-            let button_entity = commands
-                .spawn((
-                    Button,
-                    Node {
-                        position_type: PositionType::Absolute,
-                        left: px(*x),
-                        top: px(*y),
-                        width: px(140),
-                        height: px(100),
-                        border: UiRect::all(px(4)),
-                        justify_content: JustifyContent::Center,
-                        align_items: AlignItems::Center,
-                        border_radius: BorderRadius::all(px(12)),
-                        ..default()
-                    },
-                    Page(page_num),
-                    BackgroundColor(NORMAL_BUTTON_COLORS[page_num].into()),
-                    // This is the key: just add this component for automatic navigation!
-                    AutoDirectionalNavigation::default(),
-                    ResetTimer::default(),
-                    Name::new(format!(
-                        "Page {},\nRow {},\nButton {}",
-                        page_num + 1,
-                        i + 1,
-                        j + 1
-                    )),
-                ))
-                .with_child((
-                    Text::new(format!(
-                        "Page {},\nRow {},\nButton {}",
-                        page_num + 1,
-                        i + 1,
-                        j + 1
-                    )),
-                    TextLayout {
-                        justify: Justify::Center,
-                        ..default()
-                    },
-                ))
-                .id();
-            page_entities.push(button_entity);
+        for (j, (left, top)) in row.iter().enumerate() {
+            let button_entity = spawn_auto_nav_button(
+                commands,
+                format!("Btn {}-{}", i + 1, j + 1),
+                left,
+                top,
+                page_num,
+            );
+            page_button_entities.push(button_entity);
         }
     }
+
+    // Text describing current page
+    let current_page_entity = spawn_small_text_node(
+        commands,
+        format!("Currently on Page {}", page_num + 1),
+        650,
+        20,
+        Justify::Center,
+    );
+    text_entities.push(current_page_entity);
+
+    // Text describing direction to go to the previous page, placed left of the top-left button.
+    let previous_page = if page_num == 0 { 3 } else { page_num };
+    let previous_page_entity = spawn_small_text_node(
+        commands,
+        format!("Page {} << ", previous_page),
+        310,
+        120,
+        Justify::Right,
+    );
+    text_entities.push(previous_page_entity);
+
+    // Text describing direction to go to the next page, placed right of the bottom-right button.
+    let next_page_entity = spawn_small_text_node(
+        commands,
+        format!(">> Page {}", (page_num + 1) % 3 + 1),
+        1000,
+        525,
+        Justify::Left,
+    );
+    text_entities.push(next_page_entity);
+
+    // Texts describing that moving right wraps to the next row.
+    let right_1 = spawn_small_text_node(commands, "> Btn 2-1".into(), 1000, 120, Justify::Left);
+    let right_2 = spawn_small_text_node(commands, "> Btn 3-1".into(), 1000, 255, Justify::Left);
+    let right_3 = spawn_small_text_node(commands, "> Btn 4-1".into(), 1000, 390, Justify::Left);
+    let left_1 = spawn_small_text_node(commands, "Btn 1-3 < ".into(), 310, 255, Justify::Right);
+    let left_2 = spawn_small_text_node(commands, "Btn 2-3 < ".into(), 310, 390, Justify::Right);
+    let left_3 = spawn_small_text_node(commands, "Btn 3-3 < ".into(), 310, 525, Justify::Right);
+    text_entities.push(right_1);
+    text_entities.push(right_2);
+    text_entities.push(right_3);
+    text_entities.push(left_1);
+    text_entities.push(left_2);
+    text_entities.push(left_3);
+
+    // For the third page, add a notice about vertical navigation being inverted in the grid.
+    if page_num == 2 {
+        let footer_info = commands
+            .spawn((
+                Text::new(
+                    "Vertical Navigation has been manually overridden to be inverted! \
+                ^ moves down, and v (down) moves up.",
+                ),
+                Node {
+                    position_type: PositionType::Absolute,
+                    left: px(450),
+                    top: px(600),
+                    width: px(540),
+                    padding: UiRect::all(px(12)),
+                    ..default()
+                },
+                TextFont {
+                    font_size: 20.0,
+                    ..default()
+                },
+            ))
+            .id();
+        text_entities.push(footer_info);
+    }
+}
+
+/// Creates the buttons and text for a the "triangle" page and places the ids into their
+/// respective Vecs in `entities`.
+fn setup_buttons_for_triangle_page(
+    commands: &mut Commands,
+    page_num: usize,
+    entities: (&mut Vec<Entity>, &mut Vec<Entity>),
+) {
+    let button_positions = [
+        (450.0, 80.0),   // top left
+        (700.0, 80.0),   // top right
+        (575.0, 215.0),  // middle
+        (1050.0, 350.0), // bottom right
+    ];
+    let (page_button_entities, text_entities) = entities;
+    for (i, (left, top)) in button_positions.iter().enumerate() {
+        let button_entity =
+            spawn_auto_nav_button(commands, format!("Btn {}", i + 1), left, top, page_num);
+        page_button_entities.push(button_entity);
+    }
+
+    // Text describing current page
+    let current_page_entity = spawn_small_text_node(
+        commands,
+        format!("Page {}", page_num + 1),
+        650,
+        20,
+        Justify::Center,
+    );
+    text_entities.push(current_page_entity);
+
+    // Text describing direction to go to the previous page, placed left of the top-left button.
+    let previous_page = if page_num == 0 { 3 } else { page_num };
+    let previous_page_entity = spawn_small_text_node(
+        commands,
+        format!("Page {} << ", previous_page),
+        310,
+        120,
+        Justify::Right,
+    );
+    text_entities.push(previous_page_entity);
+
+    // Direction to navigate from button 3 to button 4, placed below center button
+    let below_button_three_entity =
+        spawn_small_text_node(commands, "v\nButton 4".into(), 575, 325, Justify::Center);
+    text_entities.push(below_button_three_entity);
+
+    // Direction to navigate from button 3 to button 4, placed right of center button
+    let right_of_button_three_entity =
+        spawn_small_text_node(commands, "> Button 4".into(), 735, 255, Justify::Left);
+    text_entities.push(right_of_button_three_entity);
+
+    // Direction to navigate from button 4 to button 3, placed above bottom right button
+    let below_button_three_entity =
+        spawn_small_text_node(commands, "Button 3\n^".into(), 1050, 300, Justify::Center);
+    text_entities.push(below_button_three_entity);
+
+    // Direction to navigate from button 4 to button 3, placed left of bottom right button
+    let right_of_button_three_entity =
+        spawn_small_text_node(commands, "Button 3 < ".into(), 910, 390, Justify::Right);
+    text_entities.push(right_of_button_three_entity);
+
+    // Direction to go to the next page, placed bottom of the bottom-right button.
+    let next_page_entity = spawn_small_text_node(
+        commands,
+        format!("V\nV\nPage {}", (page_num + 1) % 3 + 1),
+        1050,
+        460,
+        Justify::Center,
+    );
+    text_entities.push(next_page_entity);
+}
+
+fn spawn_auto_nav_button(
+    commands: &mut Commands,
+    text: String,
+    left: &f64,
+    top: &f64,
+    page_num: usize,
+) -> Entity {
+    commands
+        .spawn((
+            Button,
+            Node {
+                position_type: PositionType::Absolute,
+                left: px(*left),
+                top: px(*top),
+                width: px(140),
+                height: px(100),
+                border: UiRect::all(px(4)),
+                justify_content: JustifyContent::Center,
+                align_items: AlignItems::Center,
+                border_radius: BorderRadius::all(px(12)),
+                ..default()
+            },
+            Page(page_num),
+            BackgroundColor(NORMAL_BUTTON_COLORS[page_num].into()),
+            // This is the key: just add this component for automatic navigation!
+            AutoDirectionalNavigation::default(),
+            ResetTimer::default(),
+            Name::new(text.clone()),
+        ))
+        .with_child((
+            Text::new(text),
+            TextLayout {
+                justify: Justify::Center,
+                ..default()
+            },
+        ))
+        .id()
+}
+
+fn spawn_small_text_node(
+    commands: &mut Commands,
+    text: String,
+    left: i32,
+    top: i32,
+    justify: Justify,
+) -> Entity {
+    commands
+        .spawn((
+            Text::new(text),
+            Node {
+                position_type: PositionType::Absolute,
+                left: px(left),
+                top: px(top),
+                width: px(140),
+                padding: UiRect::all(px(12)),
+                ..default()
+            },
+            TextFont {
+                font_size: 20.0,
+                ..default()
+            },
+            TextLayout {
+                justify,
+                ..default()
+            },
+        ))
+        .id()
 }
 
 // Action state and input handling (same as the manual navigation example)

From 24b8cad42885744a680a879bc04abfcb02099ad3 Mon Sep 17 00:00:00 2001
From: Kevin Chen <chen.kevin.f@gmail.com>
Date: Tue, 13 Jan 2026 01:33:29 -0500
Subject: [PATCH 15/25] docs: update comment for setup fn

---
 examples/ui/navigation/combined_navigation.rs | 14 +++++++++-----
 1 file changed, 9 insertions(+), 5 deletions(-)

diff --git a/examples/ui/navigation/combined_navigation.rs b/examples/ui/navigation/combined_navigation.rs
index 810ed98382400..3875c6bf663bf 100644
--- a/examples/ui/navigation/combined_navigation.rs
+++ b/examples/ui/navigation/combined_navigation.rs
@@ -151,11 +151,15 @@ fn reset_button_after_interaction(
 
 /// Spawn pages of buttons to demonstrate automatic and manual navigation.
 ///
-/// This will create three pages of buttons. Within the rows and columns of a page,
-/// automatic navigation will be utilized. Between rows of the same page, manual
-/// navigation will connect the end of one row with the beginning of the next row. Between
-/// pages themselves, manual navigation will connect the button on the bottom right with
-/// the next page's button on the top left.
+/// This function creates three pages of buttons. All buttons have automatic navigation.
+/// Manual navigation is specified with the DirectionalNavigationMap.
+/// Page 1 has a simple grid of buttons where transitions between rows is defined using
+/// the DirectionalNavigationMap.
+/// Page 2 has a cluster of buttons to the top left and a lonely button on the bottom right.
+/// Navigation between the cluster and the lonely button is defined using the
+/// DirectionalNavigationMap.
+/// Page 3 has the same simple grid of buttons as page 1, but automatic navigation has been
+/// overridden in the vertical direction with the DirectionalNavigationMap.
 fn setup_paged_ui(
     mut commands: Commands,
     mut manual_directional_nav_map: ResMut<DirectionalNavigationMap>,

From bd41c182a3fe1431c541e8472bacff6bf3d42d34 Mon Sep 17 00:00:00 2001
From: Kevin Chen <chen.kevin.f@gmail.com>
Date: Tue, 13 Jan 2026 01:39:43 -0500
Subject: [PATCH 16/25] docs: adds backticks where needed

---
 examples/ui/navigation/combined_navigation.rs | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/examples/ui/navigation/combined_navigation.rs b/examples/ui/navigation/combined_navigation.rs
index 3875c6bf663bf..89dd955a3232b 100644
--- a/examples/ui/navigation/combined_navigation.rs
+++ b/examples/ui/navigation/combined_navigation.rs
@@ -152,14 +152,14 @@ fn reset_button_after_interaction(
 /// Spawn pages of buttons to demonstrate automatic and manual navigation.
 ///
 /// This function creates three pages of buttons. All buttons have automatic navigation.
-/// Manual navigation is specified with the DirectionalNavigationMap.
+/// Manual navigation is specified with the `DirectionalNavigationMap`.
 /// Page 1 has a simple grid of buttons where transitions between rows is defined using
-/// the DirectionalNavigationMap.
+/// the `DirectionalNavigationMap`.
 /// Page 2 has a cluster of buttons to the top left and a lonely button on the bottom right.
 /// Navigation between the cluster and the lonely button is defined using the
-/// DirectionalNavigationMap.
+/// `DirectionalNavigationMap`.
 /// Page 3 has the same simple grid of buttons as page 1, but automatic navigation has been
-/// overridden in the vertical direction with the DirectionalNavigationMap.
+/// overridden in the vertical direction with the `DirectionalNavigationMap`.
 fn setup_paged_ui(
     mut commands: Commands,
     mut manual_directional_nav_map: ResMut<DirectionalNavigationMap>,
@@ -486,7 +486,7 @@ fn setup_buttons_for_grid_page(
     }
 }
 
-/// Creates the buttons and text for a the "triangle" page and places the ids into their
+/// Creates the buttons and text for the triangle page (page 2) and places the ids into their
 /// respective Vecs in `entities`.
 fn setup_buttons_for_triangle_page(
     commands: &mut Commands,
@@ -582,7 +582,7 @@ fn spawn_auto_nav_button(
             },
             Page(page_num),
             BackgroundColor(NORMAL_BUTTON_COLORS[page_num].into()),
-            // This is the key: just add this component for automatic navigation!
+            // Just add this component for automatic navigation
             AutoDirectionalNavigation::default(),
             ResetTimer::default(),
             Name::new(text.clone()),

From 5c5ddd16eeb05e939c6870456d8cf3283d2da48f Mon Sep 17 00:00:00 2001
From: Kevin Chen <chen.kevin.f@gmail.com>
Date: Tue, 13 Jan 2026 01:41:49 -0500
Subject: [PATCH 17/25] docs: button -> btn

---
 examples/ui/navigation/combined_navigation.rs | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/examples/ui/navigation/combined_navigation.rs b/examples/ui/navigation/combined_navigation.rs
index 89dd955a3232b..0f42e080f516e 100644
--- a/examples/ui/navigation/combined_navigation.rs
+++ b/examples/ui/navigation/combined_navigation.rs
@@ -529,22 +529,22 @@ fn setup_buttons_for_triangle_page(
 
     // Direction to navigate from button 3 to button 4, placed below center button
     let below_button_three_entity =
-        spawn_small_text_node(commands, "v\nButton 4".into(), 575, 325, Justify::Center);
+        spawn_small_text_node(commands, "v\nBtn 4".into(), 575, 325, Justify::Center);
     text_entities.push(below_button_three_entity);
 
     // Direction to navigate from button 3 to button 4, placed right of center button
     let right_of_button_three_entity =
-        spawn_small_text_node(commands, "> Button 4".into(), 735, 255, Justify::Left);
+        spawn_small_text_node(commands, "> Btn 4".into(), 735, 255, Justify::Left);
     text_entities.push(right_of_button_three_entity);
 
     // Direction to navigate from button 4 to button 3, placed above bottom right button
     let below_button_three_entity =
-        spawn_small_text_node(commands, "Button 3\n^".into(), 1050, 300, Justify::Center);
+        spawn_small_text_node(commands, "Btn 3\n^".into(), 1050, 300, Justify::Center);
     text_entities.push(below_button_three_entity);
 
     // Direction to navigate from button 4 to button 3, placed left of bottom right button
     let right_of_button_three_entity =
-        spawn_small_text_node(commands, "Button 3 < ".into(), 910, 390, Justify::Right);
+        spawn_small_text_node(commands, "Btn 3 < ".into(), 910, 390, Justify::Right);
     text_entities.push(right_of_button_three_entity);
 
     // Direction to go to the next page, placed bottom of the bottom-right button.

From 9ed9aa207c42182b16d8729febc8e11cb16b0bfb Mon Sep 17 00:00:00 2001
From: Kevin Chen <chen.kevin.f@gmail.com>
Date: Tue, 13 Jan 2026 01:43:39 -0500
Subject: [PATCH 18/25] docs: currently on

---
 examples/ui/navigation/combined_navigation.rs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/examples/ui/navigation/combined_navigation.rs b/examples/ui/navigation/combined_navigation.rs
index 0f42e080f516e..bfe385ff9a10a 100644
--- a/examples/ui/navigation/combined_navigation.rs
+++ b/examples/ui/navigation/combined_navigation.rs
@@ -509,7 +509,7 @@ fn setup_buttons_for_triangle_page(
     // Text describing current page
     let current_page_entity = spawn_small_text_node(
         commands,
-        format!("Page {}", page_num + 1),
+        format!("Currently on Page {}", page_num + 1),
         650,
         20,
         Justify::Center,

From b769de6a60e271088394d4611dcef4e4d0f00b5a Mon Sep 17 00:00:00 2001
From: Kevin Chen <chen.kevin.f@gmail.com>
Date: Tue, 13 Jan 2026 01:51:43 -0500
Subject: [PATCH 19/25] style: add missing ; clippy

---
 examples/ui/navigation/combined_navigation.rs | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/examples/ui/navigation/combined_navigation.rs b/examples/ui/navigation/combined_navigation.rs
index bfe385ff9a10a..d7b9d541d0ef7 100644
--- a/examples/ui/navigation/combined_navigation.rs
+++ b/examples/ui/navigation/combined_navigation.rs
@@ -252,7 +252,7 @@ fn setup_paged_ui(
                 &mut commands,
                 page_num,
                 (page_button_entities, &mut text_entities),
-            )
+            );
         } else {
             // the first and third pages are regular grids
             setup_buttons_for_grid_page(
@@ -335,7 +335,7 @@ fn setup_paged_ui(
     let mut col_entities = Vec::with_capacity(4);
     for col in 0..=2 {
         for row in 0..=3 {
-            col_entities.push(pages_entities[2][row * 3 + col])
+            col_entities.push(pages_entities[2][row * 3 + col]);
         }
         manual_directional_nav_map.add_looping_edges(&col_entities, CompassOctant::North);
         col_entities.clear();

From d6a8a4c522b5d164ce673184ff9b59b129be0200 Mon Sep 17 00:00:00 2001
From: Kevin Chen <chen.kevin.f@gmail.com>
Date: Tue, 13 Jan 2026 14:54:59 -0500
Subject: [PATCH 20/25] refactor: renames examples to clarify intent, removes
 manual nav example

---
 Cargo.toml                                    |  32 +-
 examples/README.md                            |   5 +-
 ...avigation.rs => directional_navigation.rs} |  11 +-
 ...rs => directional_navigation_overrides.rs} |  16 +-
 examples/ui/navigation/manual_navigation.rs   | 412 ------------------
 5 files changed, 25 insertions(+), 451 deletions(-)
 rename examples/ui/navigation/{auto_navigation.rs => directional_navigation.rs} (97%)
 rename examples/ui/navigation/{combined_navigation.rs => directional_navigation_overrides.rs} (98%)
 delete mode 100644 examples/ui/navigation/manual_navigation.rs

diff --git a/Cargo.toml b/Cargo.toml
index fe1c146022ff2..c369b3eccd383 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -5080,38 +5080,26 @@ category = "UI (User Interface)"
 wasm = true
 
 [[example]]
-name = "manual_navigation"
-path = "examples/ui/navigation/manual_navigation.rs"
+name = "directional_navigation"
+path = "examples/ui/navigation/directional_navigation.rs"
 # Causes an ICE on docs.rs
 doc-scrape-examples = false
 
-[package.metadata.example.manual_navigation]
-name = "Manual Directional Navigation"
-description = "Demonstration of manually-defined navigation between UI elements"
+[package.metadata.example.directional_navigation]
+name = "Directional Navigation"
+description = "Demonstration of automatic directional navigation based on UI element positions"
 category = "UI (User Interface)"
 wasm = true
 
 [[example]]
-name = "auto_navigation"
-path = "examples/ui/navigation/auto_navigation.rs"
+name = "directional_navigation_overrides"
+path = "examples/ui/navigation/directional_navigation_overrides.rs"
 # Causes an ICE on docs.rs
 doc-scrape-examples = false
 
-[package.metadata.example.auto_navigation]
-name = "Automatic Directional Navigation"
-description = "Demonstration of automatic navigation based on UI element positions"
-category = "UI (User Interface)"
-wasm = true
-
-[[example]]
-name = "combined_navigation"
-path = "examples/ui/navigation/combined_navigation.rs"
-# Causes an ICE on docs.rs
-doc-scrape-examples = false
-
-[package.metadata.example.combined_navigation]
-name = "Combined (Automatic & Manual) Directional Navigation"
-description = "Demonstration of combining both automatic and manual directional navigation between UI elements"
+[package.metadata.example.directional_navigation_overrides]
+name = "Directional Navigation Overrides"
+description = "Demonstration of automatic directional navigation between UI elements with manual overrides"
 category = "UI (User Interface)"
 wasm = true
 
diff --git a/examples/README.md b/examples/README.md
index 003bc06330e45..5c33a02e2bc8b 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -567,12 +567,12 @@ Example | Description
 Example | Description
 --- | ---
 [Anchor Layout](../examples/ui/anchor_layout.rs) | Shows an 'anchor layout' style of ui layout
-[Automatic Directional Navigation](../examples/ui/navigation/auto_navigation.rs) | Demonstration of automatic navigation based on UI element positions
 [Borders](../examples/ui/borders.rs) | Demonstrates how to create a node with a border
 [Box Shadow](../examples/ui/box_shadow.rs) | Demonstrates how to create a node with a shadow
 [Button](../examples/ui/button.rs) | Illustrates creating and updating a button
 [CSS Grid](../examples/ui/grid.rs) | An example for CSS Grid layout
-[Combined (Automatic & Manual) Directional Navigation](../examples/ui/navigation/combined_navigation.rs) | Demonstration of combining both automatic and manual directional navigation between UI elements
+[Directional Navigation](../examples/ui/navigation/directional_navigation.rs) | Demonstration of automatic directional navigation based on UI element positions
+[Directional Navigation Overrides](../examples/ui/navigation/directional_navigation_overrides.rs) | Demonstration of automatic directional navigation between UI elements with manual overrides
 [Display and Visibility](../examples/ui/display_and_visibility.rs) | Demonstrates how Display and Visibility work in the UI.
 [Drag to Scroll](../examples/ui/drag_to_scroll.rs) | This example tests scale factor, dragging and scrolling
 [Feathers Widgets](../examples/ui/feathers.rs) | Gallery of Feathers Widgets
@@ -582,7 +582,6 @@ Example | Description
 [Font Weights](../examples/ui/font_weights.rs) | Demonstrates how to use font weights.
 [Ghost Nodes](../examples/ui/ghost_nodes.rs) | Demonstrates the use of Ghost Nodes to skip entities in the UI layout hierarchy
 [Gradients](../examples/ui/gradients.rs) | An example demonstrating gradients
-[Manual Directional Navigation](../examples/ui/navigation/manual_navigation.rs) | Demonstration of manually-defined navigation between UI elements
 [Overflow](../examples/ui/overflow.rs) | Simple example demonstrating overflow behavior
 [Overflow Clip Margin](../examples/ui/overflow_clip_margin.rs) | Simple example demonstrating the OverflowClipMargin style property
 [Overflow and Clipping Debug](../examples/ui/overflow_debug.rs) | An example to debug overflow and clipping behavior
diff --git a/examples/ui/navigation/auto_navigation.rs b/examples/ui/navigation/directional_navigation.rs
similarity index 97%
rename from examples/ui/navigation/auto_navigation.rs
rename to examples/ui/navigation/directional_navigation.rs
index 6508d750b5b42..c57e8bb8dc09a 100644
--- a/examples/ui/navigation/auto_navigation.rs
+++ b/examples/ui/navigation/directional_navigation.rs
@@ -1,8 +1,7 @@
-//! Demonstrates automatic directional navigation with zero configuration.
+//! Demonstrates automatic directional navigation.
 //!
-//! Unlike the `manual_navigation` example, this shows how to use automatic
-//! navigation by simply adding the `AutoDirectionalNavigation` component to UI elements.
-//! Navigation is automatically calculated based on screen positions.
+//! This shows how to use automatic navigation by simply adding the `AutoDirectionalNavigation`
+//! component to UI elements. Navigation is automatically calculated based on screen positions.
 //!
 //! This is especially useful for:
 //! - Dynamic UIs where elements may be added, removed, or repositioned
@@ -12,8 +11,8 @@
 //! The automatic system finds the nearest neighbor in each compass direction for every node,
 //! completely eliminating the need to manually specify navigation relationships.
 //!
-//! For an example that combines automatic and manual navigation, refer to the
-//! `combined_navigation` example.
+//! For an example that demonstrates automatic directional navigation with manual overrides,
+//! refer to the `directional_navigation_overrides` example.
 
 use core::time::Duration;
 
diff --git a/examples/ui/navigation/combined_navigation.rs b/examples/ui/navigation/directional_navigation_overrides.rs
similarity index 98%
rename from examples/ui/navigation/combined_navigation.rs
rename to examples/ui/navigation/directional_navigation_overrides.rs
index d7b9d541d0ef7..1e4df263ebda2 100644
--- a/examples/ui/navigation/combined_navigation.rs
+++ b/examples/ui/navigation/directional_navigation_overrides.rs
@@ -1,21 +1,21 @@
-//! Demonstrates a combination of automatic and manual directional navigation.
+//! Demonstrates automatic directional navigation with manual navigation overrides.
 //!
-//! This example shows how to leverage both automatic navigation and manual navigation to create
+//! This example shows how to leverage both automatic navigation and manual overrides to create
 //! a desired user navigation experience without much boilerplate code. In this example, there are
 //! multiple pages of UI Buttons that depict different scenarios in which both automatic and manual
 //! navigation are leveraged to produce a desired navigation experience.
 //!
-//! Manual navigation can also be used to define navigation in any situation where automatic
+//! Manual overrides can be used to define navigation in any situation where automatic
 //! navigation fails to create an edge due to lack of proximity. For example, when creating
-//! navigation that loops around to an opposite side, manual navigation should be used to define
+//! navigation that loops around to an opposite side, manual overrides should be used to define
 //! this behavior. If one input is too far away from the others and `AutoNavigationConfig`
-//! cannot be tweaked, manual navigation can connect that input to the others. Manual navigation
-//! can also be used to override any undesired navigation.
+//! cannot be tweaked, manual overrides can connect that input to the others. Manual navigation
+//! can also be used to override any undesired automatic navigation.
 //!
 //! The `AutoDirectionalNavigation` component is used to create basic, intuitive navigation to UI
 //! elements within a page. Manual navigation edges are added to the `DirectionalNavigationMap`
 //! to create special navigation rules. The `AutoDirectionalNavigator` system parameter navigates
-//! using manual navigation rules first and automatic navigation second.
+//! using manual navigation rules/overrides first and automatic navigation second.
 
 use core::time::Duration;
 
@@ -244,7 +244,7 @@ fn setup_paged_ui(
         Vec::with_capacity(12),
         Vec::with_capacity(12),
     ];
-    let mut text_entities = Vec::with_capacity(6);
+    let mut text_entities = Vec::with_capacity(10);
     for (page_num, page_button_entities) in pages_entities.iter_mut().enumerate() {
         if page_num == 1 {
             // the second page
diff --git a/examples/ui/navigation/manual_navigation.rs b/examples/ui/navigation/manual_navigation.rs
deleted file mode 100644
index 05c328ff521d0..0000000000000
--- a/examples/ui/navigation/manual_navigation.rs
+++ /dev/null
@@ -1,412 +0,0 @@
-//! Demonstrates how to set up a manual directional navigation system to allow for navigation between widgets.
-//!
-//! Directional navigation is generally used to move between widgets in a user interface using arrow keys or gamepad input.
-//! When compared to tab navigation, directional navigation is generally more direct, and less aware of the structure of the UI.
-//!
-//! In this example, we will set up a simple UI with a grid of buttons that can be navigated using the arrow keys or gamepad input.
-//!
-//! **Note:** This example shows manual graph construction for full control. For automatic navigation
-//! based on node positions, see the `auto_navigation` example. For combining both automatic and manual navigation,
-//! see the `combined_navigation` example.
-
-use std::time::Duration;
-
-use bevy::{
-    camera::NormalizedRenderTarget,
-    input_focus::{
-        directional_navigation::{
-            DirectionalNavigation, DirectionalNavigationMap, DirectionalNavigationPlugin,
-        },
-        InputDispatchPlugin, InputFocus, InputFocusVisible,
-    },
-    math::CompassOctant,
-    picking::{
-        backend::HitData,
-        pointer::{Location, PointerId},
-    },
-    platform::collections::{HashMap, HashSet},
-    prelude::*,
-};
-
-fn main() {
-    App::new()
-        // Input focus is not enabled by default, so we need to add the corresponding plugins
-        .add_plugins((
-            DefaultPlugins,
-            InputDispatchPlugin,
-            DirectionalNavigationPlugin,
-        ))
-        // This resource is canonically used to track whether or not to render a focus indicator
-        // It starts as false, but we set it to true here as we would like to see the focus indicator
-        .insert_resource(InputFocusVisible(true))
-        // We've made a simple resource to keep track of the actions that are currently being pressed for this example
-        .init_resource::<ActionState>()
-        .add_systems(Startup, setup_ui)
-        // Input is generally handled during PreUpdate
-        // We're turning inputs into actions first, then using those actions to determine navigation
-        .add_systems(PreUpdate, (process_inputs, navigate).chain())
-        .add_systems(
-            Update,
-            (
-                // We need to show which button is currently focused
-                highlight_focused_element,
-                // Pressing the "Interact" button while we have a focused element should simulate a click
-                interact_with_focused_button,
-                // We're doing a tiny animation when the button is interacted with,
-                // so we need a timer and a polling mechanism to reset it
-                reset_button_after_interaction,
-            ),
-        )
-        // This observer is added globally, so it will respond to *any* trigger of the correct type.
-        // However, we're filtering in the observer's query to only respond to button presses
-        .add_observer(universal_button_click_behavior)
-        .run();
-}
-
-const NORMAL_BUTTON: Srgba = bevy::color::palettes::tailwind::BLUE_400;
-const PRESSED_BUTTON: Srgba = bevy::color::palettes::tailwind::BLUE_500;
-const FOCUSED_BORDER: Srgba = bevy::color::palettes::tailwind::BLUE_50;
-
-// This observer will be triggered whenever a button is pressed
-// In a real project, each button would also have its own unique behavior,
-// to capture the actual intent of the user
-fn universal_button_click_behavior(
-    mut click: On<Pointer<Click>>,
-    mut button_query: Query<(&mut BackgroundColor, &mut ResetTimer)>,
-) {
-    let button_entity = click.entity;
-    if let Ok((mut color, mut reset_timer)) = button_query.get_mut(button_entity) {
-        // This would be a great place to play a little sound effect too!
-        color.0 = PRESSED_BUTTON.into();
-        reset_timer.0 = Timer::from_seconds(0.3, TimerMode::Once);
-
-        // Picking events propagate up the hierarchy,
-        // so we need to stop the propagation here now that we've handled it
-        click.propagate(false);
-    }
-}
-
-/// Resets a UI element to its default state when the timer has elapsed.
-#[derive(Component, Default, Deref, DerefMut)]
-struct ResetTimer(Timer);
-
-fn reset_button_after_interaction(
-    time: Res<Time>,
-    mut query: Query<(&mut ResetTimer, &mut BackgroundColor)>,
-) {
-    for (mut reset_timer, mut color) in query.iter_mut() {
-        reset_timer.tick(time.delta());
-        if reset_timer.just_finished() {
-            color.0 = NORMAL_BUTTON.into();
-        }
-    }
-}
-
-// We're spawning a simple grid of buttons and some instructions
-// The buttons are just colored rectangles with text displaying the button's name
-fn setup_ui(
-    mut commands: Commands,
-    mut directional_nav_map: ResMut<DirectionalNavigationMap>,
-    mut input_focus: ResMut<InputFocus>,
-) {
-    const N_ROWS: u16 = 5;
-    const N_COLS: u16 = 3;
-
-    // Rendering UI elements requires a camera
-    commands.spawn(Camera2d);
-
-    // Create a full-screen background node
-    let root_node = commands
-        .spawn(Node {
-            width: percent(100),
-            height: percent(100),
-            ..default()
-        })
-        .id();
-
-    // Add instruction to the left of the grid
-    let instructions = commands
-        .spawn((
-            Text::new("Use arrow keys or D-pad to navigate. \
-            Click the buttons, or press Enter / the South gamepad button to interact with the focused button."),
-            Node {
-                width: px(300),
-                justify_content: JustifyContent::Center,
-                align_items: AlignItems::Center,
-                margin: UiRect::all(px(12)),
-                ..default()
-            },
-        ))
-        .id();
-
-    // Set up the root entity to hold the grid
-    let grid_root_entity = commands
-        .spawn(Node {
-            display: Display::Grid,
-            // Allow the grid to take up the full height and the rest of the width of the window
-            width: percent(100),
-            height: percent(100),
-            // Set the number of rows and columns in the grid
-            // allowing the grid to automatically size the cells
-            grid_template_columns: RepeatedGridTrack::auto(N_COLS),
-            grid_template_rows: RepeatedGridTrack::auto(N_ROWS),
-            ..default()
-        })
-        .id();
-
-    // Add the instructions and grid to the root node
-    commands
-        .entity(root_node)
-        .add_children(&[instructions, grid_root_entity]);
-
-    let mut button_entities: HashMap<(u16, u16), Entity> = HashMap::default();
-    for row in 0..N_ROWS {
-        for col in 0..N_COLS {
-            let button_name = format!("Button {row}-{col}");
-
-            let button_entity = commands
-                .spawn((
-                    Button,
-                    Node {
-                        width: px(200),
-                        height: px(120),
-                        // Add a border so we can show which element is focused
-                        border: UiRect::all(px(4)),
-                        // Center the button's text label
-                        justify_content: JustifyContent::Center,
-                        align_items: AlignItems::Center,
-                        // Center the button within the grid cell
-                        align_self: AlignSelf::Center,
-                        justify_self: JustifySelf::Center,
-                        border_radius: BorderRadius::all(px(16)),
-                        ..default()
-                    },
-                    ResetTimer::default(),
-                    BackgroundColor::from(NORMAL_BUTTON),
-                    Name::new(button_name.clone()),
-                ))
-                // Add a text element to the button
-                .with_child((
-                    Text::new(button_name),
-                    // And center the text if it flows onto multiple lines
-                    TextLayout {
-                        justify: Justify::Center,
-                        ..default()
-                    },
-                ))
-                .id();
-
-            // Add the button to the grid
-            commands.entity(grid_root_entity).add_child(button_entity);
-
-            // Keep track of the button entities so we can set up our navigation graph
-            button_entities.insert((row, col), button_entity);
-        }
-    }
-
-    // Connect all of the buttons in the same row to each other,
-    // looping around when the edge is reached.
-    for row in 0..N_ROWS {
-        let entities_in_row: Vec<Entity> = (0..N_COLS)
-            .map(|col| button_entities.get(&(row, col)).unwrap())
-            .copied()
-            .collect();
-        directional_nav_map.add_looping_edges(&entities_in_row, CompassOctant::East);
-    }
-
-    // Connect all of the buttons in the same column to each other,
-    // but don't loop around when the edge is reached.
-    // While looping is a very reasonable choice, we're not doing it here to demonstrate the different options.
-    for col in 0..N_COLS {
-        let entities_in_column: Vec<Entity> = (0..N_ROWS)
-            .map(|row| button_entities.get(&(row, col)).unwrap())
-            .copied()
-            .collect();
-
-        directional_nav_map.add_edges(&entities_in_column, CompassOctant::South);
-    }
-
-    // When changing scenes, remember to set an initial focus!
-    let top_left_entity = *button_entities.get(&(0, 0)).unwrap();
-    input_focus.set(top_left_entity);
-}
-
-// The indirection between inputs and actions allows us to easily remap inputs
-// and handle multiple input sources (keyboard, gamepad, etc.) in our game
-#[derive(Debug, PartialEq, Eq, Hash)]
-enum DirectionalNavigationAction {
-    Up,
-    Down,
-    Left,
-    Right,
-    Select,
-}
-
-impl DirectionalNavigationAction {
-    fn variants() -> Vec<Self> {
-        vec![
-            DirectionalNavigationAction::Up,
-            DirectionalNavigationAction::Down,
-            DirectionalNavigationAction::Left,
-            DirectionalNavigationAction::Right,
-            DirectionalNavigationAction::Select,
-        ]
-    }
-
-    fn keycode(&self) -> KeyCode {
-        match self {
-            DirectionalNavigationAction::Up => KeyCode::ArrowUp,
-            DirectionalNavigationAction::Down => KeyCode::ArrowDown,
-            DirectionalNavigationAction::Left => KeyCode::ArrowLeft,
-            DirectionalNavigationAction::Right => KeyCode::ArrowRight,
-            DirectionalNavigationAction::Select => KeyCode::Enter,
-        }
-    }
-
-    fn gamepad_button(&self) -> GamepadButton {
-        match self {
-            DirectionalNavigationAction::Up => GamepadButton::DPadUp,
-            DirectionalNavigationAction::Down => GamepadButton::DPadDown,
-            DirectionalNavigationAction::Left => GamepadButton::DPadLeft,
-            DirectionalNavigationAction::Right => GamepadButton::DPadRight,
-            // This is the "A" button on an Xbox controller,
-            // and is conventionally used as the "Select" / "Interact" button in many games
-            DirectionalNavigationAction::Select => GamepadButton::South,
-        }
-    }
-}
-
-// This keeps track of the inputs that are currently being pressed
-#[derive(Default, Resource)]
-struct ActionState {
-    pressed_actions: HashSet<DirectionalNavigationAction>,
-}
-
-fn process_inputs(
-    mut action_state: ResMut<ActionState>,
-    keyboard_input: Res<ButtonInput<KeyCode>>,
-    gamepad_input: Query<&Gamepad>,
-) {
-    // Reset the set of pressed actions each frame
-    // to ensure that we only process each action once
-    action_state.pressed_actions.clear();
-
-    for action in DirectionalNavigationAction::variants() {
-        // Use just_pressed to ensure that we only process each action once
-        // for each time it is pressed
-        if keyboard_input.just_pressed(action.keycode()) {
-            action_state.pressed_actions.insert(action);
-        }
-    }
-
-    // We're treating this like a single-player game:
-    // if multiple gamepads are connected, we don't care which one is being used
-    for gamepad in gamepad_input.iter() {
-        for action in DirectionalNavigationAction::variants() {
-            // Unlike keyboard input, gamepads are bound to a specific controller
-            if gamepad.just_pressed(action.gamepad_button()) {
-                action_state.pressed_actions.insert(action);
-            }
-        }
-    }
-}
-
-fn navigate(action_state: Res<ActionState>, mut directional_navigation: DirectionalNavigation) {
-    // If the user is pressing both left and right, or up and down,
-    // we should not move in either direction.
-    let net_east_west = action_state
-        .pressed_actions
-        .contains(&DirectionalNavigationAction::Right) as i8
-        - action_state
-            .pressed_actions
-            .contains(&DirectionalNavigationAction::Left) as i8;
-
-    let net_north_south = action_state
-        .pressed_actions
-        .contains(&DirectionalNavigationAction::Up) as i8
-        - action_state
-            .pressed_actions
-            .contains(&DirectionalNavigationAction::Down) as i8;
-
-    // Compute the direction that the user is trying to navigate in
-    let maybe_direction = match (net_east_west, net_north_south) {
-        (0, 0) => None,
-        (0, 1) => Some(CompassOctant::North),
-        (1, 1) => Some(CompassOctant::NorthEast),
-        (1, 0) => Some(CompassOctant::East),
-        (1, -1) => Some(CompassOctant::SouthEast),
-        (0, -1) => Some(CompassOctant::South),
-        (-1, -1) => Some(CompassOctant::SouthWest),
-        (-1, 0) => Some(CompassOctant::West),
-        (-1, 1) => Some(CompassOctant::NorthWest),
-        _ => None,
-    };
-
-    if let Some(direction) = maybe_direction {
-        match directional_navigation.navigate(direction) {
-            // In a real game, you would likely want to play a sound or show a visual effect
-            // on both successful and unsuccessful navigation attempts
-            Ok(entity) => {
-                println!("Navigated {direction:?} successfully. {entity} is now focused.");
-            }
-            Err(e) => println!("Navigation failed: {e}"),
-        }
-    }
-}
-
-fn highlight_focused_element(
-    input_focus: Res<InputFocus>,
-    // While this isn't strictly needed for the example,
-    // we're demonstrating how to be a good citizen by respecting the `InputFocusVisible` resource.
-    input_focus_visible: Res<InputFocusVisible>,
-    mut query: Query<(Entity, &mut BorderColor)>,
-) {
-    for (entity, mut border_color) in query.iter_mut() {
-        if input_focus.0 == Some(entity) && input_focus_visible.0 {
-            // Don't change the border size / radius here,
-            // as it would result in wiggling buttons when they are focused
-            *border_color = BorderColor::all(FOCUSED_BORDER);
-        } else {
-            *border_color = BorderColor::DEFAULT;
-        }
-    }
-}
-
-// By sending a Pointer<Click> trigger rather than directly handling button-like interactions,
-// we can unify our handling of pointer and keyboard/gamepad interactions
-fn interact_with_focused_button(
-    action_state: Res<ActionState>,
-    input_focus: Res<InputFocus>,
-    mut commands: Commands,
-) {
-    if action_state
-        .pressed_actions
-        .contains(&DirectionalNavigationAction::Select)
-        && let Some(focused_entity) = input_focus.0
-    {
-        commands.trigger(Pointer::<Click> {
-            entity: focused_entity,
-            // We're pretending that we're a mouse
-            pointer_id: PointerId::Mouse,
-            // This field isn't used, so we're just setting it to a placeholder value
-            pointer_location: Location {
-                target: NormalizedRenderTarget::None {
-                    width: 0,
-                    height: 0,
-                },
-                position: Vec2::ZERO,
-            },
-            event: Click {
-                button: PointerButton::Primary,
-                // This field isn't used, so we're just setting it to a placeholder value
-                hit: HitData {
-                    camera: Entity::PLACEHOLDER,
-                    depth: 0.0,
-                    position: None,
-                    normal: None,
-                },
-                duration: Duration::from_secs_f32(0.1),
-            },
-        });
-    }
-}

From f246aeb139be2eada2e8a62d7f4832e433bd8570 Mon Sep 17 00:00:00 2001
From: Kevin Chen <chen.kevin.f@gmail.com>
Date: Tue, 13 Jan 2026 15:34:14 -0500
Subject: [PATCH 21/25] docs: comment pass on dir nav classes

---
 .../src/directional_navigation.rs             | 51 ++++++++++++-------
 .../src/auto_directional_navigation.rs        | 27 ++++++++--
 2 files changed, 56 insertions(+), 22 deletions(-)

diff --git a/crates/bevy_input_focus/src/directional_navigation.rs b/crates/bevy_input_focus/src/directional_navigation.rs
index a7b45788d5fe0..1fa07239a9fb1 100644
--- a/crates/bevy_input_focus/src/directional_navigation.rs
+++ b/crates/bevy_input_focus/src/directional_navigation.rs
@@ -1,4 +1,9 @@
-//! A navigation framework for moving between focusable elements based on directional input.
+//! A manual navigation framework for moving between focusable elements based on directional input.
+//!
+//! Note: If using `bevy_ui`, this manual navigation framework is used to provide overrides
+//! for its automatic navigation framework based on the `AutoDirectionalNavigation` component.
+//! Most times, the automatic navigation framework alone should be sufficient.
+//! If not using `bevy_ui`, this manual navigation framework can still be used by itself.
 //!
 //! While virtual cursors are a common way to navigate UIs with a gamepad (or arrow keys!),
 //! they are generally both slow and frustrating to use.
@@ -7,15 +12,15 @@
 //! Like the rest of this crate, the [`InputFocus`] resource is manipulated to track
 //! the current focus.
 //!
+//! This module's [`DirectionalNavigationMap`] stores a directed graph of focusable entities.
+//! Each entity can have up to 8 neighbors, one for each [`CompassOctant`], balancing
+//! flexibility and required precision.
+//!
 //! Navigating between focusable entities (commonly UI nodes) is done by
 //! passing a [`CompassOctant`] into the [`navigate`](DirectionalNavigation::navigate) method
-//! from the [`DirectionalNavigation`] system parameter. Under the hood, an entity is found
-//! automatically via brute force search in the desired [`CompassOctant`] direction.
-//!
-//! If some manual navigation is desired, a [`DirectionalNavigationMap`] will override the brute force
-//! search in a direction for a given entity. The [`DirectionalNavigationMap`] stores a directed graph
-//! of focusable entities. Each entity can have up to 8 neighbors, one for each [`CompassOctant`],
-//! balancing flexibility and required precision.
+//! from the [`DirectionalNavigation`] system parameter. Under the hood, the
+//! [`DirectionalNavigationMap`] is used to return the focusable entity in a direction
+//! for a given entity.
 //!
 //! # Setting up Directional Navigation
 //!
@@ -26,21 +31,26 @@
 //! include automatic navigation, you should also use the `AutoDirectionalNavigator` system parameter
 //! in that crate instead of [`DirectionalNavigation`].
 //!
-//! ## Manual Navigation
-//!
-//! You can also manually define navigation connections using methods like
-//! [`add_edge`](DirectionalNavigationMap::add_edge) and
-//! [`add_looping_edges`](DirectionalNavigationMap::add_looping_edges).
-//!
-//! ## Combining Automatic and Manual
+//! ## Combining Automatic Navigation with Manual Overrides
 //!
 //! Following manual edges always take precedence, allowing you to use
 //! automatic navigation for most UI elements while overriding specific connections for
-//! special cases like wrapping menus or cross-layer navigation.
+//! special cases like wrapping menus or cross-layer navigation. If you need to override
+//! automatic navigation behavior, use the [`DirectionalNavigationMap`] to define
+//! overriding edges between UI entities.
+//!
+//! ## Manual Navigation Only
+//!
+//! Manually define your navigation using the [`DirectionalNavigationMap`], and use the
+//! [`DirectionalNavigation`] system parameter to navigate between components.
+//! You can define navigation connections using methods like
+//! [`add_edge`](DirectionalNavigationMap::add_edge) and
+//! [`add_looping_edges`](DirectionalNavigationMap::add_looping_edges).
 //!
-//! ## When to Use Manual Navigation
+//! ## When to Use Manual Navigation or Manual Overrides
 //!
-//! While automatic navigation is recommended for most use cases, manual navigation provides:
+//! While automatic navigation is recommended and satisfactory for most use cases,
+//! using manual navigation only or integrating manual overrides to automatic navigation provide:
 //!
 //! - **Precise control**: Define exact navigation flow, including non-obvious connections like looping edges
 //! - **Cross-layer navigation**: Connect elements across different UI layers or z-index levels
@@ -189,6 +199,11 @@ impl NavNeighbors {
 ///
 /// This graph must be built and maintained manually, and the developer is responsible for ensuring that it meets the above criteria.
 /// Notably, if the developer adds or removes the navigability of an entity, the developer should update the map as necessary.
+///
+/// If the automatic navigation system in `bevy_ui` is being used, this resource can be used to specify
+/// manual navigation overrides. Any navigation edges specified in this map take precedence over automatic
+/// navigation. For example, if navigation on one side of the window should wrap around to
+/// the other side of the window, this navigation behavior can be specified using this map.
 #[derive(Resource, Debug, Default, Clone, PartialEq)]
 #[cfg_attr(
     feature = "bevy_reflect",
diff --git a/crates/bevy_ui/src/auto_directional_navigation.rs b/crates/bevy_ui/src/auto_directional_navigation.rs
index a3072e486f443..eb650d0d25896 100644
--- a/crates/bevy_ui/src/auto_directional_navigation.rs
+++ b/crates/bevy_ui/src/auto_directional_navigation.rs
@@ -1,7 +1,21 @@
-//! An automatic directional navigation system, powered by the [`AutoDirectionalNavigation`] component.
+//! An automatic directional navigation system, powered by the [`AutoDirectionalNavigation`]
+//! component.
 //!
-//! [`AutoDirectionalNavigator`] expands on the manual directional navigation system
-//! provided by the [`DirectionalNavigation`] system parameter from `bevy_input_focus`.
+//! Unlike the navigation system provided by `bevy_input_focus`, the automatic directional
+//! navigation system does not require specifying navigation edges. Just simply add the
+//! [`AutoDirectionalNavigation`] component to your entities, and the system will automatically
+//! calculate the navigation edges between entities based on screen position.
+//!
+//! [`AutoDirectionalNavigator`] replaces the manual directional navigation system
+//! provided by the [`DirectionalNavigation`] system parameter from `bevy_input_focus`. The
+//! [`AutoDirectionalNavigator`] will first navigate using manual override edges defined in the
+//! [`DirectionalNavigationMap`](bevy_input_focus::directional_navigation::DirectionalNavigationMap).
+//! If no manual overrides are defined, automatic navigation will occur between entities based on
+//! screen position.
+//!
+//! If any resulting navigation behavior is undesired, [`AutoNavigationConfig`] can be tweaked or
+//! manual overrides can be specified using the
+//! [`DirectionalNavigationMap`](bevy_input_focus::directional_navigation::DirectionalNavigationMap).
 
 use crate::{ComputedNode, ComputedUiTargetCamera, UiGlobalTransform};
 use bevy_camera::visibility::InheritedVisibility;
@@ -72,7 +86,7 @@ use bevy_reflect::{prelude::*, Reflect};
 ///   automatic navigation as needed.
 ///
 /// Manual edges defined via [`DirectionalNavigationMap`](bevy_input_focus::directional_navigation::DirectionalNavigationMap)
-/// are completely independent and will continue to work regardless of this component.
+/// will override any automatically calculated edges.
 ///
 /// # Additional Requirements
 ///
@@ -237,6 +251,11 @@ impl<'w, 's> AutoDirectionalNavigator<'w, 's> {
     }
 }
 
+/// Util used to get the resulting bounds of a UI entity after applying its rotation.
+///
+/// This is necessary to apply because navigation should only use the final screen position
+/// of an entity in automatic navigation calculations. These bounds are used as the entity's size in
+/// [`FocusableArea`].
 fn get_rotated_bounds(size: Vec2, rotation: f32) -> Vec2 {
     if rotation == 0.0 {
         return size;

From 093af728397093ca91de1600a9c54e4994104a3c Mon Sep 17 00:00:00 2001
From: Kevin Chen <chen.kevin.f@gmail.com>
Date: Tue, 13 Jan 2026 16:30:19 -0500
Subject: [PATCH 22/25] docs: fix names within examples themselves

---
 examples/ui/navigation/directional_navigation.rs           | 2 +-
 examples/ui/navigation/directional_navigation_overrides.rs | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/examples/ui/navigation/directional_navigation.rs b/examples/ui/navigation/directional_navigation.rs
index c57e8bb8dc09a..49b7907f02641 100644
--- a/examples/ui/navigation/directional_navigation.rs
+++ b/examples/ui/navigation/directional_navigation.rs
@@ -132,7 +132,7 @@ fn setup_scattered_ui(mut commands: Commands, mut input_focus: ResMut<InputFocus
     let instructions = commands
         .spawn((
             Text::new(
-                "Automatic Navigation Demo\n\n\
+                "Directional Navigation Demo\n\n\
                  Use arrow keys or D-pad to navigate.\n\
                  Press Enter or A button to interact.\n\n\
                  Buttons are scattered irregularly,\n\
diff --git a/examples/ui/navigation/directional_navigation_overrides.rs b/examples/ui/navigation/directional_navigation_overrides.rs
index 1e4df263ebda2..8024bf93c6321 100644
--- a/examples/ui/navigation/directional_navigation_overrides.rs
+++ b/examples/ui/navigation/directional_navigation_overrides.rs
@@ -180,7 +180,7 @@ fn setup_paged_ui(
     let instructions = commands
         .spawn((
             Text::new(
-                "Combined Navigation Demo\n\n\
+                "Directional Navigation Overrides Demo\n\n\
                  Use arrow keys or D-pad to navigate.\n\
                  Press Enter or A button to interact.\n\n\
                  Navigation on each page is a combination of \

From fb84a036bd515c0c7d9605d032402ebb24553da7 Mon Sep 17 00:00:00 2001
From: Kevin Chen <chen.kevin.f@gmail.com>
Date: Tue, 13 Jan 2026 23:34:14 -0500
Subject: [PATCH 23/25] docs: doc-link structs in examples

---
 .../ui/navigation/directional_navigation.rs   |  2 +-
 .../directional_navigation_overrides.rs       | 26 +++++++++----------
 2 files changed, 13 insertions(+), 15 deletions(-)

diff --git a/examples/ui/navigation/directional_navigation.rs b/examples/ui/navigation/directional_navigation.rs
index 49b7907f02641..d7f37ecfc9c28 100644
--- a/examples/ui/navigation/directional_navigation.rs
+++ b/examples/ui/navigation/directional_navigation.rs
@@ -1,6 +1,6 @@
 //! Demonstrates automatic directional navigation.
 //!
-//! This shows how to use automatic navigation by simply adding the `AutoDirectionalNavigation`
+//! This shows how to use automatic navigation by simply adding the [`AutoDirectionalNavigation`]
 //! component to UI elements. Navigation is automatically calculated based on screen positions.
 //!
 //! This is especially useful for:
diff --git a/examples/ui/navigation/directional_navigation_overrides.rs b/examples/ui/navigation/directional_navigation_overrides.rs
index 8024bf93c6321..03d1416ee190b 100644
--- a/examples/ui/navigation/directional_navigation_overrides.rs
+++ b/examples/ui/navigation/directional_navigation_overrides.rs
@@ -12,9 +12,9 @@
 //! cannot be tweaked, manual overrides can connect that input to the others. Manual navigation
 //! can also be used to override any undesired automatic navigation.
 //!
-//! The `AutoDirectionalNavigation` component is used to create basic, intuitive navigation to UI
-//! elements within a page. Manual navigation edges are added to the `DirectionalNavigationMap`
-//! to create special navigation rules. The `AutoDirectionalNavigator` system parameter navigates
+//! The [`AutoDirectionalNavigation`] component is used to create basic, intuitive navigation to UI
+//! elements within a page. Manual navigation edges are added to the [`DirectionalNavigationMap`]
+//! to create special navigation rules. The [`AutoDirectionalNavigator`] system parameter navigates
 //! using manual navigation rules/overrides first and automatic navigation second.
 
 use core::time::Duration;
@@ -151,15 +151,16 @@ fn reset_button_after_interaction(
 
 /// Spawn pages of buttons to demonstrate automatic and manual navigation.
 ///
-/// This function creates three pages of buttons. All buttons have automatic navigation.
-/// Manual navigation is specified with the `DirectionalNavigationMap`.
+/// This function creates three pages of buttons. All buttons have automatic navigation
+/// enabled by having the [`AutoDirectionalNavigation`] component.
+/// Manual navigation is specified with the [`DirectionalNavigationMap`].
 /// Page 1 has a simple grid of buttons where transitions between rows is defined using
-/// the `DirectionalNavigationMap`.
+/// the [`DirectionalNavigationMap`].
 /// Page 2 has a cluster of buttons to the top left and a lonely button on the bottom right.
 /// Navigation between the cluster and the lonely button is defined using the
-/// `DirectionalNavigationMap`.
+/// [`DirectionalNavigationMap`].
 /// Page 3 has the same simple grid of buttons as page 1, but automatic navigation has been
-/// overridden in the vertical direction with the `DirectionalNavigationMap`.
+/// overridden in the vertical direction with the [`DirectionalNavigationMap`].
 fn setup_paged_ui(
     mut commands: Commands,
     mut manual_directional_nav_map: ResMut<DirectionalNavigationMap>,
@@ -198,6 +199,7 @@ fn setup_paged_ui(
             BackgroundColor(Color::srgba(0.1, 0.1, 0.1, 0.8)),
         ))
         .id();
+    commands.entity(root_node).add_children(&[instructions]);
 
     // Focus display - shows which button is currently focused
     commands.spawn((
@@ -239,6 +241,7 @@ fn setup_paged_ui(
         },
     ));
 
+    // Setup the pages with buttons and helper text
     let mut pages_entities = [
         Vec::with_capacity(12),
         Vec::with_capacity(12),
@@ -286,7 +289,6 @@ fn setup_paged_ui(
 
         text_entities.clear();
     }
-    let first_button = Some(pages_entities[0][0]);
 
     // For Pages 1 and 3, add manual edges within the grid page for navigation between rows.
     let entity_pairs = [
@@ -373,12 +375,8 @@ fn setup_paged_ui(
         CompassOctant::East,
     );
 
-    commands.entity(root_node).add_children(&[instructions]);
-
     // Set initial focus
-    if let Some(button) = first_button {
-        input_focus.set(button);
-    }
+    input_focus.set(pages_entities[0][0]);
 }
 
 /// Creates the buttons and text for a grid page and places the ids into their

From fa811474489144300cb213f4ce4a1f832d8380f4 Mon Sep 17 00:00:00 2001
From: Kevin Chen <chen.kevin.f@gmail.com>
Date: Tue, 13 Jan 2026 23:41:33 -0500
Subject: [PATCH 24/25] docs: clean up outdated comment

---
 examples/ui/navigation/directional_navigation.rs           | 2 +-
 examples/ui/navigation/directional_navigation_overrides.rs | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/examples/ui/navigation/directional_navigation.rs b/examples/ui/navigation/directional_navigation.rs
index d7f37ecfc9c28..e9a54335cd1e3 100644
--- a/examples/ui/navigation/directional_navigation.rs
+++ b/examples/ui/navigation/directional_navigation.rs
@@ -265,7 +265,7 @@ fn setup_scattered_ui(mut commands: Commands, mut input_focus: ResMut<InputFocus
     }
 }
 
-// Action state and input handling (same as the manual navigation example)
+// Action state and input handling
 #[derive(Debug, PartialEq, Eq, Hash)]
 enum DirectionalNavigationAction {
     Up,
diff --git a/examples/ui/navigation/directional_navigation_overrides.rs b/examples/ui/navigation/directional_navigation_overrides.rs
index 03d1416ee190b..84930f65a05eb 100644
--- a/examples/ui/navigation/directional_navigation_overrides.rs
+++ b/examples/ui/navigation/directional_navigation_overrides.rs
@@ -625,7 +625,7 @@ fn spawn_small_text_node(
         .id()
 }
 
-// Action state and input handling (same as the manual navigation example)
+// Action state and input handling
 #[derive(Debug, PartialEq, Eq, Hash)]
 enum DirectionalNavigationAction {
     Up,

From 12ca70a5d480cb8c428349e121c4c85c15368a56 Mon Sep 17 00:00:00 2001
From: Kevin Chen <chen.kevin.f@gmail.com>
Date: Wed, 14 Jan 2026 10:58:08 -0500
Subject: [PATCH 25/25] docs: note that search distance is btwn closest edges

---
 crates/bevy_input_focus/src/directional_navigation.rs      | 1 +
 examples/ui/navigation/directional_navigation.rs           | 2 +-
 examples/ui/navigation/directional_navigation_overrides.rs | 2 +-
 3 files changed, 3 insertions(+), 2 deletions(-)

diff --git a/crates/bevy_input_focus/src/directional_navigation.rs b/crates/bevy_input_focus/src/directional_navigation.rs
index 1fa07239a9fb1..9a9da75aff853 100644
--- a/crates/bevy_input_focus/src/directional_navigation.rs
+++ b/crates/bevy_input_focus/src/directional_navigation.rs
@@ -132,6 +132,7 @@ pub struct AutoNavigationConfig {
     /// Maximum search distance in logical pixels.
     ///
     /// Nodes beyond this distance won't be connected. `None` means unlimited.
+    /// The distance between two UI elements is calculated using their closest edges.
     pub max_search_distance: Option<f32>,
 
     /// Whether to prefer nodes that are more aligned with the exact direction.
diff --git a/examples/ui/navigation/directional_navigation.rs b/examples/ui/navigation/directional_navigation.rs
index e9a54335cd1e3..492ddc73b2fb2 100644
--- a/examples/ui/navigation/directional_navigation.rs
+++ b/examples/ui/navigation/directional_navigation.rs
@@ -47,7 +47,7 @@ fn main() {
         .insert_resource(AutoNavigationConfig {
             // Require at least 10% overlap in perpendicular axis for cardinal directions
             min_alignment_factor: 0.1,
-            // Don't connect nodes more than 500 pixels apart
+            // Don't connect nodes more than 500 pixels apart between their closest edges
             max_search_distance: Some(500.0),
             // Prefer nodes that are well-aligned
             prefer_aligned: true,
diff --git a/examples/ui/navigation/directional_navigation_overrides.rs b/examples/ui/navigation/directional_navigation_overrides.rs
index 84930f65a05eb..147d2f052d559 100644
--- a/examples/ui/navigation/directional_navigation_overrides.rs
+++ b/examples/ui/navigation/directional_navigation_overrides.rs
@@ -53,7 +53,7 @@ fn main() {
         .insert_resource(AutoNavigationConfig {
             // Require at least 10% overlap in perpendicular axis for cardinal directions
             min_alignment_factor: 0.1,
-            // Don't connect nodes more than 200 pixels apart
+            // Don't connect nodes more than 200 pixels apart between their closest edges
             max_search_distance: Some(200.0),
             // Prefer nodes that are well-aligned
             prefer_aligned: true,