17 min read

Source: Roblox Creator Hub · CC BY 4.0 · View source · Code samples: MIT Imported 2026-10-03. Formatting adapted for this site.

CollectionService

Inherits from: Instance → Object

CollectionService manages groups (collections) of instances with tags. Tags are sets of strings applied to instances that replicate from the server to the client. They are also serialized when places are saved.

The primary use of CollectionService is to register instances with specific tags that you can use to extend their behavior. If you find yourself adding the same script to many different instances, a script that uses CollectionService may be better.

Tags can be added or removed through this class' methods such as AddTag() or RemoveTag(). They can also be managed directly in Studio through the Tags section of an instance's properties.

Replication

When tags replicate, all tags on an instance replicate at the same time. Therefore, if you set a tag on an instance from the client then add/remove a different tag on the same instance from the server, the client's local tags on the instance are overwritten. In StreamingEnabled places, instances can be unloaded as they leave the client's streamed area. If such an instance re-enters the streamed area, properties and tags will be re-synchronized from the server. This can cause changes made by LocalScripts to be overwritten/removed.

Inherits from: Instance

Memory category: Instances

Tags: NotCreatable, Service

Methods

Inherited from Instance

Inherited from Object

CollectionService:AddTag

This method applies a tag to an Instance, doing nothing if the tag is already applied to that instance. Successfully adding a tag will fire a signal created by GetInstanceAddedSignal() with the given tag.

Warnings

• An instance's tags that were added client-side will be dropped if the server later adds or removes a tag on that instance because the server replicates all tags together and overwrites previous tags.

• When tagging an instance, it is common that some resources are used to give the tag its functionality, for example event connections or tables. To prevent memory leaks, it's a good idea to clean these up (disconnect, set to nil, etc.) when no longer needed for a tag. Do this when calling RemoveTag(), calling Instance:Destroy() or in a function connected to a signal returned by GetInstanceRemovedSignal().

Parameters

Returns

CollectionService:CreateCollection

This method creates a Collection, a live, query-based group of instances. Unlike tag-based methods such as GetTagged() which return a fixed array at the moment they are called, a Collection continuously tracks which instances match query and notifies you as instances enter and leave the result set.

The query string is a CSS-inspired selector that follows the same selector conventions used by QueryDescendants() and the StyleRule styling selectors. Filters stack conjunctively, combinators express hierarchy, and comma-separated selectors form a union:

• ClassName — Instances of that class (uses IsA()), for example Part or Model.
• #Name — Instances with a matching Name.
• .Tag — Instances carrying a CollectionService tag.
• [Property = value] — Instances whose property equals a value.
• [$Attribute] or [$Attribute = value] — Instances that have an attribute, optionally matching a value.
• A > B (direct child) and A >> B (any descendant) combinators.
• :has(...) and :not(...) pseudoclasses.

The rightmost selector in a chain identifies the matched instance, so Folder > Part tracks the parts, not the folders.

local CollectionService = game:GetService("CollectionService")

-- Track every Part tagged "KillBrick" anywhere under Workspace
local killBricks: Collection = CollectionService:CreateCollection("Part.KillBrick")

-- When a part joins the collection, make it glow red
-- OnAdded fires once for each part already matching, then again for each new match
function killBricks.OnAdded(brick: Part)
	brick.Material = Enum.Material.Neon
	brick.Color = Color3.new(1, 0, 0)
end

-- Kill any humanoid that touches a matched part
function killBricks.OnTouched(brick: Part, otherPart: BasePart)
	local character: Instance? = otherPart.Parent
	local humanoid = character and character:FindFirstChildOfClass("Humanoid")
	if humanoid then
		humanoid.Health = 0
	end
end

-- Fires when a part stops matching (tag removed, reparented out, or destroyed)
function killBricks.OnRemoved(brick: Part)
	print("Deactivating", brick:GetFullName())
end

Notes

• The collection remains active until you call Destroy() or its root is destroyed.
• Lifecycle callbacks are queued rather than invoked synchronously, so a newly assigned OnAdded may fire on a later resumption point rather than during the assignment itself.

Parameters

Returns

CollectionService:GetAllTags

Returns an array of all tags that currently have at least one tagged instance inside the DataModel. The returned array does not guarantee any particular ordering.

A tag appears in the result as soon as any instance bearing it enters the DataModel (for example by being parented to Workspace), and it is removed from the result once the last instance with that tag leaves the DataModel or has the tag removed. This means calling GetAllTags() immediately after removing the last instance with a given tag will no longer include that tag.

Returns

CollectionService:GetCollection

Deprecated. This item has been superseded by a CollectionService tagging method. The equivalent function using the new method is CollectionService:GetTagged() which should be used in new work.

This function returns all instances of a given class which are in the DataModel. Only works for Configuration, CustomEvent, CustomEventReceiver, Dialog, and VehicleSeat.

Parameters

