VeloScroll

This guide starts with installation and a five-minute Quick Start, explains how the recycler works, then walks each feature, the no-code editor tooling, and the full scripting API.

⤓ Installation

Import the package, make sure uGUI and the Input System are present, and add a component.

What gets installed

Assets/VeloScroll/
  Runtime/        // VeloScrollView, Recycler, CellPool, layouts, animator, data sources
  Editor/         // Custom inspector, scaffolding menus, Welcome window, project validator
  Demo/           // The interactive WebGL-ready demo scene (Build Index 0)
  Samples/        // Per-feature example scenes + the no-code template scene
  Documentation/  // You are here
  Tests/          // EditMode + PlayMode tests (run headless via Unity -runTests)Project

⚡ Quick Start

Your first recycling list in about five minutes — no code, then one optional line of script.

Option A — Add the component

Option B — Scaffold from the menu

Prefer a one-click setup? Use GameObject → UI → VeloScroll → Recycling List. It creates a Canvas and EventSystem only if the scene lacks them, drops in a pre-wired VeloScroll View, and registers full Undo. Press Play and it renders the sample. (There is a Recycling Grid variant too.)

Make it 10,000 items from code

One call turns the same view into a 10,000-row list bound to your own data. The recycler binds only the cells near the viewport, so the binder runs O(visible), never O(count):

using UnityEngine;
using VeloScroll;

public class QuickStart : MonoBehaviour
{
    [SerializeField] private VeloScrollView view;

    void Start()
    {
        // 10,000 items, a handful of live cells, no per-item instantiation while scrolling.
        view.SetData<VeloScrollTextCell>(10000, (i, c) => c.SetContent("Item " + i, ""));
    }
}

⚙ How It Works

Recycling (a.k.a. virtualization) in one idea: reuse a small, bounded pool of cells as the list scrolls.

A naive scroll list instantiates one cell GameObject per item, so a 10,000-row list creates 10,000 cells — slow to build and heavy on memory. VeloScroll instead keeps only the cells that are near the viewport alive. As a cell scrolls out one edge, it is returned to a pool and immediately reused to show the item appearing at the other edge. The count of live cells therefore stays roughly constant regardless of how many items the data has.

1. The driven ScrollRect's onValueChanged reports the new scroll offset.
2. The active layout (List or Grid) maps that offset to the range of item indices currently visible. For variable sizes a cumulative-offset cache is searched by binary search.
3. The recycler returns any now-off-screen cells to the cell pool and pulls cells back out for the items entering view.
4. The active data source binds each incoming cell (Bind(index, cell)) — only for the small visible set.
5. If an animation preset is set, the animator nudges each visible cell's scale/opacity by its distance from the viewport center.

Built by composition, not subclassing

VeloScroll drives a standard uGUI ScrollRect by composition; it never subclasses it. That means it coexists with any existing ScrollRect setup, and added to a bare GameObject it self-builds the viewport + content it needs. There is a blank-first-frame guard, too: because UI rects are 0×0 until a layout pass runs, the first build defers one frame until the viewport has a real size.

📋 Feature: Recycling List

A single-track recycled list, vertical or horizontal, with uniform cell sizes.

The default layout is a list: one column when scrolling vertically, one row when scrolling horizontally. Set the scroll Axis, the uniform Cell Main Size (height for vertical, width for horizontal), Spacing, inner Padding and an off-screen Buffer (extra cells kept alive just outside the viewport for smoother fast scrolling) in the Inspector.

// Switch back to a single-track list from code (e.g. after using a grid):
view.SetListLayout();

// Drive it from a typed binder. The default cell is VeloScrollTextCell.
view.SetData<VeloScrollTextCell>(10000, (i, c) => c.SetContent("Row " + i, "subtitle"));

▦ Feature: Grid

A fixed-count grid recycler — columns when scrolling vertically, rows when scrolling horizontally.

Switch the Layout Kind to Grid and set the Grid Cross Count (number of columns for a vertical scroll, or rows for a horizontal scroll) and the Grid Cross Spacing. The grid recycles exactly like the list — only the visible lines are alive.

// 3-column grid (vertical scroll), 6px between columns:
view.SetGridLayout(3, 6f);
view.SetData<VeloScrollTextCell>(5000, (i, c) => c.SetContent("Cell " + i, ""));

↕ Feature: Variable Cell Sizes

Per-cell heights (vertical) or widths (horizontal), with the live set still bounded.

Uniform cells are the fast default, but real lists often need rows of different sizes. Provide a size function and the list layout measures each item along the scroll axis, caches cumulative offsets, and finds the visible range by binary search — so even a non-uniform 10k-row list keeps a bounded live-cell set. Pass null to revert to uniform sizing.

