# 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.               |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://mobius-studios.gitbook.io/selectable/api/events.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.