NEOLearn

Interaction

Make UI respond to the mouse and touch: the Button widget and its Activate event, hover and pressed state, pointer event observers, disabling, drag and drop, and letting clicks pass through.

Updated October 20, 2026

On this page

UI nodes are hit-tested by the engine's picking system, the same one that picks sprites and meshes. Picking turns mouse and touch input into events on the node under the pointer, and keeps a few state components up to date. You react with observers or by reading the state in a system.

UI picking is on in NEO's builds and every UI node takes part by default.

Buttons#

Button from neo::ui_widgets is a headless button: it handles pointer and keyboard input, tracks whether it's pressed, and triggers an Activate event when it's clicked. It has no look of its own.

src/menu.rs
use neo::{
    picking::hover::Hovered,
    prelude::*,
    ui_widgets::{observe, Activate, Button},
};

fn spawn_play_button(mut commands: Commands) {
    commands.spawn((
        Button,
        Hovered::default(), // keep hover state up to date
        Node {
            width: px(150),
            height: px(65),
            justify_content: JustifyContent::Center,
            align_items: AlignItems::Center,
            border_radius: BorderRadius::MAX,
            ..default()
        },
        BackgroundColor(Color::srgb(0.15, 0.15, 0.15)),
        observe(|_activate: On<Activate>, mut next: ResMut<NextState<GameState>>| {
            next.set(GameState::Playing);
        }),
        children![Text::new("Play")],
    ));
}

observe(...) adds an observer to the entity as it's spawned; commands.spawn(..).observe(..) does the same afterwards. Observers are covered in Events and observers.

Button activates when the pointer is released over it. Add ActivateOnPress to activate on press instead, which suits menu buttons. A focused button also activates with Enter or Space; see Focus and navigation.

Hover and pressed state#

To style a node by its state, read these components:

ComponentFromMeaning
Hoveredneo::picking::hoverhovered.get() is true while the pointer is over the node or one of its children. Add Hovered::default() to entities you want tracked.
Pressedneo::uiPresent while a widget is held down. Button adds and removes it.
InteractionDisabledneo::uiAdd it to stop a widget from activating. Style it greyed out yourself.
Rust
fn style_buttons(
    mut buttons: Query<(&Hovered, Has<Pressed>, Has<InteractionDisabled>, &mut BackgroundColor), With<Button>>,
) {
    for (hovered, pressed, disabled, mut color) in &mut buttons {
        *color = match (disabled, pressed, hovered.get()) {
            (true, _, _) => Color::srgb(0.3, 0.3, 0.3),
            (_, true, _) => Color::srgb(0.35, 0.75, 0.35),
            (_, _, true) => Color::srgb(0.25, 0.25, 0.25),
            _ => Color::srgb(0.15, 0.15, 0.15),
        }
        .into();
    }
}

Hovered only changes when the pointer enters or leaves, so filter on Changed<Hovered> to restyle only when something happened. You can also react to the change with an observer, such as On<Insert, Pressed>.

Pointer events#

Every pickable node receives pointer events, which you handle with observers:

EventWhen
PointerOver, PointerOutThe pointer moves onto or off the node.
PointerPress, PointerReleaseA button or finger goes down or up on it.
PointerClickA press and release on the same node. count says how many clicks in a row.
PointerMoveThe pointer moves over it.
PointerScrollThe wheel or trackpad scrolls over it.
PointerDragStart, PointerDrag, PointerDragEndIt's dragged; distance is the offset from the start.
PointerDragEnter, PointerDragOver, PointerDragLeave, PointerDragDropSomething dragged moves over it or is dropped on it.

Events bubble up to parents, so one observer on a panel hears clicks on everything inside it. Call event.propagate(false) to stop that.

Rust
commands
    .spawn((Node { width: px(80), height: px(80), ..default() }, BackgroundColor(Color::WHITE)))
    .observe(|click: On<PointerClick>| info!("clicked {} ({} times)", click.entity, click.count));

Drag and drop#

Move a node while it's dragged with a UiTransform, so its place in the layout stays put until the drop:

Rust
commands
    .spawn((Node { width: px(64), height: px(64), ..default() }, BackgroundColor(Color::WHITE)))
    .observe(|drag: On<PointerDrag>, mut q: Query<&mut UiTransform>| {
        if let Ok(mut t) = q.get_mut(drag.event_target()) {
            t.translation = Val2::px(drag.distance.x, drag.distance.y);
        }
    })
    .observe(|end: On<PointerDragEnd>, mut q: Query<&mut UiTransform>| {
        if let Ok(mut t) = q.get_mut(end.event_target()) {
            t.translation = Val2::ZERO;
        }
    });

Handle PointerDragDrop on the target to accept the drop. Raise the dragged node with GlobalZIndex so it draws over everything while it moves.

Let clicks pass through#

A node blocks the pointer from reaching what's under it, including the 3D world. For decorative overlays, add Pickable::IGNORE so the node is never hit. To be hit but still let things below be hovered too, use Pickable { should_block_lower: false, ..default() }.

Where the cursor is inside a node#

RelativeCursorPosition on a node holds normalized, the cursor's position inside the node from (0, 0) at the top-left to (1, 1) at the bottom-right, and cursor_over(). Use it for colour pickers and custom sliders.

Examples#

ExampleWhat it shows
buttonA styled Button that logs when clicked.
standard_widgets_observersRestyling widgets from observers instead of a polling system.
ui_drag_and_dropDragging nodes around a grid.
relative_cursor_positionRelativeCursorPosition.

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

Next steps#