// Alternating tall/short rows; the recycler stays bounded.
view.SetVariableSizes(i => (i % 2 == 0) ? 120f : 72f);
view.SetData<VeloScrollTextCell>(10000, (i, c) => c.SetContent("Item " + i, "variable height"));

✨ Feature: Animated Cells

Scroll-driven cell emphasis — the no-code "juice" layer, on a real virtualizer.

Pick an Animation Kind and the animator shapes each visible cell by its distance from the viewport center. The math is a pure, testable function of that distance, and writes only when a value changes (no per-frame allocation):

// Strength 0..1 controls how strongly edge cells shrink/fade; curve is optional.
view.SetAnimation(VeloScrollAnimationKind.FocusScale, 0.35f);

// Shape the falloff with an AnimationCurve (empty = linear):
view.SetAnimation(VeloScrollAnimationKind.Depth, 0.5f, myCurve);

🎯 Feature: Snapping / Paging

Snap to the nearest cell when a drag ends, and jump to any index instantly or with an animated scroll.

Enable Snapping and choose where the snapped cell lands in the viewport with Snap Align (Start, Center or End). When the user releases a drag, VeloScroll animates the content so the nearest cell settles at that alignment over the configured Snap Duration, using a smoothstep ease (or your own curve). Each settle raises the OnSnap event with the resolved item index.

// Turn on drag-end snapping, center-aligned, quarter-second ease.
view.SetSnapping(true, VeloScrollSnapAlign.Center, 0.25f);

// Get notified when a snap settles (drag-end or animated jump):
view.OnSnap += index => Debug.Log("Snapped to " + index);

// Jump to an item. animated:true performs an eased scroll and then fires OnSnap.
view.ScrollToIndex(500, VeloScrollSnapAlign.Center, animated: true);

🔄 Feature: Dynamic Data

Change the count or the contents at runtime — the list re-binds without an instantiation storm.

VeloScroll never stores your model; it asks the data source for a Count and binds cells on demand. When your data changes, call the matching operation and the recycler resizes the content and refreshes the window without rebuilding the world:

// A live count delegate keeps the list in sync with a growing/shrinking collection.
view.SetData<VeloScrollTextCell>(() => items.Count, (i, c) => c.SetContent(items[i].Title, ""));

items.Add(newItem);
view.Reload();          // content resized, window refreshed, correct re-bind, no NaN

🧱 Feature: Masonry / Staggered Grid

A Pinterest-style grid: fixed columns, but every cell has its own height, packed into the shortest column.

Where the regular Grid keeps a uniform cell size, the staggered grid takes a per-item main size and places each item into whichever column is currently shortest — the masonry look — while staying fully recycled and bounded.

// 3 columns, 6px cross spacing, each item's height from your model.
view.SetStaggeredGrid(3, 6f, i => 80f + items[i].ExtraHeight);
view.SetData<VeloScrollTextCell>(items.Count, (i, c) => c.SetContent(items[i].Title, ""));

📑 Feature: Sticky Section Headers

Grouped lists with a header per section that floats, pinned to the top, until the next header pushes it up.

Describe your list as sections — each one header followed by its rows — and VeloScroll flattens them into the recycler's index space. Headers and rows recycle through separate pools. With sticky on, the current section's header is mirrored into a floating overlay pinned to the viewport top, and the next section's incoming header shoves it out for a seamless hand-off.

// 40 sections, 12 rows each; 50px headers, 44px rows; sticky on.
view.SetSections(
    sectionCount: 40,
    rowsInSection: s => 12,
    headerSize: 50f, rowSize: 44f,
    bindHeader: (s, cell) => ((VeloScrollTextCell)cell).SetContent("Section " + s, ""),
    bindRow:    (s, r, cell) => ((VeloScrollTextCell)cell).SetContent("Row " + r, ""),
    sticky: true);

🔁 Feature: Looping & Auto-Scroll

Endless, seamless loops for pickers, carousels and tickers — optionally self-scrolling.

Looping repeats your data as one long, seamless run (the virtual extent is capped so scroll precision stays sub-pixel), wrapping each index back onto your real data. Pair it with auto-scroll for a hands-off marquee that wraps with no visible seam.

// A spinning value picker that wraps forever.
view.SetData<VeloScrollTextCell>(24, (i, c) => c.SetContent(hours[i], ""));
view.SetLooping(true);

// A news ticker: loop + continuous auto-scroll at 120 px/s.
view.SetLooping(true);
view.SetAutoScroll(120f);

⬇ Feature: Pull-to-Refresh & Load-More

The familiar mobile gesture: over-drag past an end to refresh or load the next page.

Enable it, set a threshold, and wire the events (in code or the Inspector). Over-pull past the start fires OnPullToRefresh; past the end fires OnLoadMore — perfect for infinite feeds.

