Scrolling and overflow
Clip UI content that doesn't fit, make nodes scroll with ScrollPosition, scroll with the mouse wheel through ScrollArea, add scrollbars, and keep headers fixed.
On this page
When a node's children are bigger than the node, Node::overflow decides what happens: they spill out (the default), get clipped, or scroll. Scrolling is how you build long lists, chat logs, inventories and settings pages.
Overflow#
overflow is an Overflow { x, y }, one OverflowAxis per axis:
OverflowAxis | What happens to content that doesn't fit |
|---|---|
Visible | It's drawn outside the node. The default. |
Clip | It's cut off at the node's edge. |
Hidden | Like Clip, but layout also treats the node as a scroll container, so it can't be stretched by its content. |
Scroll | It's clipped, and the node can be scrolled. |
Shortcuts: Overflow::visible(), clip(), clip_x(), clip_y(), hidden(), hidden_x(), hidden_y(), scroll(), scroll_x() and scroll_y().
OverflowClipMargin sets where clipping starts: the content box, the padding box or the border box, plus a margin. The overflow_clip_margin example shows the difference.
Scroll position#
A scrolling node has a ScrollPosition(Vec2): how far its content is moved, in logical pixels. Write it to scroll from code; the layout clamps it to the content's size.
fn scroll_to_top(mut lists: Query<&mut ScrollPosition, With<ChatLog>>) {
for mut position in &mut lists {
position.y = 0.0;
}
}ComputedNode::content_size() and size() (times inverse_scale_factor() for logical pixels) tell you how far there is to scroll.
Scroll with the mouse wheel#
Add ScrollArea (from neo::ui_widgets) to a node with Scroll overflow, and the wheel and trackpad scroll it while the pointer is over it. Nested scroll areas work: the innermost one under the pointer scrolls.
use neo::{prelude::*, ui_widgets::ScrollArea};
fn spawn_list(mut commands: Commands) {
commands
.spawn((
Node {
flex_direction: FlexDirection::Column,
width: px(240),
height: px(300),
overflow: Overflow::scroll_y(),
..default()
},
ScrollArea,
BackgroundColor(Color::srgb(0.1, 0.1, 0.12)),
))
.with_children(|list| {
for i in 0..50 {
list.spawn((Text::new(format!("Item {i}")), Node { min_height: px(24), ..default() }));
}
});
}For other scroll input, such as a gamepad stick or drag-to-scroll on touch screens, update ScrollPosition yourself. The scroll example routes wheel events into a custom bubbling event, and drag_to_scroll scrolls by dragging.
Scrollbars#
Scrollbar is a headless widget that scrolls a target node when dragged. Spawn it next to the scroll area, set its target and orientation, and give it a child with ScrollbarThumb; the widget sizes and moves the thumb for you.
use neo::ui_widgets::{ControlOrientation, Scrollbar, ScrollbarThumb};
commands.spawn((
Node { min_width: px(8), ..default() },
Scrollbar { orientation: ControlOrientation::Vertical, target: list_entity, min_thumb_length: 8.0 },
children![(
ScrollbarThumb { border_radius: BorderRadius::all(px(4)), ..default() },
BackgroundColor(Color::srgb(0.4, 0.4, 0.45)),
)],
));A grid with the scroll area in one cell and the scrollbars in the next row and column is the usual layout; the scrollbars example builds one. Node::scrollbar_width reserves space for a scrollbar inside the scrolling node instead.
Keep part of the content fixed#
IgnoreScroll(BVec2) on a child stops its parent's scroll from moving it on the chosen axes, which keeps a header row or first column in place while the rest scrolls.
Bring an item into view#
Trigger ScrollIntoView { entity } on an item to scroll its parent until the item is visible. The list box and tree widgets do this as you move through them with the keyboard.
Examples#
| Example | What it shows |
|---|---|
scroll | Vertical, horizontal, two-way, nested and sticky scrolling lists. |
scrollbars | A scroll area with both scrollbars. |
drag_to_scroll | Scrolling by dragging. |
overflow | Visible, clipped and hidden overflow. |
overflow_clip_margin | OverflowClipMargin. |
overflow_transform | Clipping with rotated and scaled nodes. |
Run one from the engine core's workspace: cargo run --example scroll.