# CollectionService

Roblox Engine API class from Roblox Studio 0.744.0.7441077 (version-7aaa6838d36c4448).

- Inherits from, nearest first: [Instance](https://rapi.sleaze.dev/classes/Instance.md), [Object](https://rapi.sleaze.dev/classes/Object.md)
- Tags: Not creatable, Service
- Memory category: Instances
- HTML page: https://rapi.sleaze.dev/classes/CollectionService/
- Roblox documentation: https://create.roblox.com/docs/reference/engine/classes/CollectionService

A service which manages instance collections using assigned tags.

## Methods

### AddTag

```luau
CollectionService:AddTag(instance: Instance, tag: string)
```

- Tags: Custom Lua state, Capabilities: Basic

Applies a tag to an [`Instance`](https://rapi.sleaze.dev/classes/Instance.md).

Parameters:

- `instance`: The [`Instance`](https://rapi.sleaze.dev/classes/Instance.md) to apply the tag to.
- `tag`: The tag string to apply to the instance.

### CreateCollection

```luau
CollectionService:CreateCollection(query: string, root: Instance? = nil): CollectionHandle
```

- Tags: Capabilities: Basic

Creates a `Collection` that tracks every instance matching a query.

Parameters:

- `query`: A selector string describing which instances to match. See the description for the supported syntax.
- `root`: The instance whose descendants are searched. Pass this to restrict the search to a subtree, such that instances outside that subtree never match and an instance is removed from the collection if it is reparented out of `root`. Defaults to [`Workspace`](https://rapi.sleaze.dev/classes/Workspace.md) when omitted.

Returns: A `Collection` that reactively tracks the instances matching `query`.

### GetAllTags

```luau
CollectionService:GetAllTags(): { any }
```

- Tags: Thread safe, Capabilities: Basic

Returns an array of all tags in the experience.

Returns: An array of all tags that currently have at least one tagged instance in the [`DataModel`](https://rapi.sleaze.dev/classes/DataModel.md).

### GetCollections

```luau
CollectionService:GetCollections(instance: Instance): { any }
```

- Tags: Capabilities: Basic

### GetInstanceAddedSignal

```luau
CollectionService:GetInstanceAddedSignal(tag: string): RBXScriptSignal
```

- Tags: Capabilities: Basic

Returns a signal that fires when a given tag is added to an instance.

Parameters:

- `tag`: The tag to watch for.

Returns: An event that fires when you add the tag to an instance.

### GetInstanceRemovedSignal

```luau
CollectionService:GetInstanceRemovedSignal(tag: string): RBXScriptSignal
```

- Tags: Capabilities: Basic

Returns a signal that fires when a given tag is removed from an instance.

Parameters:

- `tag`: The tag to watch for.

Returns: An event that fires when you remove the tag from an instance.

### GetTagAddedSignal

```luau
CollectionService:GetTagAddedSignal(instance: Instance): RBXScriptSignal
```

- Tags: Roblox script security, Capabilities: Basic

### GetTagged

```luau
CollectionService:GetTagged(tag: string): { Instance }
```

- Tags: Thread safe, Capabilities: Basic

Returns an array of instances in the game with a given tag.

Parameters:

- `tag`: The tag to search for.

Returns: An array of all instances with the tag.

### GetTagRemovedSignal

```luau
CollectionService:GetTagRemovedSignal(instance: Instance): RBXScriptSignal
```

- Tags: Roblox script security, Capabilities: Basic

### GetTags

```luau
CollectionService:GetTags(instance: Instance): { any }
```

- Tags: Custom Lua state, Thread safe, Capabilities: Basic

Gets an array of all tags applied to a given instance.

Parameters:

- `instance`: The instance whose tags should be returned.

Returns: An array of strings which are the tags applied to the given instance.

### HasTag

```luau
CollectionService:HasTag(instance: Instance, tag: string): boolean
```

- Tags: Custom Lua state, Thread safe, Capabilities: Basic

Check whether an instance has a given tag.

Parameters:

- `instance`: The instance to check for the presence of a tag.
- `tag`: The tag to check for.

Returns: Whether the instance has the tag.

### RemoveTag

```luau
CollectionService:RemoveTag(instance: Instance, tag: string)
```

- Tags: Custom Lua state, Capabilities: Basic

Removes a tag from an instance.

Parameters:

- `instance`: The instance to remove the tag from.
- `tag`: The tag to remove from the instance.

### GetCollection

```luau
CollectionService:GetCollection(class: string): { Instance }
```

- Tags: Deprecated, Capabilities: Basic
- Use instead: [`CollectionService.GetTagged`](https://rapi.sleaze.dev/classes/CollectionService.md)

**Deprecated:** This item has been superseded by a [`CollectionService`](https://rapi.sleaze.dev/classes/CollectionService.md) tagging method. The equivalent function using the new method is [`CollectionService:GetTagged()`](https://rapi.sleaze.dev/classes/CollectionService.md) which should be used in new work.

Returns all instances of a given class which are in the [`DataModel`](https://rapi.sleaze.dev/classes/DataModel.md).

Parameters:

- `class`: The class type to retrieve instances of.

Returns: An array of all instances of the specified class in the [`DataModel`](https://rapi.sleaze.dev/classes/DataModel.md).

## Events

### TagAdded

```luau
CollectionService.TagAdded: RBXScriptSignal<(tag: string)>
```

- Tags: Capabilities: Basic

Fires when a tag is added to an instance and the added tag is the only occurrence of that tag in the place.

### TagRemoved

```luau
CollectionService.TagRemoved: RBXScriptSignal<(tag: string)>
```

- Tags: Capabilities: Basic

Fires when a tag is removed from an instance and the removed tag is no longer used anywhere in the place.

### ItemAdded

```luau
CollectionService.ItemAdded: RBXScriptSignal<(instance: Instance)>
```

- Tags: Deprecated, Capabilities: Basic
- Use instead: [`CollectionService.GetInstanceAddedSignal`](https://rapi.sleaze.dev/classes/CollectionService.md)

**Deprecated:** This item has been superseded by a [`CollectionService`](https://rapi.sleaze.dev/classes/CollectionService.md) tagging method. There is currently no means of checking when a tag is added.

Fires when a [`Configuration`](https://rapi.sleaze.dev/classes/Configuration.md), [`CustomEvent`](https://rapi.sleaze.dev/classes/CustomEvent.md), [`CustomEventReceiver`](https://rapi.sleaze.dev/classes/CustomEventReceiver.md), [`Dialog`](https://rapi.sleaze.dev/classes/Dialog.md), or [`VehicleSeat`](https://rapi.sleaze.dev/classes/VehicleSeat.md) is added to the [`DataModel`](https://rapi.sleaze.dev/classes/DataModel.md).

### ItemRemoved

```luau
CollectionService.ItemRemoved: RBXScriptSignal<(instance: Instance)>
```

- Tags: Deprecated, Capabilities: Basic
- Use instead: [`CollectionService.GetInstanceRemovedSignal`](https://rapi.sleaze.dev/classes/CollectionService.md)

**Deprecated:** This item has been superseded by a [`CollectionService`](https://rapi.sleaze.dev/classes/CollectionService.md) tagging method. There is currently no means of checking when a tag is removed.

Fires when a [`Configuration`](https://rapi.sleaze.dev/classes/Configuration.md), [`CustomEvent`](https://rapi.sleaze.dev/classes/CustomEvent.md), [`CustomEventReceiver`](https://rapi.sleaze.dev/classes/CustomEventReceiver.md), [`Dialog`](https://rapi.sleaze.dev/classes/Dialog.md), or [`VehicleSeat`](https://rapi.sleaze.dev/classes/VehicleSeat.md) is removed from the [`DataModel`](https://rapi.sleaze.dev/classes/DataModel.md).

## Inherited members

- From [Instance](https://rapi.sleaze.dev/classes/Instance.md): `Archivable`, `archivable`, `Attributes`, `AttributesReplicate`, `AttributesSerialize`, `HistoryId`, `Name`, `Parent`, `PredictionMode`, `PropertyStatusStudio`, `RobloxLocked`, `SerializedOverrides`, `SourceAssetId`, `Tags`, `UniqueId`, `numExpectedDirectChildren`, `DataCost`, `Capabilities`, `DefinesCapabilities`, `IsInSandbox`, `Sandboxed`, `AddTag`, `ClearAllChildren`, `Clone`, `Destroy`, `FindFirstAncestor`, `FindFirstAncestorOfClass`, `FindFirstAncestorWhichIsA`, `FindFirstChild`, `FindFirstChildOfClass`, `FindFirstChildWhichIsA`, `FindFirstDescendant`, `GetActor`, `GetAttribute`, `GetAttributeChangedSignal`, `GetAttributes`, `GetChildren`, `GetDebugId`, `GetDescendants`, `GetFullName`, `GetStyled`, `GetStyledPropertyChangedSignal`, `GetTags`, `HasTag`, `IsAncestorOf`, `IsDescendantOf`, `IsPropertyModified`, `QueryDescendants`, `RemoveTag`, `ResetPropertyToDefault`, `SetAttribute`, `WaitForChild`, `Remove`, `children`, `clone`, `destroy`, `findFirstChild`, `getChildren`, `isDescendantOf`, `remove`, `AncestryChanged`, `AttributeChanged`, `ChildAdded`, `ChildRemoved`, `DescendantAdded`, `DescendantRemoving`, `Destroying`, `StyledPropertiesChanged`, `childAdded`
- From [Object](https://rapi.sleaze.dev/classes/Object.md): `ClassName`, `className`, `GetPropertyChangedSignal`, `IsA`, `isA`, `Changed`