NEOLearn

Widgets

The engine's headless UI widgets: buttons, checkboxes, radio groups, sliders, text inputs, menus, list boxes, tabs, trees, dialogs, popovers and scrollbars, and how their state works.

Updated October 20, 2026

On this page

neo_ui_widgets provides the behaviour of common controls: what happens on click, drag and key press, keyboard focus and accessibility information. The widgets are headless: they have no look of their own. You build each one from ordinary nodes and style it with the components on Images and styling, so a widget can look like anything your game needs.

The widgets are on in NEO's builds, and DefaultPlugins registers all of them (UiWidgetsPlugins). Import them from neo::ui_widgets.

The widgets#

WidgetMain componentsReports
ButtonButton, optional ActivateOnPressActivate
Checkbox or toggleCheckbox, Checked (from neo::ui)ValueChange<bool>
Radio groupRadioGroup with RadioButton childrenValueChange<Entity>: the chosen button
SliderSlider, SliderValue, SliderRange, optional SliderStep and SliderPrecision; a child with SliderThumbValueChange<f32>
Text inputTextInput with EditableText; see UI textEdits itself
MenuMenuButton, MenuPopup, MenuItemMenuEvent
List boxListBox, ListItem, optional ListBoxMultiSelectValueChange<Entity>: the chosen row
TabsTabList with Tab children, SelectedTabValueChange<Option<Entity>>: the chosen tab
Tree viewTreeView, TreeItemSelection and expand events
DialogDialog, optional ModalDialog to trap focus, DialogDragHandleRequestClose
PopoverPopoverPositions itself next to its parent, staying on screen
ScrollbarScrollbar, a child with ScrollbarThumbScrolls its target; see Scrolling and overflow

Every widget is focusable and works with Tab and directional navigation. InteractionDisabled (from neo::ui) disables any of them.

How widget state works#

Most widgets don't change their own state. A checkbox doesn't tick itself when clicked: it reports a ValueChange<bool> with the proposed value, and your code decides what happens. That's because UI in games usually shows live game data. A volume slider should show the volume setting, and when the setting changes from somewhere else, the slider should follow.

So the pattern is:

  1. The widget's state lives in a component: Checked, SliderValue, SelectedTab.
  2. When the player interacts, the widget triggers ValueChange<T> on itself, with value and is_final (false while a slider is still being dragged).
  3. Your observer updates your game state and writes the new state component back to the widget.
A volume slider bound to a setting
use neo::{
    prelude::*,
    ui_widgets::{observe, Slider, SliderRange, SliderThumb, SliderValue, ValueChange},
};

#[derive(Resource)]
struct Volume(f32);

fn volume_slider(volume: f32) -> impl Bundle {
    (
        Node { width: px(200), height: px(12), ..default() },
        Slider::default(),
        SliderValue(volume),
        SliderRange::new(0.0, 1.0),
        observe(|change: On<ValueChange<f32>>, mut volume: ResMut<Volume>, mut commands: Commands| {
            volume.0 = change.value;
            commands.entity(change.source).insert(SliderValue(change.value));
        }),
        children![(
            SliderThumb,
            Node { position_type: PositionType::Absolute, width: px(12), height: px(12), ..default() },
            BackgroundColor(Color::WHITE),
        )],
    )
}

The slider doesn't move its thumb: a system of yours sets the thumb's left from SliderValue and SliderRange (filter on Changed<SliderValue>). The standard_widgets example has a complete slider, including how to account for the thumb's width.

If you don't need that control, add the matching self-update observer and the widget keeps its own state: checkbox_self_update, radio_self_update, slider_self_update, tablist_self_update and tree_view_self_update.

Rust
commands.spawn((
    Checkbox,
    Node { width: px(20), height: px(20), border: px(2).all(), ..default() },
    BorderColor::all(Color::WHITE),
    observe(checkbox_self_update),
));

A few widgets work differently: buttons and menu items have no state and trigger Activate (or MenuEvent) instead; text inputs edit their own text, since it's large; and scrollbars write the target's ScrollPosition directly.

To set a value from code, insert the state component (SliderValue(0.5)), or trigger the widget's set event, such as SetSliderValue or SetChecked, which is handy for gamepad controls.

Style by state#

Read the state components in a system and pick a look, or observe their insertion and removal (On<Insert, Checked>, On<Remove, Checked>). Useful state components:

ComponentMeaning
Hovered (neo::picking::hover)The pointer is over it. Add Hovered::default() to track it.
PressedIt's held down.
CheckedA checkbox, radio button or toggle is on.
Selected, ExpandedList, tab and tree item state.
InteractionDisabledIt's disabled.
SliderDragStateA slider is being dragged.

Writing your own widgets#

A widget is components plus observers. Follow the same conventions so yours mix with the built-in ones: keep state in a component, trigger ValueChange<T> instead of changing it, add Focusable, and stop the propagation of events your widget handles (event.propagate(false)) while letting others bubble.

Styled widgets#

The engine core also has neo_feathers, a styled widget set built on these widgets and used by several engine examples (feathers_gallery, feathers_counter). It needs the neo_feathers cargo feature, which isn't on in NEO's default builds.

Examples#

ExampleWhat it shows
buttonOne styled button.
standard_widgetsButton, slider, checkbox, radio group and menu, with state in a resource.
standard_widgets_observersThe same, styled from observers.
vertical_sliderHorizontal and vertical sliders that snap to steps.
headless_tabs, headless_treeTabs and a tree view.
scrollbarsScrollbars on a scroll area.

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

Next steps#