# Working with Custom Events

{% hint style="info" %}
[release-1.7.0](https://docs.pixiebrix.com/release-notes/release-notes-archive/release-1.7.0 "mention") in June 2022 introduced support for Custom Events.
{% endhint %}

Custom Events can be used to define your own custom Triggers, and control when a Sidebar Panel mod refreshes.

PixieBrix uses the [DOM Event API](https://developer.mozilla.org/en-US/docs/Web/Events/Creating_and_triggering_events) standard. Therefore, custom events can be used to communicate bi-directionally with the host page.

### Emitting/Dispatching a Custom Event

To emit a custom event, use the [Emit a Custom Event](https://www.pixiebrix.com/marketplace/fcd0a884-fb83-4d82-a1c4-932287ae79f4/emit-a-custom-event/) brick. The brick takes two inputs:

* `eventName`: a unique name for the event. The name should be globally unique
* `data`: an optional data payload

PixieBrix dispatches the event on the root document of the frame.

### Running a Trigger on a Custom Event

To run a trigger on a Custom Event, choose “Custom Event” from the Trigger dropdown and configure the trigger:

* Custom Event: the name of the event. Should match the `eventName` in your use of Emit a Custom Event (see Emitting/Dispatching a Custom Event above)
* Element: an *optional* selector controlling the elements on which to listen for the event. Use when running triggers for events from the host page. The Emit a Custom Event brick emits events on the document itself.

<figure><img src="https://2274778196-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fq123bF1HPQPV35s5vHa1%2Fuploads%2FfSQORELaW74Bs8Ch3Kdl%2FUntitled%20(71).png?alt=media&#x26;token=b8afba90-1624-414e-8406-37464a9eb851" alt=""><figcaption></figcaption></figure>

If the event includes data, that data will be available to the Trigger mod bricks as `@input.event`

If the event includes data, that data will be available to the Trigger mod bricks as `@input.event`

<figure><img src="https://2274778196-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fq123bF1HPQPV35s5vHa1%2Fuploads%2FXXsP7ELjkUzxvwMrbh83%2FUntitled%20(72).png?alt=media&#x26;token=df69349c-8984-4c11-863a-5f6bc8ca7b8f" alt=""><figcaption></figcaption></figure>

### Refreshing a Sidebar Panel on Custom Event

Custom Events can also be used to control Sidebar Panel updates. To configure a Sidebar Panel to update on a custom event, choose “Custom Event” from the Panel Refresh > Trigger dropdown.

Then, configure the event to listen for:

* Custom Event: the name of the event. Should match the `eventName` in your use of Emit a Custom Event (see Emitting/Dispatching a Custom Event above)

<figure><img src="https://2274778196-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fq123bF1HPQPV35s5vHa1%2Fuploads%2F3YcGjN20I4wdiZ1yMCq3%2FUntitled%20(73).png?alt=media&#x26;token=060c2c03-676a-477b-9f87-fc9f775a5494" alt=""><figcaption></figcaption></figure>