> For the complete documentation index, see [llms.txt](https://mobius-studios.gitbook.io/selectable/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://mobius-studios.gitbook.io/selectable/api/events.md).

# Events

Selectable fires a number of custom events that the instance can listen for.

You can attach a number of custom event listeners using the [`on()`](https://mobius1.github.io/Selectable/api/methods/on.html) method and pass the event name and a callback as the first two arguments:

```javascript
const selectable = new Selectable();

selectable.on('event_name', myCallback);
```

Event listeners can be detached by calling the [`off()`](https://mobius1.github.io/Selectable/api/methods/off.html) method with the same arguments:

```javascript
selectable.off('event_name', myCallback);
```

***

{% hint style="info" %}
Both the `on()` and `off()` methods function the same as the native [`addEventListener`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener) and [`removeEventListener`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/removeEventListener) methods respectively.

This means that in order to remove a custom event listener from the instance, you must pass the same [function expression](https://developer.mozilla.org/en-US/docs/web/JavaScript/Reference/Operators/function) to the `off()` method as you did to the `on()` method - [declared / anonymous functions](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function) cannot be removed.
{% endhint %}

#### Incorrect <a href="#incorrect" id="incorrect"></a>

```javascript
selectable.on('end', function(e, selected, unselected) {
    counter.value = selected.length;
});
```

#### Correct <a href="#correct" id="correct"></a>

<pre class="language-javascript"><code class="lang-javascript">const myCallback = function(e, selected, unselected) {
    counter.value = selected.length;
<strong>};
</strong>
// add the event listener
selectable.on('end', myCallback);

// remove the event listener
selectable.off('end', myCallback);
</code></pre>

***

### Listening for an event once

```javascript
const myCallback = function(e, selected, unselected) {
    // Do something once

    // Remove the event listener
    this.off('select', myCallback);
};

// Add the event listener
selectable.on('select', myCallback);
```

### Event reference <a href="#eventreference" id="eventreference"></a>

| Name                                                   | Description                              |
| ------------------------------------------------------ | ---------------------------------------- |
| [`init`](/selectable/api/events/init.md)               | The instance is ready.                   |
| [`destroyed`](/selectable/api/events/destroyed.md)     | The instance has been destroyed          |
| [`add`](/selectable/api/events/add.md)                 | An item was added to the instance.       |
| [`remove`](/selectable/api/events/remove.md)           | An item was removed from the instance.   |
| [`start`](/selectable/api/events/start.md)             | `mousedown` / `touchstart`.              |
| [`drag`](/selectable/api/events/drag.md)               | `mousemove` / `touchmove`.               |
| [`end`](/selectable/api/events/end.md)                 | `mouseup` / `touchend`.                  |
| [`select`](/selectable/api/events/select.md)           | An item was selected.                    |
| [`deselect`](/selectable/api/events/deselect.md)       | An item was deselected.                  |
| [`selecting`](/selectable/api/events/selecting.md)     | An item has been marked for selection.   |
| [`deselecting`](/selectable/api/events/deselecting.md) | An item has been marked for deselection. |
| [`state`](/selectable/api/events/state.md)             | Save state change.                       |
| [`enabled`](/selectable/api/events/enabled.md)         | The instance was enabled.                |
| [`disabled`](/selectable/api/events/disabled.md)       | The instance was disabled.               |