Returns

Code samples: View on Creator Hub (CollectionService-GetCollection1).

CollectionService:GetInstanceAddedSignal

Given a tag (string), this method returns a signal which fires under two conditions:

• The tag is assigned to an instance within the DataModel using CollectionService:AddTag() or Instance:AddTag().

• An instance with the given tag is added as a descendant of the DataModel, for example by setting Instance.Parent or similar.

Subsequent calls to this method with the same tag return the same signal object. Consider also calling GetTagged() to get a list of instances that already have a tag (and thus won't fire the event if they already are in the DataModel).

See also GetInstanceRemovedSignal() which returns an event that fires under similar conditions.

Parameters

Returns

Code samples: View on Creator Hub (Deadly-Bricks-using-CollectionService).

CollectionService:GetInstanceRemovedSignal

Given a tag (string), this method returns a signal which fires under two conditions:

• The tag is removed from an instance within the DataModel using CollectionService:RemoveTag() or Instance:RemoveTag().

• An instance with the given tag is removed as a descendant of the DataModel, for example by un‑setting Instance.Parent or similar.

Subsequent calls to this method with the same tag return the same signal object. The signal is useful for cleaning up resources used by instances that once had tags, such as disconnecting connections.

See also GetInstanceAddedSignal() which returns an event that fires under similar conditions.

Parameters

Returns

Code samples: View on Creator Hub (Deadly-Bricks-using-CollectionService).

CollectionService:GetTagged

This method returns an array of instances with a given tag which are descendants of the DataModel. Removing a tag using CollectionService:RemoveTag() or Instance:RemoveTag() ensures this method does not return them.

If you want to detect all instances with a tag, both present and future, use this method to iterate over instances while also making a connection to a signal returned by GetInstanceAddedSignal().

This method does not guarantee any ordering of the returned instances. Additionally, it's possible that instances can have the given tag assigned to them but not be a descendant of the DataModel, for example its parent is nil; this method will not return such instances.

Parameters

Returns

Code samples: View on Creator Hub (Deadly-Bricks-using-CollectionService).

CollectionService:GetTags

Given an Instance, this method returns an array of strings which are the tags applied to the instance.

This method is useful when you want to do something with multiple instance tags at once, but it's inefficient to check for the existence of a single tag. For this, use HasTag() to check for a single tag.

Parameters

Returns

Code samples: View on Creator Hub (Using-Tags-and-CollectionService).

CollectionService:HasTag

This method returns whether a given Instance has a tag.

By extension, any tags returned by a call to GetTags() on an instance will return true when used with this method.

Parameters

Returns

Code samples: View on Creator Hub (Using-Tags-and-CollectionService).

CollectionService:RemoveTag

This method removes a tag from an instance. Successfully removing a tag will fire a signal created by GetInstanceRemovedSignal() with the given tag.

When removing a tag, it's common that some resources are used to give the tag its functionality, for example event connections or tables. To prevent memory leaks, it's a good idea to clean these up (disconnect, set to nil, etc.) when no longer needed for a tag.

Parameters

Returns

Code samples: View on Creator Hub (Using-Tags-and-CollectionService).

Events

Inherited from Instance

Inherited from Object

CollectionService.ItemAdded

Deprecated. This item has been superseded by a CollectionService tagging method. There is currently no means of checking when a tag is added.

This function fires when a Configuration, CustomEvent, CustomEventReceiver, Dialog, or VehicleSeat is added to the DataModel.

Parameters

Code samples: View on Creator Hub (CollectionService-ItemAdded1).

CollectionService.ItemRemoved

Deprecated. This item has been superseded by a CollectionService tagging method. There is currently no means of checking when a tag is removed.

This function fires when a Configuration, CustomEvent, CustomEventReceiver, Dialog, or VehicleSeat is removed from the DataModel.

Parameters

Code samples: View on Creator Hub (CollectionService-ItemRemoved1).

CollectionService.TagAdded

This event fires when a tag transitions from being unused to being in use — specifically, when a tag is applied to an instance inside the DataModel and no other instance in the DataModel previously had that tag. The event passes the tag name as its parameter.

TagAdded fires once per tag lifetime, not once per instance. To detect every individual instance that receives a particular tag, use GetInstanceAddedSignal() instead.

The event fires asynchronously (deferred to the next resumption point), not synchronously inside the AddTag() call that triggered it.

Parameters

CollectionService.TagRemoved

This event fires when the last instance bearing a given tag leaves the DataModel or has the tag removed, meaning no instance in the DataModel still carries that tag. The event passes the tag name as its parameter.

TagRemoved fires once per tag lifetime, not once per instance. To detect every individual instance that loses a particular tag, use GetInstanceRemovedSignal() instead.

The event fires asynchronously (deferred to the next resumption point), not synchronously inside the removal operation that triggered it.

Parameters

Properties

Inherited from Instance

Inherited from Object