# tag

```javascript
// Get all tags
const tags = await eagle.tag.get();

// Filter tags by name
const designTags = await eagle.tag.get({ name: "design" });

// Get recently used tags
const recents = await eagle.tag.getRecentTags();

// Get starred tags
const starred = await eagle.tag.getStarredTags();
```

## Methods <a href="#z1a5y" id="z1a5y"></a>

## get(options) <a href="#x9nu2" id="x9nu2"></a>

Retrieves tags with optional filtering.

* `options` Object (optional) - Query conditions
  * `name` string (optional) - Filter tags by name with fuzzy search, case-insensitive
* Returns `Promise<tags: Object[]>` - the query result for tags.

```javascript
// Get all tags
const tags = await eagle.tag.get();

// Filter tags by name
const filteredTags = await eagle.tag.get({
    name: "design"
});
```

{% hint style="info" %}
Note: The `name` parameter requires Eagle 4.0 build12 or higher.
{% endhint %}

***

## getRecentTags() <a href="#dwsxw" id="dwsxw"></a>

Retrieves the most recently used tags.

* Returns `Promise<tags: Object[]>` - the query result for tags.

```javascript
const recents = await eagle.tag.getRecentTags();
```

***

## getStarredTags() <a href="#starred" id="starred"></a>

Retrieves starred tags (user's favorite tags).

* Returns `Promise<tags: Object[]>` - the query result for tags.

```javascript
const starred = await eagle.tag.getStarredTags();
```

{% hint style="info" %}
Note: The `getStarredTags()` method requires Eagle 4.0 build18 or higher.
{% endhint %}

***

## merge(options) <a href="#merge" id="merge"></a>

Merges tags: renames the source tag to the target tag, automatically updating all items using the source tag.

* `options` Object - Option parameters
  * `source` string - Source tag name (will be removed)
  * `target` string - Target tag name (will be kept after merge)
* Returns `Promise<Object>` - Merge result
  * `affectedItems` number - Number of affected items
  * `sourceRemoved` boolean - Whether the source tag was removed

```javascript
// Merge all "UI Design" tags into "UI"
const result = await eagle.tag.merge({
    source: 'UI Design',
    target: 'UI'
});

console.log(`Merged tags for ${result.affectedItems} items`);
```

{% hint style="info" %}
Note: The `merge()` method requires Eagle 4.0 build18 or higher.
{% endhint %}

{% hint style="warning" %}
Warning: The merge operation updates all items, tag groups, starred tags, and history tags that use the source tag. This operation is irreversible.
{% endhint %}

***

## Class: Tag <a href="#tag-class" id="tag-class"></a>

Object type returned by Eagle API `get`, providing modification and save functionality.

{% hint style="success" %}
**🦄 Best Practice:** To ensure data security, use the `save()` method provided by the Tag instance to modify data. Avoid directly modifying tag data in the Eagle resource library.
{% endhint %}

***

### Instance Methods <a href="#instance-methods" id="instance-methods"></a>

#### **save()**

Save tag modifications. Currently only supports modifying tag names.

* Returns `Promise<result: boolean>` - `result` whether the modification was successful

```javascript
// Get all tags
const tags = await eagle.tag.get();

// Find the tag to modify
const tag = tags.find(t => t.name === 'old-name');

// Modify tag name
tag.name = 'new-name';

// Save changes
await tag.save();
```

{% hint style="info" %}
Note: The `save()` method requires Eagle 4.0 build12 or higher.
{% endhint %}

{% hint style="warning" %}
Warning: After modifying a tag name, all files using that tag will automatically be updated with the new tag name.
{% endhint %}

***

### Instance Properties <a href="#instance-properties" id="instance-properties"></a>

#### **`name` string**

Tag name. This property can be modified and saved through the `save()` method.

#### **`count` number**

Read-only, number of files using this tag.

#### **`color` string**

Tag color.

#### **`groups` string\[]**

Read-only, groups the tag belongs to.

#### **`pinyin` string**

Read-only, pinyin of tag name (for search and sorting).