Pager

Pager retains page state and animates between pages. The selected index belongs to the application, so tabs, buttons, and gestures can share one value.

#include <huxerui/huxerui.h>

#include <cstddef>

using namespace huxerui;

[[huxerui::composable]]
View Walkthrough() {
  auto selected = UseState<std::size_t>(0);
  return Pager({Text("Welcome"), Text("Create a project"), Text("Start building")}, selected)
      .OnChanged([selected](std::size_t next) { selected = next; })
      .With(Frame{.height = 240.0F});
}

Selection and gestures

Pager(pages, selected) accepts an initializer list or vector and a plain or State-held index. Supply a nonempty page list and a valid index.

A completed drag proposes an adjacent page through OnChanged(std::size_t); accept it by writing back. Programmatic index changes animate but do not emit another change event. This prevents tab-to-pager feedback loops.

Configuration

• .ScrollAxis(Axis::Horizontal | Axis::Vertical) chooses orientation.
• .Reverse(bool) reverses the physical direction.
• .DragEnabled(bool) allows programmatic-only switching.
• Reduced-motion policy is respected by the shared transition behavior.

Give the pager useful bounded space, especially inside scrolling layouts. Retained offscreen pages preserve local state and are not automatically torn down.

Use IndexedPages for instant non-swipe switching. Use Tabs as a visible selector, sharing the same controlled index. Read the Pager example source.

Defaults and state ownership

Default orientation is Horizontal, Reverse is false, and direct dragging is enabled. Reverse(true) inverts the natural resolved direction, including horizontal layout direction. DragEnabled(false) prevents direct pointer paging while leaving programmatic selection and accessibility actions available; it is not equivalent to disabling the whole subtree.

OnChanged(void(std::size_t)) proposes one adjacent index after an accepted direct gesture. Keep page count and selected index consistent in the same recomposition. If the owner rejects a proposal, the controlled index remains authoritative. Assigning a distant index programmatically uses the built-in transition without synthesizing intermediate OnChanged events.

Pager retains peer pages, so local edit state can survive paging and background work can remain alive. It has no per-page lazy-load callback, route history, or exposed PagerStyle. A screen-sized pager should normally occupy a bounded content region; a nested vertical page scroller can then own that page’s content scrolling.

Settled pages

OnSettled(std::size_t) reports the displayed index after paging or rebound and the final layout settle. It also covers programmatic transitions and can repeat an index; initial mount and stationary recomposition do not emit it.

Use OnChanged for controlled selection and OnSettled for work that needs a settled visible page. Do not feed Settled back into selection merely to synchronize Tabs: they should already share the same State. The event is a layout/motion observation, not proof that async content on that page finished loading.