VirtualScroller Module Documentation

Links

• Module Link: Link to the Module Script on Roblox
• Example Place: Link to Example Place
• Devforum Post: Link to Post

Introduction

The VirtualScroller is a Roblox Lua module designed for efficient scrolling through large datasets in a UI ScrollingFrame. It uses virtualization to only render items that are currently visible (plus a buffer), reducing performance overhead. Ideal for lists, grids, or inventories with thousands of items.

Key features:

• Single or multi-column support.
• Item pooling and recycling.
• Custom callbacks for data application and events.
• Methods for data management and scrolling.
• Handles resizing and scrolling automatically.

Installation

To install, insert the module script into your Roblox project (e.g., in ReplicatedStorage) and require it in your scripts.

1. Get the ModuleScript Model from Roblox.
2. Place it in an appropriate location, like ReplicatedStorage.
3. In your script: local VirtualScroller = require(ReplicatedStorage.VirtualScroller)
4. Use in any localscript.

Usage

Create a new instance with required parameters. Example:

local VirtualScroller = require(ReplicatedStorage.VirtualScroller)

-- Setup
local scrollingFrame = script.Parent.ScrollingFrame
local itemTemplate = scrollingFrame.ItemTemplate
local data = {}  -- e.g., {{Name = "Item1"}, {Name = "Item2"}}

local scroller = VirtualScroller.new(
    scrollingFrame,
    itemTemplate,
    data,
    50,  -- itemHeight
    2,   -- numColumns
    0.5, -- itemWidthScale
    15,  -- bufferRows
    function(frame, data, index)
        frame.NameLabel.Text = data.Name or "Item " .. index
    end
)

The scroller handles rendering and updates automatically.

Constructor: VirtualScroller.new()

Creates a new instance. Parameters after dataTable are optional.

• scrollingFrame (Instance): The ScrollingFrame.
• itemTemplate (Instance): Template Frame (invisible).
• dataTable (table): Data array.
• itemHeight (number | UDim): Item height (default UDim.new(0.1, 0)).
• numColumns (number): Columns (default 1).
• itemWidthScale (number): Width scale (default 1/numColumns).
• bufferRows (number): Buffer rows (default 15).
• applyDataFunction (function): Apply data callback.
• itemSetupFunction (function): Setup frame callback.
• onItemShown (function): Shown callback.
• onItemHidden (function): Hidden callback.
• onScrolled (function): Scrolled callback.

Returns the instance.

Methods

GetVisibleItemCount()

Returns visible items count.

local count = scroller:GetVisibleItemCount()

ReloadData(newDataTable)

Reloads full data and updates view. (Useful for Inventory Page Changes without multiple ScrollingFrames.)

scroller:ReloadData(newData)

ScrollToIndex(index, animated)

Scrolls to index, optionally animated.

scroller:ScrollToIndex(10, true)

SortData(comparatorFunction)

Sorts data and updates the Scrollingframe.

scroller:SortData(function(a, b) return a.Name < b.Name end)

AddItem(dataItem, position)

Adds item.

scroller:AddItem({Name = "New Item", Id = "?"})

RemoveItem(index)

Removes item at index.

scroller:RemoveItem(3)

Destroy()

Cleans up resources.

scroller:Destroy()

Notes

• Enable ClipsDescendants on itemTemplate if needed.
• Performance optimized for large datasets.
• Use callbacks for advanced features like image / viewport loading.