Introduction
Hi everyone, welcome to this Spring ’26 LWC blog post! In this article, we’ll explore a practical enhancement in this release. You can now bind event listeners dynamically using a new directive.
With Spring ’26, salesforce has introduced a powerful enhancement to Lightning Web Components (LWC). This enhancement improves how we handle events in templates.
Earlier versions of LWC required developers to write every individual event listener directly in the HTML template. With Spring ’26, Salesforce has introduced a new method. You can now define your event bindings as objects in JavaScript. This keeps your templates cleaner and your logic more flexible.
You may be getting comfortable with LWC. Or perhaps you are building reusable modular components. Either way, this update helps in simplifying event handling patterns. It also unlocks dynamic interaction capabilities.
In this post, we’ll explore:
- What changed in Spring ’26
- Why dynamic event binding matters
- How to use the new
lwc:ondirective - A practical example with child components
- Best practices for real-world projects
What Used to Be — Static Event Binding
Before Spring ’26:
✔ You could attach events like onclick, onmouseover, etc.
✔ Templates had to list out each handler explicitly.
❌ You could not change which events a component listened for at runtime without modifying the markup.
If your component needed different behavior depending on context or user choice, you often had to build workarounds. You also had to rely on lots of conditional logic. This cluttered both the template and JavaScript.
Example Static Event Binding
Template
<template>
<lightning-card title="StaticEventListener" icon-name="standard:logging">
<div class="slds-var-m-horizontal_medium">
<lightning-radio-group
label="Event Mode"
type="button"
options={modeOptions}
value={eventMode}
onchange={handleModeChange}
class="slds-var-m-bottom_large"
>
</lightning-radio-group>
<div class={boxClass} onclick={handleClick} onmouseenter={handleMouseEnter} onmouseleave={handleMouseLeave}>
<div class="box-message">{message}</div>
<div class="box-hint">{hintText}</div>
</div>
</div>
</lightning-card>
</template>
JavaScript
import { LightningElement } from 'lwc';
export default class TestStaticEvent extends LightningElement {
// 'click' or 'hover' mode
modeOptions = [
{ label: 'Click Mode', value: 'click' },
{ label: 'Hover Mode', value: 'hover' }
];
message = 'Interact with the box!';
eventMode = 'click';
handleModeChange(event) {
this.eventMode = event.detail.value;
this.message = `Now using ${this.eventMode.toUpperCase()} mode`;
}
handleClick() {
if (this.eventMode === 'click') {
this.message = '🖱️ You clicked!';
}
}
handleMouseEnter() {
if (this.eventMode === 'hover') {
this.message = '✨ Mouse entered!';
}
}
handleMouseLeave() {
if (this.eventMode === 'hover') {
this.message = '👋 Mouse left!';
}
}
get boxClass() {
const modeClass = `${this.eventMode}-mode`;
return `slds-box slds-box_small slds-text-align_center interactive-box ${modeClass}`;
}
get hintText() {
return this.eventMode === 'click'
? '👆 Click here'
: '🖐️ Hover over me';
}
}
Explanation:
In this example, event listeners are statically defined in the template using attributes like onclick, onmouseenter, and onmouseleave. These handlers are always attached to the <div> element regardless of the selected interaction mode.
The component allows the user to switch between Click Mode and Hover Mode using the radio button group. When the mode changes, the eventMode property is updated through the handleModeChange method.
Each event handler (handleClick, handleMouseEnter, and handleMouseLeave) then checks the current eventMode before performing any action. For example, the click handler only updates the message when the component is in click mode. In contrast, the hover handlers update the message when the component is in hover mode.
Although this approach works, all event listeners remain attached to the element even when they are not needed. The handlers also require additional conditional checks. These checks determine whether the logic should execute. This can make the code harder to maintain as the component grows.
Limitations of Static Event Binding
While the above approach works for simple components, it has some drawbacks:
- All events are always attached – Even when the component is in click mode, hover events (
mouseenter,mouseleave) are still registered on the element. - Extra conditional logic in JavaScript – Each handler must check
eventModeto decide whether it should execute. - Multiple handlers for related behavior – Logic gets spread across different methods (
handleClick,handleMouseEnter,handleMouseLeave). - Hard-coded event bindings in the template – Events like
onclickandonmouseenterare directly written in markup. - Reduced flexibility for reusable components – Changing interaction behavior requires modifying both template and JavaScript.
Because of these limitations, the component template becomes tightly coupled to specific event handlers. This coupling makes it harder to adapt the behavior dynamically.
What’s New — lwc:on Directive
Spring ’26 introduces a new directive called lwc:on. This directive lets you bind multiple event listeners to an element dynamically, using a JavaScript object that maps event types to functions.
Instead of declaring event attributes like onclick,onfocus erc. individually in HTML, you define them inside JavaScript and pass them as an object.
Why This Matters
- 🧹 Cleaner Templates – Keep HTML minimal and declarative.
- 🔁 Dynamic Behavior – Change event bindings based on state or configuration without touching the template.
- 🔌 Reusable Logic – Move event logic to JavaScript files that can be shared across multiple components.
Core Concept — Dynamic Event Map
The lwc:on directive accepts an object property where:
- Keys are event names (e.g.,
click,focus,mouseover) - Values are functions that run when those events occur
This pattern centralizes event logic into JavaScript — making your templates single-purpose and easier to read.
Example: Simple Dynamic Event Map
Here’s how you might use lwc:on in a very straightforward scenario.
Template
<template>
<lightning-card title="DynamicEventListener" icon-name="standard:logging">
<div class="slds-var-m-horizontal_medium">
<lightning-radio-group
label="Event Mode"
type="button"
options={modeOptions}
value={eventMode}
onchange={handleModeChange}
class="slds-var-m-bottom_large"
>
</lightning-radio-group>
<div class={boxClass} lwc:on={boxEventHandlers}>
<div class="box-message">{message}</div>
<div class="box-hint">{hintText}</div>
</div>
</div>
</lightning-card>
</template>
JavaScript
import { LightningElement } from 'lwc';
export default class TestDynamicEvent extends LightningElement {
// 'click' or 'hover' mode
modeOptions = [
{ label: 'Click Mode', value: 'click' },
{ label: 'Hover Mode', value: 'hover' }
];
message = 'Interact with the box!';
eventMode = 'click';
/**
* THE KEY FEATURE: Returns an object of event handlers
* The lwc:on directive uses this to attach listeners dynamically
*/
get boxEventHandlers() {
const handlers = {};
switch (this.eventMode) {
case 'click':
handlers.click = () => {
this.message = '🖱️ You clicked!';
};
break;
case 'hover':
handlers.mouseenter = () => {
this.message = '✨ Mouse entered!';
};
handlers.mouseleave = () => {
this.message = '👋 Mouse left!';
};
break;
// no default
}
return handlers;
}
handleModeChange(event) {
this.eventMode = event.detail.value;
this.message = `Now using ${this.eventMode.toUpperCase()} mode`;
}
get boxClass() {
const modeClass = `${this.eventMode}-mode`;
return `slds-box slds-box_small slds-text-align_center interactive-box ${modeClass}`;
}
get hintText() {
return this.eventMode === 'click'
? '👆 Click here'
: '🖐️ Hover over me';
}
}
Explanation:
In this example, lwc:on={boxEventHandlers} dynamically attaches event listeners to the <div> element. The getter boxEventHandlers returns an object where the keys represent event names and the values are the corresponding handler functions.
Based on the selected eventMode, the component returns different event handlers:
- In Click Mode, only the
clickevent listener is attached. - In Hover Mode, the
mouseenterandmouseleaveevent listeners are attached.
When the user switches the mode using the radio buttons, the eventMode value changes. This causes the getter to recompute the event handler object, and LWC automatically updates the listeners on the element.
This approach keeps the template clean and avoids writing multiple static event attributes like onclick, onmouseenter, and onmouseleave. Instead, the event behavior is controlled entirely through JavaScript, making the component more flexible and easier to maintain.
Using lwc:on with Child Components
Spring ’26 supports passing this directive to child components. This allows parent components to dynamically control how they respond to events. These events are emitted by children. This paves the way for more configurable components that can handle custom events without hard-coding listeners all over the place.
For example:
- The parent prepares an event map and passes it to the child through a property
- The child uses
lwc:onto hook into those events - When a child fires a custom event, the parent’s handler reacts accordingly
This helps keep the communication pattern clean and reduces duplicated event wiring in child markup.
Parent Component — Template
<template>
<lightning-card title="ParentDynamicEvent">
<div class="slds-var-m-horizontal_medium">
<c-child-display lwc:on={childEventHandlers}></c-child-display>
<br/>
<p>Child says: {message}</p>
</div>
</lightning-card>
</template>
Parent Component — JavaScript
import { LightningElement, track } from 'lwc';
export default class ParentDynamicEvents extends LightningElement {
@track message = '';
childEventHandlers = {
sendMessage: this.handleChildMessage
};
handleChildMessage(event) {
this.message = `Received: ${event.detail.text}`;
}
}
Child Component — Template
<template>
<lightning-button
label="Send Message"
onclick={fireCustomEvent}>
</lightning-button>
</template>
Child Component — JavaScript
import { LightningElement } from 'lwc';
export default class ChildDisplay extends LightningElement {
fireCustomEvent() {
this.dispatchEvent(
new CustomEvent('sendMessage', {
detail: { text: 'Hello from Child!' }
})
);
}
}
Explanation:
- The parent sends a handler object to the child
- The child uses
lwc:onto attach dynamic listeners - When the child dispatches a custom event, the parent handler reacts and updates UI
This pattern improves separation of concerns and reduces tight coupling between parent-child components.
When Should You Use lwc:on?
Recommended
- You want cleaner templates
- Event logic depends on component state
- You need reusable or configurable handlers
- Events are computed or passed via
@api
Be Cautious
- Simple static events with a single handler
- Over-abstracting very small components
- When custom events are straightforward and never change
Summary — Spring ’26 LWC Event Handling Made Better
The lwc:on directive in Spring ’26 is a thoughtful evolution for LWC developers:
✔ Reduces template clutter
✔ Enables dynamic, state-based event behavior
✔ Makes components easier to maintain and reuse
Welcome to The Salesforce Dev 
Leave a comment