VirtualScroller | Documentation

Constructor

VirtualScroller.new(scrollingFrame, itemTemplate, dataTable, itemHeight, numColumns, itemWidthScale, bufferRows, applyDataFunction, itemSetupFunction, onItemShown, onItemHidden, onScrolled)

Creates a new VirtualScroller instance.

scrollingFrame: ScrollingFrame instance

itemTemplate: GuiObject template to clone

dataTable: Table of data to display

itemHeight: (Optional) UDim or number (pixels)

numColumns: (Optional) Number of columns (default: 1)

applyDataFunction: (Optional) Function(frame, dataItem, index)

Methods

VirtualScroller:GetVisibleItemCount()

Returns the number of items currently being rendered.

VirtualScroller:ReloadData(newDataTable)

Replaces the entire data source and refreshes the view.

VirtualScroller:SortData(comparatorFunction)

Sorts the current data table using standard table.sort and updates the view.

VirtualScroller:AddItem(dataItem, position)

Inserts a new item at the specific index (defaults to end) and updates the layout dynamically.

VirtualScroller:RemoveItem(index)

Removes the item at the specific index and shifts subsequent items.

VirtualScroller:ScrollToIndex(index, animated)

Scrolls the frame to show the specific item index.

VirtualScroller:Destroy()

Cleans up all connections and frame pools.

Example

local VirtualScroller = require(script.VirtualScroller)

-- Setup function called when a new frame is created
local function setupItem(frame)
    frame.BackgroundTransparency = 0.5
end

-- Apply function called when data is assigned to a frame
local function applyData(frame, data, index)
    frame.Title.Text = data.Name
end

local Scroller = VirtualScroller.new(
    Frame,          -- ScrollingFrame
    Template,       -- Item Template
    {},             -- Initial Data
    UDim.new(0, 50), -- Item Height
    1,              -- Columns
    1,              -- Width Scale
    15,             -- Buffer Rows
    applyData,      -- Apply Function
    setupItem       -- Setup Function
)