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

# .on()

`.on()` attaches any event listener.

***

#### Syntax

```js
element.on(eventType, callback);
element.on(eventType, callback, ?options);
```

***

#### Parameters

* `eventType` → event name like `'click'`, `'input'`, or `'change'`
* `callback` → function to run
* `options` → optional event listener options

***

#### Output

```js
HTMLElement | NodeList | HTMLCollection
```

***

#### Example

```js
$('#upload').on('change', function () {
  console.log(this.files);
});
```

***

#### Use cases

Use `.on()` when you need an event not covered by a specialized helper:

* Respond to element focus and blur.
* Handle keyboard input.
* Run code once when an event occurs.

***

#### More examples

Show guidance when an input receives focus:

```js
$('#email').on('focus', () => {
  $('#email-help').show();
});
```

Listen for a custom keyboard action:

```js
$('#message').on('keydown', function(e) {
  if (e.key === 'Escape') {
    this.val('');
  }
});
```

Run an action only once:

```js
$('#welcome').on('click', () => {
  $('#welcome').hide();
}, { once: true });
```

***

#### Key Takeaway

> `.on()` is the general event helper.