HTML Events and Listeners

Handle user interactions using event listeners in JavaScript or inline event handlers

UXP supports standard HTML events for handling user interactions like clicks, input changes, and keyboard actions. You can attach event listeners in JavaScript (recommended) or use inline event handlers in HTML (requires additional permissions).

Prerequisites

Before you begin, make sure your development environment uses the following versions:

The recommended approach is to attach event listeners in JavaScript using addEventListener() or by assigning event handler properties.

data-slots=heading, code

data-repeat=2

data-languages=HTML, JavaScript

index.html

<button id="firstButton">Click me</button>
<button id="secondButton">Click me too</button>

index.js

// Method 1: addEventListener (recommended)
const firstButton = document.getElementById("firstButton");
firstButton.addEventListener("click", handleClick);

// Method 2: Event handler property
const secondButton = document.getElementById("secondButton");
secondButton.onclick = handleClick;

function handleClick(event) {
  console.log(`Button clicked: ${event.target.id}`);
}

data-variant=info

data-slots=text
Using addEventListener() is preferred because it allows multiple event listeners on the same element and provides better control over event handling.

Example: Inline Event Handlers

You can define event handlers directly in HTML attributes, but this requires enabling a special permission.

data-slots=heading, code

data-repeat=3

data-languages=HTML, JavaScript, JSON

index.html

<button id="thirdButton" onclick="handleClick(event)">Click me</button>

index.js

function handleClick(event) {
  console.log(`Button clicked: ${event.target.id}`);
}

manifest.json

{
  // ...
  "requiredPermissions": {
    "allowCodeGenerationFromStrings": true
  }
  // ...
}

data-variant=warning

data-slots=heading, text
Security consideration
The allowCodeGenerationFromStrings permission allows code execution from strings, which can introduce security risks. Only enable this if inline event handlers are essential to your plugin's architecture.

Common Event Types

UXP supports standard HTML events:

Event Type
Fires When
Common Use Cases
click
Element is clicked
Buttons, links, interactive elements
input
Input value changes
Text fields, sliders, checkboxes
change
Input value changes and loses focus
Dropdowns, file inputs
submit
Form is submitted
Forms
keydown
Key is pressed
Keyboard shortcuts
keyup
Key is released
Text input validation
focus
Element receives focus
Input fields
blur
Element loses focus
Input validation

Working with Spectrum Components

Event listeners work the same way with Spectrum Web Components:

// Spectrum button
const button = document.querySelector("sp-button");
button.addEventListener("click", () => {
  console.log("Spectrum button clicked");
});

// Spectrum slider
const slider = document.querySelector("sp-slider");
slider.addEventListener("input", (event) => {
  console.log(`Slider value: ${event.target.value}`);
});

Reference Material