---
updatedAt: 2026-05-15T15:22:44.000Z
agentTools:
  projectIndex: https://docs.joinforage.app/llms.txt
---

# on()

`element.on(elementEvent, handler)`

Adds an event handler to the [`EBT Element`](https://docs.joinforage.app/reference/ebt-elements) for the provided [event](https://docs.joinforage.app/reference/events). When the event fires, the handler is called.

## Parameters

<table>
  <thead>
    <tr>
      <th style={{textAlign:"left"}}></th>
      <th style={{textAlign:"left"}}>Type</th>
      <th style={{textAlign:"left"}}>Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td style={{textAlign:"left"}}><code>elementEvent</code><br /><span style={{color:"red"}}>required</span></td>
      <td style={{textAlign:"left"}}><code>EBT Element</code> event</td>
      <td style={{textAlign:"left"}}>The <code>EBT Element</code> event that calls the handler.</td>
    </tr>
    <tr>
      <td style={{textAlign:"left"}}><code>handler</code><br /><span style={{color:"red"}}>required</span></td>
      <td style={{textAlign:"left"}}>function</td>
      <td style={{textAlign:"left"}}>A callback that fires when the provided event occurs.</td>
    </tr>
  </tbody>
</table>

## Examples

In these examples, the `ForagePinElement` is used for a balance check.

### Listen for input changes on a `ForagePinElement` and display a message if there's a validation error

```javascript
balanceElement.on('change', (event) => {
  const explainErrorSpan = document.getElementById('explain-error')
  if (event.error) {
    // show validation error to customer
    explainErrorSpan.textContent = event.error.message
  } else {
    // hide validation error
    explainErrorSpan.textContent = ''
  }
})
```

### (React-oriented) Listen for input changes and display a message if there's a validation error

```json
balanceElement.on('change', (event) => {
  if (event.error) {
    // show validation error to customer
    setValidationMessage(event.error.message)
  } else {
    // hide validation error
    setValidationMessage('')
  }
})
```

# Sibling pages

* [clear()](https://docs.joinforage.app/reference/clear.md)
* [destroy()](https://docs.joinforage.app/reference/destroy.md)
* [mount()](https://docs.joinforage.app/reference/mount.md)