view.SetPullToRefresh(true, thresholdPx: 90f);
view.OnPullToRefresh.AddListener(() => ReloadFromServer());
view.OnLoadMore.AddListener(() => AppendNextPage());

🧩 Feature: Multi-Prefab Cells

Mix different cell types in one list — ads between posts, dividers, rich vs plain rows — all bounded.

Register several cell prefabs plus a per-index type selector. Each type recycles through its own pool, so a heterogeneous list stays as bounded and allocation-free as a uniform one. The untyped binder casts each cell to the type it was handed.

// Two cell types alternating, 20,000 items, still a bounded handful of live cells.
view.SetMultiPrefabData(20000, new[] { postPrefab, adPrefab },
    typeOf: i => (i % 8 == 7) ? 1 : 0,   // every 8th row is an ad
    bind: (i, cell) => Populate(i, cell));

🎨 Feature: Themes & Animation Presets

Reusable ScriptableObject assets for look-and-feel — assign in the Inspector, no code required.

A Theme asset recolors the built-in text cells (background, title, subtitle) and drives spacing; it is applied on every bind through a zero-allocation hook. An Animation Preset asset bundles a scroll animation (kind + strength + curve) and overrides the inline settings. Create both from Assets › Create › VeloScroll, drop them on the component, or assign from code.

view.SetTheme(darkTheme);                 // recolors cells + spacing
view.SetAnimationPreset(focusPreset);      // overrides inline animation

📊 Feature: Table / Columns (frozen header)

A virtualized data grid: aligned columns, a header row that stays pinned at the top, thousands of rows recycled.

Describe your columns (a title + a pixel width; a width of 0 flexes to share the leftover space), give a row count and a string[] per row, and VeloScroll renders a table whose rows recycle like any list — bounded no matter how many rows. The header row is mirrored into a frozen overlay pinned to the top.

var columns = new[] {
    new VeloScrollColumn("ID", 80),
    new VeloScrollColumn("Name", 0),     // flex
    new VeloScrollColumn("Score", 100),
};
view.SetTable(columns, 10000, row => new[] { ""+row, data[row].Name, ""+data[row].Score });

⇅ Feature: Drag-to-Reorder

Drag a cell to a new position; on drop you move the data and the list reflects it.

Turn it on with a callback. Press-drag a cell and it lifts and follows the pointer; on release VeloScroll computes the drop index and raises onReorder(from, to) so you mutate your own list, then it reloads into the new order. Your data stays the single source of truth.

view.SetReorderable(true, (from, to) => {
    var item = list[from];
    list.RemoveAt(from);
    list.Insert(to, item);   // the view reloads to show the new order
});

🗂 Feature: Nested Scrolling

Horizontal lists inside a vertical list (a "shelf of shelves") that route drags correctly.

A plain uGUI ScrollRect swallows the whole drag, so a vertical swipe started on an inner horizontal list never reaches the outer one. Add VeloScrollNestedRouter to the inner scroll's GameObject: it forwards drags that belong to the parent — those orthogonal to the inner axis, or continuing past the inner's edge — to the nearest parent scroll, while the inner keeps handling its own axis.

// On each inner (e.g. horizontal) VeloScrollView's GameObject:
innerGo.AddComponent<VeloScrollNestedRouter>();   // auto-finds the parent scroll

📥 Feature: Import CSV / JSON

A universal file reader: turn a real CSV or JSON payload into a list or a table, and let the user choose which columns to show.

Pass raw text to VeloScrollImport and it returns a VeloScrollTabularData — the discovered columns plus the rows. It is deliberately forgiving: it strips byte-order marks, sniffs the CSV delimiter (comma / semicolon / tab / pipe), honours RFC-4180 quoting (quoted commas, embedded newlines, doubled "" escapes) and pads ragged rows; for JSON it locates the record array (top-level, a wrapper property, or a single object), unions every record's keys into the schema and flattens nested objects into dotted columns (address.city). It is pure C# and culture-invariant, so it runs in players too — not just the editor.

Every column starts included; toggle any of them and the projection (IncludedHeader() / IncludedRow(i)) collapses to just the chosen columns — the data is never mutated, so you can re-include later. Then drive the view with the ApplyAsTable / ApplyAsList extensions.

var data = VeloScrollImport.FromCsv(csvText);   // or .FromJson(json) / .Auto(text) / .FromFile(path)

data.SetIncluded("internal_id", false);     // the user excludes a column they don't want

view.ApplyAsTable(data);                   // virtualized table of the included columns…
view.ApplyAsList(data);                    // …or a list: first column as title, the rest as subtitle

