# Add and remove watchlist subjects

Once users have created a watchlist and displayed it in a grid, they will want to add and remove subjects from it. The Watchlist API provides methods for inserting, appending and removing subjects from a watchlist.

## Prerequisites

Please ensure that your installation meets the requirements and configuration outlined in [Watchlist API prerequisites](watchlist-api-prerequisites.md).

## Adding and removing watchlist subjects

The [Watchlist,opts="nofollow"](https://docs.caplin.com/developer/api/caplin_trader/4/module-caplin_watchlist_Watchlist) object manages the subscription to its server-side container on Transformer. In order to make the most efficient use of [StreamLink](../../../caplin-platform/streamlink/index.md) resources, the subscription is only active when there are parties interested in the watchlist’s content. The [Watchlist,opts="nofollow"](https://docs.caplin.com/developer/api/caplin_trader/4/module-caplin_watchlist_Watchlist) class tracks the number of interested parties by forcing all operations on a watchlist’s content to occur through instances of a second class: [WatchlistContentsManager,opts="nofollow"](https://docs.caplin.com/developer/api/caplin_trader/4/module-caplin_watchlist_WatchlistContentsManager). A party signals its interest in the watchlist’s contents by requesting a [WatchlistContentsManager,opts="nofollow"](https://docs.caplin.com/developer/api/caplin_trader/4/module-caplin_watchlist_WatchlistContentsManager) object, and signals the termination of its interest by destroying the [WatchlistContentsManager,opts="nofollow"](https://docs.caplin.com/developer/api/caplin_trader/4/module-caplin_watchlist_WatchlistContentsManager) object. While at least one active [WatchlistContentsManager,opts="nofollow"](https://docs.caplin.com/developer/api/caplin_trader/4/module-caplin_watchlist_WatchlistContentsManager) object exists, the watchlist will maintain its subscription.

To acquire a contents manager for a particular watchlist, call [Watchlist.getContentsManager,opts="nofollow"](https://docs.caplin.com/developer/api/caplin_trader/4/module-caplin_watchlist_Watchlist#getContentsManager):

```js
var watchlistContentsManager = watchlist.getContentsManager();
```

When you no longer need the contents manager, call [WatchlistContentsManager.destroy,opts="nofollow"](https://docs.caplin.com/developer/api/caplin_trader/4/module-caplin_watchlist_WatchlistContentsManager#destroy) to give the [Watchlist,opts="nofollow"](https://docs.caplin.com/developer/api/caplin_trader/4/module-caplin_watchlist_Watchlist) object the opportunity to shutdown the subscription if there are no other interested parties:

```js
watchlistContentsManager.destroy();
```

The [WatchlistGridDataProvider,opts="nofollow"](https://docs.caplin.com/developer/api/caplin_trader/4/module-caplin_watchlist_sljs_WatchlistGridDataProvider) class uses the [WatchlistContentsManager,opts="nofollow"](https://docs.caplin.com/developer/api/caplin_trader/4/module-caplin_watchlist_WatchlistContentsManager) class internally to automatically synchronise changes made to the grid with the server-side watchlist.

### Appending a subject

To append one or more instruments to a watchlist, call [WatchlistContentsManager.append,opts="nofollow"](https://docs.caplin.com/developer/api/caplin_trader/4/module-caplin_watchlist_WatchlistContentsManager#append). Pass an array containing the subject names of the instruments.

```js
var watchlistContentsManager = watchlist.getContentsManager();
watchlistContentsManager.append(['/FX/GBPUSD']);
```

### Inserting a subject

To insert one or more instruments into a watchlist, call [WatchlistContentsManager.insert,opts="nofollow"](https://docs.caplin.com/developer/api/caplin_trader/4/module-caplin_watchlist_WatchlistContentsManager#insert). Pass an array containing the subject names of the instruments, and the index at which to insert them.

```js
var watchlistContentsManager = watchlist.getContentsManager();
watchlistContentsManager.insert(['/FX/GBPUSD'], 2);
```

### Removing a subject

To remove one or more instruments from a watchlist, call [WatchlistContentsManager.remove,opts="nofollow"](https://docs.caplin.com/developer/api/caplin_trader/4/module-caplin_watchlist_WatchlistContentsManager#remove). Pass an array containing the subject names of the instruments.

```js
var watchlistContentsManager = watchlist.getContentsManager();
watchlistContentsManager.remove(['/FX/GBPUSD']);
```