docs › panels & media › api reference › virtual reference

virtual reference¶

A virtualized scrollable viewport over the engine's BaseVirtualPanel: only visible rows exist as panels. Rows are built as Goo blobs via Row; stateful nodes inside a row (e.g. TextEntry editors) should carry a per-item Key so a recycled panel never inherits another item's private engine state. Give it a bounded size on the scroll axis.

example¶

var players = new List<string> { "gordon", "alyx", "barney" };
var roster = Virtual.List(players, itemHeight: 32,
    row: name => new Container
    {
        Padding = 8,
        Children = { new Text(name) },
    });

structural properties¶

property	type	notes
Items	IReadOnlyList	The backing items. Pass the same list reference across rebuilds; a new reference or a count change triggers a refresh (content changes in a new list are diffed per row engine-side).
Row	RowBuilder?	Builds the Blob for one item. Runs when the row scrolls into view or its item changes.
ItemHeight	float	Fixed row height for list mode. Ignored when `ItemSize` or `Panel` is set.
ItemSize	Vector2	Fixed cell size for grid mode (y > 0 selects the fiber-backed grid over the list panel).

layout¶

property	type	notes
FlexBasis	Length?	Initial main-axis size of a flex child before grow and shrink are applied.
FlexGrow	float?	Share of leftover main-axis space this child claims; 0 (default) means do not grow.
FlexShrink	float?	How readily this child shrinks when space is tight; 0 pins it to its basis.
Position	PositionMode?	Positioning scheme: Relative offsets from the normal slot, Absolute lifts the box out of flow against the nearest positioned ancestor.

position offsets¶

property	type	notes
Bottom	Length?	Bottom-edge offset; applied only when Position is Relative or Absolute.
Left	Length?	Left-edge offset; applied only when Position is Relative or Absolute.
Right	Length?	Right-edge offset; applied only when Position is Relative or Absolute.
Top	Length?	Top-edge offset; applied only when Position is Relative or Absolute.

sizing¶

property	type	notes
Width	Length?	Width of the box (Length: px, %, em, rem, ...).
Height	Length?	Height of the box.
MaxHeight	Length?	Upper bound on height.
MaxWidth	Length?	Upper bound on width; the box never grows past it.
MinHeight	Length?	Lower bound on height.
MinWidth	Length?	Lower bound on width; the box never shrinks below it.

spacing¶

property	type	notes
Margin	Length?	Outer space on all four edges, between this box and its neighbors.
MarginLeft	Length?	Outer space on the left edge.
MarginTop	Length?	Outer space on the top edge.
MarginRight	Length?	Outer space on the right edge.
MarginBottom	Length?	Outer space on the bottom edge.
Gap	Length?	Space between flex children on both axes (shorthand for RowGap and ColumnGap).
RowGap	Length?	Vertical space between flex rows.
ColumnGap	Length?	Horizontal space between flex columns.

background¶

property	type	notes
BackgroundColor	Color?	Fill color behind the content.
BackgroundTint	Color?	Multiplies the background image color; default white (no tint).

border radius¶

property	type	notes
BorderRadius	Length?	Rounds all four corners.
BorderTopLeftRadius	Length?	Rounds the top-left corner.
BorderTopRightRadius	Length?	Rounds the top-right corner.
BorderBottomRightRadius	Length?	Rounds the bottom-right corner.
BorderBottomLeftRadius	Length?	Rounds the bottom-left corner.

effects¶

property	type	notes
Opacity	float?	Overall opacity from 0 (transparent) to 1 (opaque).

transform¶

property	type	notes
Transform	Goo.PanelTransform?	Translate, rotate, scale, and skew applied to the rendered box.

misc¶

property	type	notes
PointerEvents	PointerEvents?	Whether the element receives pointer input (All or None).

events and key¶

property	type	notes
Panel	Func?	Escape hatch: supply any BaseVirtualPanel subclass for a custom layout strategy. Create-only.
OnLastRow	Action?	Called when the last item materializes - the infinite-scroll load-more hook.
Key	string?	Stable identity across rebuilds. Set it when this blob can change position among its siblings, so the reconciler matches it to the same panel.