A Container is returned by Handle.RegisterContainer(frame). It tracks child Instances by key and diffs them across renders — only inserting new children, reusing existing ones, and destroying any that were not touched during the current cycle.

Methods

UpsertChild(child) / UpsertChild(key, child)

Inserts a new child or returns the existing live Instance for that key. On re-renders the incoming clone is destroyed and the already-parented Instance is returned. Always write property updates to the returned value.

When called with one argument the key defaults to child.Name. When called with two arguments the first is the explicit key.

Example:

local list = Handle.RegisterContainer(element.ScrollFrame)

for i, entry in ipairs(data.entries) do
    local live = list.UpsertChild(entry.id, Assets.Row:Clone()) 
    live.Label.Text  = entry.name
    live.Score.Text  = tostring(entry.score)
    live.LayoutOrder = i
end

InsertChild(key, child)

Inserts a child only if the key does not already exist. Warns and returns the existing Instance if the key is taken. Use UpsertChild when you want upsert semantics.

Example:

local header = list.InsertChild("Header", Assets.SectionHeader:Clone())
header.Text = "Top Players"

GetChild(key)

Returns the tracked Instance for a key, or nil if not found.

Example:

local row = list.GetChild("player_123")
if row then
    row.Highlight.Visible = true
end

GetAllChildren()

Returns the full { [key]: Instance } map of all tracked children.

Example:

for key, child in pairs(list.GetAllChildren()) do
    child.Highlight.Visible = false
end

UpdateChild(key, fn)

Passes the live Instance for key to fn. Warns if the key is not found. Use this for one-off mutations outside the main loop.

Example:

list.UpdateChild("player_123", function(row)
    row.NameLabel.TextColor3 = Color3.new(1, 0.8, 0)
end)

DeleteChild(key)

Destroys the Instance for key and removes it from tracking.

Example:

list.DeleteChild("player_123")

ClearChildren()

Destroys every tracked child and resets the container to empty.

Example:

list.ClearChildren() -- Wipe the list before a full rebuild