feat: add lwc:on directive

packages/@lwc/compiler/src/options.ts

@@ -125,6 +125,8 @@ export interface TransformOptions {
     customRendererConfig?: CustomRendererConfig;
     /** @deprecated Ignored by compiler. `lwc:spread` is always enabled. */
     enableLwcSpread?: boolean;
+    /** Flag to enable usage of dynamic event listeners (lwc:on) directive in HTML template */
+    enableLwcOn?: boolean;
     /** Set to true if synthetic shadow DOM support is not needed, which can result in smaller/faster output. */
     disableSyntheticShadowSupport?: boolean;
     /**
@@ -148,6 +150,7 @@ type OptionalTransformKeys =
     | 'scopedStyles'
     | 'customRendererConfig'
     | 'enableLwcSpread'
+    | 'enableLwcOn'
     | 'enableLightningWebSecurityTransforms'
     | 'enableDynamicComponents'
     | 'experimentalDynamicDirective'

packages/@lwc/compiler/src/transformers/template.ts

@@ -40,6 +40,7 @@ export default function templateTransform(
         customRendererConfig,
         enableDynamicComponents,
         experimentalDynamicDirective: deprecatedDynamicDirective,
+        enableLwcOn,
         instrumentation,
         namespace,
         name,
@@ -61,6 +62,7 @@ export default function templateTransform(
             enableStaticContentOptimization,
             customRendererConfig,
             enableDynamicComponents,
+            enableLwcOn,
             instrumentation,
             apiVersion,
             disableSyntheticShadowSupport,

packages/@lwc/engine-core/src/framework/hydration.ts

@@ -50,6 +50,7 @@ import { VNodeType, isVStaticPartElement } from './vnodes';
 
 import { patchProps } from './modules/props';
 import { applyEventListeners } from './modules/events';
+import { patchDynamicEventListeners } from './modules/dynamic-events';
 import { hydrateStaticParts, traverseAndSetElements } from './modules/static-parts';
 import { getScopeTokenClass } from './stylesheet';
 import { renderComponent } from './component';
@@ -517,6 +518,7 @@ function handleMismatch(node: Node, vnode: VNode, renderer: RendererAPI): Node |
 
 function patchElementPropsAndAttrsAndRefs(vnode: VBaseElement, renderer: RendererAPI) {
     applyEventListeners(vnode, renderer);
+    patchDynamicEventListeners(null, vnode, renderer, vnode.owner);
     patchProps(null, vnode, renderer);
     // The `refs` object is blown away in every re-render, so we always need to re-apply them
     applyRefs(vnode, vnode.owner);

packages/@lwc/engine-core/src/framework/modules/dynamic-events.ts

@@ -0,0 +1,98 @@
+/*
+ * Copyright (c) 2025, salesforce.com, inc.
+ * All rights reserved.
+ * SPDX-License-Identifier: MIT
+ * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/MIT
+ */
+import { isUndefined } from '@lwc/shared';
+import { EmptyObject } from '../utils';
+import { invokeEventListener } from '../invoker';
+import type { VM } from '../vm';
+import type { VBaseElement } from '../vnodes';
+import type { RendererAPI } from '../renderer';
+
+export function patchDynamicEventListeners(
+    oldVnode: VBaseElement | null,
+    vnode: VBaseElement,
+    renderer: RendererAPI,
+    owner: VM
+) {
+    const {
+        elm,
+        data: { dynamicOn, dynamicOnRaw },
+        sel,
+    } = vnode;
+
+    const oldDynamicOn = oldVnode?.data?.dynamicOn ?? EmptyObject;
+    const newDynamicOn = dynamicOn ?? EmptyObject;
+
+    // Compare raw values to check if same object is passed to lwc:on
+    const isObjectSame = oldVnode?.data?.dynamicOnRaw === dynamicOnRaw;
+
+    const { addEventListener, removeEventListener } = renderer;
+    const attachedEventListeners = getAttachedEventListeners(owner, elm!);
+
+    // Properties that are present in 'oldDynamicOn' but not in 'newDynamicOn'
+    for (const eventType in oldDynamicOn) {
+        if (!(eventType in newDynamicOn)) {
+            // Throw if same object is passed
+            if (isObjectSame) {
+                throw new Error(
+                    `Detected mutation of property '${eventType}' in the object passed to lwc:on for <${sel}>. Reusing the same object with modified properties is prohibited. Please pass a new object instead.`
+                );
+            }
+
+            // Remove listeners that were attached previously but don't have a corresponding property in `newDynamicOn`
+            const attachedEventListener = attachedEventListeners[eventType];
+            removeEventListener(elm, eventType, attachedEventListener!);
+            attachedEventListeners[eventType] = undefined;
+        }
+    }
+
+    // Ensure that the event listeners that are attached match what is present in `newDynamicOn`
+    for (const eventType in newDynamicOn) {
+        const oldCallback = oldDynamicOn[eventType];
+        const newCallback = newDynamicOn[eventType];
+
+        // Properties that are present in 'newDynamicOn' but whose value are different from that in `oldDynamicOn`
+        if (oldCallback !== newCallback) {
+            // Throw if same object is passed
+            if (isObjectSame) {
+                throw new Error(
+                    `Detected mutation of property '${eventType}' in the object passed to lwc:on for <${sel}>. Reusing the same object with modified properties is prohibited. Please pass a new object instead.`
+                );
+            }
+
+            // Remove listener that was attached previously
+            if (oldCallback) {
+                const attachedEventListener = attachedEventListeners[eventType];
+                removeEventListener(elm, eventType, attachedEventListener!);
+            }
+
+            // Bind callback to owner component and add it as listener to element
+            const newBoundEventListener = bindEventListener(owner, newCallback);
+            addEventListener(elm, eventType, newBoundEventListener);
+
+            // Store the newly added eventListener
+            attachedEventListeners[eventType] = newBoundEventListener;
+        }
+    }
+}
+
+function getAttachedEventListeners(
+    vm: VM,
+    elm: Element
+): Record<string, EventListener | undefined> {
+    let attachedEventListeners = vm.attachedEventListeners.get(elm);
+    if (isUndefined(attachedEventListeners)) {
+        attachedEventListeners = {};
+        vm.attachedEventListeners.set(elm, attachedEventListeners);
+    }
+    return attachedEventListeners;
+}
+
+function bindEventListener(vm: VM, fn: EventListener): EventListener {
+    return function (event: Event) {
+        invokeEventListener(vm, fn, vm.component, event);
+    };
+}

packages/@lwc/engine-core/src/framework/rendering.ts

@@ -53,6 +53,7 @@ import { patchProps } from './modules/props';
 import { patchClassAttribute } from './modules/computed-class-attr';
 import { patchStyleAttribute } from './modules/computed-style-attr';
 import { applyEventListeners } from './modules/events';
+import { patchDynamicEventListeners } from './modules/dynamic-events';
 import { applyStaticClassAttribute } from './modules/static-class-attr';
 import { applyStaticStyleAttribute } from './modules/static-style-attr';
 import { applyRefs } from './modules/refs';
@@ -586,6 +587,7 @@ function patchElementPropsAndAttrsAndRefs(
     }
 
     const { owner } = vnode;
+    patchDynamicEventListeners(oldVnode, vnode, renderer, owner);
     // Attrs need to be applied to element before props IE11 will wipe out value on radio inputs if
     // value is set before type=radio.
     patchClassAttribute(oldVnode, vnode, renderer);

packages/@lwc/engine-core/src/framework/vm.ts

@@ -135,6 +135,8 @@ export interface VM<N = HostNode, E = HostElement> {
     readonly owner: VM<N, E> | null;
     /** References to elements rendered using lwc:ref (template refs) */
     refVNodes: RefVNodes | null;
+    /** event listeners added to elements corresponding to functions provided by lwc:on */
+    attachedEventListeners: WeakMap<Element, Record<string, EventListener | undefined>>;
     /** Whether or not the VM was hydrated */
     readonly hydrated: boolean;
     /** Rendering operations associated with the VM */
@@ -344,6 +346,7 @@ export function createVM<HostNode, HostElement>(
         mode,
         owner,
         refVNodes: null,
+        attachedEventListeners: new WeakMap(),
         children: EmptyArray,
         aChildren: EmptyArray,
         velements: EmptyArray,

packages/@lwc/engine-core/src/framework/vnodes.ts

@@ -153,6 +153,8 @@ export interface VNodeData {
     readonly styleDecls?: ReadonlyArray<[string, string, boolean]>;
     readonly context?: Readonly<Record<string, Readonly<Record<string, any>>>>;
     readonly on?: Readonly<Record<string, (event: Event) => any>>;
+    readonly dynamicOn?: Readonly<Record<string, (event: Event) => any>>; // clone of object passed to lwc:on, used to patch event listeners
+    readonly dynamicOnRaw?: Readonly<Record<string, (event: Event) => any>>; // object passed to lwc:on, used to verify whether object reference has changed
     readonly svg?: boolean;
     readonly renderer?: RendererAPI;
 }

packages/@lwc/errors/src/compiler/error-info/index.ts

@@ -5,7 +5,7 @@
  * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/MIT
  */
 /**
- * Next error code: 1203
+ * Next error code: 1207
  */
 
 export * from './compiler';

packages/@lwc/errors/src/compiler/error-info/template-transform.ts

@@ -947,4 +947,36 @@ export const ParserDiagnostics = {
         level: DiagnosticLevel.Warning,
         url: '',
     },
+
+    INVALID_LWC_ON_ELEMENT: {
+        code: 1203,
+        message:
+            'Invalid lwc:on usage on element "{0}". The directive can\'t be used on a template element.',
+        level: DiagnosticLevel.Error,
+        url: '',
+    },
+
+    INVALID_LWC_ON_LITERAL_PROP: {
+        code: 1204,
+        message:
+            'Invalid lwc:on usage on element "{0}". The directive binding must be an expression.',
+        level: DiagnosticLevel.Error,
+        url: '',
+    },
+
+    INVALID_LWC_ON_WITH_DECLARATIVE_LISTENERS: {
+        code: 1205,
+        message:
+            'Invalid lwc:on usage on element "{0}". It is not permitted to use declarative event listeners alongside lwc:on',
+        level: DiagnosticLevel.Error,
+        url: '',
+    },
+
+    INVALID_LWC_ON_OPTS: {
+        code: 1206,
+        message:
+            'Invalid lwc:on usage. The `lwc:on` directive must be enabled in order to use this feature.',
+        level: DiagnosticLevel.Error,
+        url: '',
+    },
 };

packages/@lwc/integration-karma/scripts/karma-plugins/lwc.js

@@ -58,6 +58,7 @@ function createPreprocessor(config, emitter, logger) {
                     strict: true,
                 },
                 enableDynamicComponents: true,
+                enableLwcOn: true,
                 experimentalComplexExpressions,
                 enableStaticContentOptimization: !DISABLE_STATIC_CONTENT_OPTIMIZATION,
                 disableSyntheticShadowSupport: DISABLE_SYNTHETIC_SHADOW_SUPPORT_IN_COMPILER,