# Tags

Class · extends [`EventHandler`](https://api.playcanvas.com/engine/classes/EventHandler.md) · category: Framework

Source: https://github.com/playcanvas/engine/blob/970d89f6d3bc6667f4e1f88153abd6e7e82ed52c/src/core/tags.js#L14

Tags is a powerful tag management system for categorizing and filtering objects in PlayCanvas
applications. It provides an efficient way to attach string identifiers to objects and query them
using logical operations.

Tags are automatically available on [Asset](https://api.playcanvas.com/engine/classes/Asset.md)s and [Entity](https://api.playcanvas.com/engine/classes/Entity.md)s (see [Asset#tags](https://api.playcanvas.com/engine/classes/Asset.md#tags)
and [GraphNode#tags](https://api.playcanvas.com/engine/classes/GraphNode.md#tags)). You can search for specific assets via [AssetRegistry#findByTag](https://api.playcanvas.com/engine/classes/AssetRegistry.md#findbytag)
and specific entities via [GraphNode#findByTag](https://api.playcanvas.com/engine/classes/GraphNode.md#findbytag).

## Constructors

### constructor

```ts
new Tags(parent?: any)
```

Create a new Tags instance.

**Parameters**

- `parent` (`any`, optional): Parent object who tags belong to.

## Accessors

### size

```ts
get size(): number
```

Number of tags in set.

## Methods

### add

```ts
add(...args: any[]): boolean
```

Add a tag, duplicates are ignored. Can be array or comma separated arguments for multiple tags.

**Parameters**

- `args` (`any[]`): Name of a tag, or array of tags.

**Returns** `boolean`: True if any tag were added.

**Example**

```ts
tags.add('level-1');
```

**Example**

```ts
tags.add('ui', 'settings');
```

**Example**

```ts
tags.add(['level-2', 'mob']);
```

### clear

```ts
clear(): void
```

Remove all tags.

**Example**

```ts
tags.clear();
```

### has

```ts
has(...query: any[]): boolean
```

Check if tags satisfy filters. Filters can be provided by simple name of tag, as well as by
array of tags. When an array is provided it will check if tags contain each tag within the
array. If any of comma separated argument is satisfied, then it will return true. Any number
of combinations are valid, and order is irrelevant.

**Parameters**

- `query` (`any[]`): Name of a tag or array of tags.

**Returns** `boolean`: True if filters are satisfied.

**Example**

```ts
tags.has('player'); // player
```

**Example**

```ts
tags.has('mob', 'player'); // player OR mob
```

**Example**

```ts
tags.has(['level-1', 'mob']); // monster AND level-1
```

**Example**

```ts
tags.has(['ui', 'settings'], ['ui', 'levels']); // (ui AND settings) OR (ui AND levels)
```

### list

```ts
list(): string[]
```

Returns immutable array of tags.

**Returns** `string[]`: Copy of tags array.

### remove

```ts
remove(...args: any[]): boolean
```

Remove tag.

**Parameters**

- `args` (`any[]`): Name of a tag or array of tags.

**Returns** `boolean`: True if any tag were removed.

**Example**

```ts
tags.remove('level-1');
```

**Example**

```ts
tags.remove('ui', 'settings');
```

**Example**

```ts
tags.remove(['level-2', 'mob']);
```

## Events

### EVENT_ADD

```ts
static EVENT_ADD: string = 'add'
```

Fired for each individual tag that is added.

**Example**

```ts
tags.on('add', (tag, parent) => {
   console.log(`${tag} added to ${parent.name}`);
});
```

### EVENT_CHANGE

```ts
static EVENT_CHANGE: string = 'change'
```

Fired when tags have been added or removed. It will fire once on bulk changes, while `add`
and `remove` will fire on each tag operation.

**Example**

```ts
tags.on('change', (parent) => {
   console.log(`Tags changed on ${parent.name}`);
});
```

### EVENT_REMOVE

```ts
static EVENT_REMOVE: string = 'remove'
```

Fired for each individual tag that is removed.

**Example**

```ts
tags.on('remove', (tag, parent) => {
  console.log(`${tag} removed from ${parent.name}`);
});
```

## Inherited from [EventHandler](https://api.playcanvas.com/engine/classes/EventHandler.md)

- `fire(name: string, arg1?: any, arg2?: any, arg3?: any, arg4?: any, arg5?: any, arg6?: any, arg7?: any, arg8?: any): EventHandler`
- `hasEvent(name: string): boolean`
- `off(name?: string, callback?: HandleEventCallback, scope?: any): EventHandler`
- `on(name: string, callback: HandleEventCallback, scope?: any): EventHandle`
- `once(name: string, callback: HandleEventCallback, scope?: any): EventHandle`