@@ -35,6 +35,33 @@ All props accepted by `VStack` and `HStack`:
3535 }
3636 ```
3737
38+## Scroll
39+
40+Scroll supports **uncontrolled** (default) and **controlled** modes, mirroring the focus model:
41+
42+```ts
43+// Uncontrolled β framework manages scroll position. Mouse wheel just works.
44+VStack({ overflow: "scroll", scrollbar: true }, [...items]);
45+
46+// Controlled β app owns scroll state.
47+VStack(
48+ {
49+ overflow: "scroll",
50+ scrollbar: true,
51+ scrollOffset: offset,
52+ onScroll: (newOffset) => {
53+ offset = newOffset;
54+ cel.render();
55+ },
56+ },
57+ [...items],
58+);
59+```
60+
61+- Scroll direction follows the containerβs main axis: VStack β vertical, HStack β horizontal.
62+- Scroll is pointer-driven (mouse wheel), not focus-driven. A user can type in a focused widget while scrolling a different container.
63+- In controlled mode, the UI only moves when the app passes the updated `scrollOffset` back. `onScroll` fires with the clamped new offset.
64+
3865 ## Text Props
3966
4067 ```ts