Let the user pick a real file at runtime. VeloScrollFilePicker opens the platform file dialog and hands back the chosen file's text. In a WebGL build it opens the browser's native file picker (via a bundled .jslib — System.IO cannot read a user-selected file in WebGL); in the editor it shows an open-file panel, so the same button works while you iterate. Combine it with Auto (which sniffs CSV vs JSON) for a complete "import my data" button:

VeloScrollFilePicker.Open(".csv,.json,.txt", (name, text) => {
    var data = VeloScrollImport.Auto(text);   // CSV vs JSON auto-detected from the contents
    view.ApplyAsTable(data);
});

🔧 Editor Tools / No-Code

VeloScroll is built to be used without writing a line of code. The component, its custom inspector, the scaffolding menus, the data-source asset and the Welcome window cover the whole authoring loop.

1. The component & custom inspector

The VeloScroll View component exposes every option as a serialized field with sensible defaults, so it "just works" unconfigured. Its custom inspector groups the fields and shows only the knobs that apply:

• Setup: Axis, Layout Kind, Cell Main Size, Spacing, Padding, Buffer. Grid Cross Count / Cross Spacing appear only when Layout Kind is Grid.
• Data: a Data Source Mode selector (Sample / Asset / Code), a Data Source Asset slot (shown in Asset mode, with a helpful hint when empty), the Sample Count (in Sample mode), and an optional Cell Prefab.
• Animation: Animation Kind, with Strength and Curve appearing only when a kind other than None is chosen.
• Behaviour: the Build On Start toggle.
• Preview: a manual Rebuild Preview button in edit mode, and live Items / Live cells / Created stats while playing.

2. GameObject scaffolding menus

Two one-click entry points create a ready-to-play view, adding a Canvas and an EventSystem only if the scene lacks them (so running an item twice never litters the hierarchy), wiring the EventSystem for the new Input System, and registering full Undo with the new object selected and pinged:

• GameObject → UI → VeloScroll → Recycling List
• GameObject → UI → VeloScroll → Recycling Grid

3. The VeloScrollDataSource asset

For a fully no-code list, create a data asset via Assets → Create → VeloScroll → Data Source (or the CreateAssetMenu entry). Each row is a small struct — Title, Subtitle, Tint — authored in the Inspector or generated with a deterministic Generate button. Set the component's Data Source Mode to Asset, drop the asset in the slot, and press Play: it renders the asset's rows with no scripting. A ready-made sample data asset ships under Assets/VeloScroll/Samples/ for you to duplicate.

4. Precedence: "just works" vs "code wins"

On Play, the gated auto-build resolves data in this order:

So a code-set data source is never overwritten by the auto-build, and a truly unconfigured component is never blank.

5. The Welcome window

On first load, a one-screen Welcome window orients you: a 3-step getting-started, a Create your first Recycling List button (which reuses the exact scaffolding the menu uses), an Open Documentation button, and a "don't show again" toggle. It is available any time under Window → VeloScroll → Welcome.

Sample scenes

Generate per-feature example scenes from Tools → VeloScroll → Generate Sample Scenes. Each one isolates a single feature: the recycling list, grid, masonry, variable sizes, sticky sections, animation, snapping, looping + marquee, pull-to-refresh, multi-prefab, table, drag-to-reorder, nested scrolling, dynamic data, CSV / JSON import, and a fully no-code template (a VeloScrollView in Asset mode bound to a VeloScrollDataSource). Open any one, press Play, and see exactly that feature. The interactive demo scene showcases all of them together with live controls.

📙 Scripting API

The public surface of VeloScroll.VeloScrollView and its supporting types. Namespace: VeloScroll.

Getting a reference and setting data

using UnityEngine;
using VeloScroll;

var view = GetComponent<VeloScrollView>();

// Count + typed binder (the default cell type is VeloScrollTextCell):
view.SetData<VeloScrollTextCell>(10000, (i, c) => c.SetContent("Item " + i, ""));

// Live-count delegate for dynamic collections:
view.SetData<VeloScrollTextCell>(() => model.Count, (i, c) => c.SetContent(model[i].Name, ""));

// Full control: implement IVeloScrollDataSource and assign it.
view.SetDataSource(myDataSource);

Methods

Importing data (CSV / JSON)

Properties & events

Supporting types

Custom cells

public class MyCell : VeloScrollCell
{
    public override void OnBind(int index)
    {
        base.OnBind(index);     // records Index; recycler treats this as "show item N now"
        // ... populate your visuals from your model[index] ...
    }

    public override void OnRecycle()
    {
        base.OnRecycle();         // resets scale/alpha so a reused cell carries no stale state
        // ... release any per-item state ...
    }
}

🖥 Compatibility

Where VeloScroll runs, and what it was verified against.

💡 Troubleshooting

The issues that come up most, and how to fix them.

❓ FAQ

Quick answers to the questions that come up most.

📬 Support

Need help? We're here for you.