How to handle addEventListener on `CSSPseudoElement`?

[danielsakhapov]

Full context: https://github.com/danielsakhapov/CSSPseudoElementDoc?tab=readme-ov-file#41-addeventlistener-on-a-proxyhandle

Description:
Given that the CSSPseudoElement object acts as a persistent handle, attaching an event listener via addEventListener raises further questions.

• What does it mean to listen for an event on a handle when the actual pseudo element might not be currently rendered (e.g., due to display: none)?
• Should the listener only become active when the pseudo element is actually rendered?
• How does this interact with the retargeting behavior?
• If event.target remains the Element, how does a listener on the CSSPseudoElement get invoked?
• Does it require a special dispatch phase?

This would require some heavy discussions, as it’s already known that authors want to be able to count clicks on ::scroll-marker pseudo elements for analytics purposes.

Potential solutions on example of ::scroll-marker:

• No direct listening on pseudo element (Status Quo):
  • Description: Do not allow addEventListener('click',...) directly on the CSSPseudoElement for ::scroll-marker. Clicks physically hitting the marker would continue to dispatch with event.target set to the originating Element. Developers would have to attach the listener to the Element and use coordinate-based hit-testing within that listener to infer if the click landed on the marker area.
  • Pros:
    • Requires no changes to the event dispatch model.
    • Zero web compatibility risk regarding event.target.
  • Cons:
    • Very poor developer ergonomics for this specific use case. Calculating marker positions and sizes to perform manual hit-testing is complex, brittle (breaks with style changes), and potentially slow.
    • Makes the CSSPseudoElement object less useful and doesn't leverage its EventTarget inheritance.
• Allow direct listening with special dispatch phase:
  • Description: Allow developers to call scrollMarkerPseudoElement.addEventListener('click', counterFunction). When a click physically occurs on the scroll marker:
    • Special Phase: The browser's event system identifies the hit target as the ::scroll-marker and invokes counterFunction (and any other listeners attached directly to this specific CSSPseudoElement handle).
    • Standard Phase: The event dispatch continues as normal, but crucially, event.target is set to the originating scrollable Element. The event then proceeds through the capture and bubble phases relative to the Element, without re-invoking counterFunction during this standard flow.
  • Pros:
    • Directly addresses the developer need: allows attaching listeners specifically to the pseudo-element of interest.
    • Preserves web compatibility by ensuring event.target remains the Element during the standard, observable event flow.
    • Provides a meaningful use for the EventTarget inheritance on CSSPseudoElement.
    • Much better developer ergonomics than manual coordinate checking.
  • Cons:
    • Requires implementing the modified event dispatch logic (the "special phase").
    • The event model becomes slightly more complex internally, though the developer-facing API (addEventListener on the pseudo) is intuitive.
• Introduce a new specific event type:
  • Description: Instead of using the standard click event, define a new event type like pseudoElementClick that only fires on the CSSPseudoElement handle for pseudo elements. Standard click events would continue to target the Element only.
  • Pros:
    • Avoids any ambiguity or modification related to the standard click event dispatch.
    • Clearly separates the interaction.
  • Cons:
    • Introduces a new event type for a very specific interaction, potentially leading to event type proliferation.
    • Developers might intuitively try to listen for click first and be confused why it doesn't work directly on the pseudo-element handle without the special dispatch phase.
    • Doesn't fully resolve the general question of how other standard events (like mouseover) should interact with pseudo-elements if direct listeners are desired.
• Add event.pseudoElement as in KeyframeEffect for Web Animations:
  • Description: Add pseudoElement parameter as either CSSPseudoElement or string to event which will be set if the event was fired from the pseudo element. Allowing calling addEventListener on CSSPseudoElement can even be optional here.
  • Pros:
    • Avoids web compat issues.
    • Sidesteps pseudo lifetime/eventing complexity for the use case if pseudoElement is represented as string.
    • Proven feasible for Web Animations.
  • Cons:
    • Adding new API.

Recommendation:

Add event.pseudoElement as in KeyframeEffect for Web Animations.

Justification: This option provides the best balance. It directly enables the desired developer use case (listening for clicks on the scroll marker) with good ergonomics (addEventListener on the pseudo element object). Crucially, it achieves this while adhering to the non-negotiable web compatibility requirement that event.target for standard events like click must remain the originating Element.

[Loirooriol]

Allow direct listening with special dispatch phase

I think that invoking the listener on pseudo-elements before the entire standard dispatch is very weird. I would expect:

1. Capturing phase: event listeners with capture set to true, on ancestors, from the root towards the target
2. At target phase (1): event listeners with capture set to true, on the target element
3. (new) Pseudo-element phase (1): event listeners with capture set to true, on the target pseudo-element
4. (new) Pseudo-element phase (2): event listeners with capture set to false, on the target pseudo-element
5. At target phase (2): event listeners with capture set to false, on the target element
6. Bubbling phase: event listeners with capture set to false, on ancestors, from the the target towards the root. Only if the event bubbles.

It's still kinda weird that non-bubbling events will still bubble from the actual pseudo-element target to the ultimate originating element target.

[danielsakhapov]

Agree, I think the best would be to "Add event.pseudoElement as in KeyframeEffect for Web Animations" as it both covers the use case and doesn't introduce any new confusing constructions, what do you think?

[Loirooriol]

Yes, that approach can be less confusing. But maybe I would name it targetPseudoElement or pseudoElementTarget or such.

[danielsakhapov]

oh ofc, my naming was just for describing the approach, the naming can be discussed later.
I'm wondering if we should also have ~currentTargetPseudoElement to cover the case of nested pseudo elements?

[foolip]

cc @annevk about potential changes to DOM, please see "Add event.pseudoElement as in KeyframeEffect for Web Animations" for the proposed solution here.

[annevk]

This seems like a pretty big layering violation?

[danielsakhapov]

Sorry, I don't think I understand.
Do you mean that we shouldn't add CSS spec to the HTML one?
Or is there some layering in DOM events?
Could you elaborate, please?

[flackr]

My preference is to add the target pseudo-element to the event object. This allows for developers to use event delegation patterns with pseudo-element targets as well. Note that it should be the object as a string is not necessarily sufficient to uniquely identify a pseudo-element.

[css-meeting-bot]

The CSS Working Group just discussed How to handle addEventListener on `CSSPseudoElement`?.

The full IRC log of that discussion

<TabAtkins> sakhapov: so PseudoElement inherits from EventTarget
<TabAtkins> sakhapov: how do we represent this, without webcompat problems
<TabAtkins> sakhapov: proposal is to add pseudoElementTarget and currentPseudoElementTarget, similar to target and currentTarget. Will have to discuss this with DOM folks as well, but wanted opinions here first
<TabAtkins> flackr: sounds good
<TabAtkins> Yeah, I think this is what we need, can't set .target to a PseudoElement without breaking code
<TabAtkins> sakhapov: anne pointed out it might be a layering violation
<TabAtkins> flackr: i think the point is just that the html spec needs to call into the css pseudo spec to set up this property on the event
<TabAtkins> sakhapov: okay, if no one objects i'll propose this at the WHATNOT html meeting
<TabAtkins> fantasai: Anne says he wants more time to consider flackr's idea, also wants to hear from smaug from Moz since he's been involved with events for a long time
<TabAtkins> astearns: i think taking this to HTML is the right next step, to get feedback there as well
<TabAtkins> astearns: we ahve a joint meeting with whatwg every other thursday
<TabAtkins> sakhapov: sounds good

[danielsakhapov]

Proposed rough draft changes to the DOM and the CSS specs to add pseudoTarget and currentPseudoTarget to the Event interface.

CSS spec.

Dispatching an event on a pseudo-element.

• First either (a) make internally a target a CSSPseudoElement or (b) add an argument pseudoTarget to the dispatching struct.

• Then when an event is dispatched on target the user agent must run the following algorithm to determine the event's pseudoTarget and currentPseudoTarget:

  • Let event be the Event object being dispatched.

  • Let event.pseudoElement be either the target if we go with (a) or pseudoElement parameter if we go with (b).

  • If we go with (a):

    • Let parent be the ultimate originating element of the pseudoElement.

    • Set target to be parent.

  • Set currentPseudoTarget to null.

Adding pseudo-elements to the event path algorithm:

• Let pseudoElements be a list of pseudo-element ancestors starting with the pseudoTarget and going up to the outermost pseudo-element attached to the target.

• Insert the pseudoElements list into the event's path right before the target or maybe as a separate parameter if it’s a web compat problem?

The algorithm to update currentPseudoTarget and currentTarget during event capture:

• If invoked on CSSPseudoElement, set currentPseudoTarget to that CSSPseudoElement.

• Otherwise set currentTarget to the currently invoked target and set currentPseudoTarget to null.

• Maybe clear pseudo-elements from the event path, once we processed them there.

DOM spec.

• In the event dispatching algorithm a new step should be added to call the CSS spec algorithm. (after the target is set, probably).

• The event path creation algorithm should call the CSS spec algorithm for adding pseudo-elements to the event path.

• Call current targets setting algorithm during event capture and bubbling.

The overall idea is to add the new functionality for CSSPseudoElement in events, while masking the changes for the code which doesn't know anything about CSSPseudoElement in events.

[danielsakhapov]

My previous rough draft was based on adding pseudo-elements to the event path and having them participate in bubbling.

After talking with the WHATNOT WG and hearing all the feedback, especially around the huge web-compat risks with mouseover/mouseout events (e.g. hovering mouse over pseudo-elements and real element would fire too many events), it's clear that my first approach was too complex and risky.

So, I've rethought it and would like to propose a much simpler and safer alternative.

New Proposal: A "Contained Event" Model

The idea is simple: when an event happens on a pseudo-element, it fires a self-contained event that only its own listeners can hear.

• The event does not bubble up to the originating element. It lives and dies with the pseudo-element.
• To give developers context, we'd add a new event.pseudoTarget property that points to the pseudo-element handle.

This means the main event dispatch for the real element is completely untouched, which guarantees web compatibility. It neatly solves the mouseover problem because the pseudo's mouseover is a separate event that old code will never see.

Here’s how it would work for the ::scroll-marker use case:

const list = document.querySelector('#firstItem');
const scrollMarker = list.pseudo('::scroll-marker');

// The API is simple and does what you'd expect:
scrollMarker.addEventListener('click', (event) => {
  console.log('Scroll marker was clicked!');
  // event.target would still be the #firstItem if it bubbled,
  // but this event doesn't bubble at all.
  console.log(event.pseudoTarget); // The CSSPseudoElement for ::scroll-marker
});

---

The Important Limitations: Where This Model Breaks Down

Now, this model is safer, but it isn't solving everything. Here are some examples of unsolved problems.

1. Default event handling

Because the pseudo-element's event is completely separate, it can't affect the behavior of its real parent element.

• Preventing Navigation: If you have a ::before on an <a> tag and call event.preventDefault() in the pseudo's click listener, the link will still navigate. The preventDefault() call only affects the contained event, not the separate, standard event that fires on the <a> tag.
• Form Submission: Likewise, if you style a pseudo-element to look like a submit button inside a <form>, clicking it will not submit the form. It's not a real form-associated element, and the click event doesn't trigger the form's submit action.

2. Accessibility Issues

This is probably the most critical issue. The model encourages building components that are inaccessible to many users.

• Invisible to Screen Readers: Interactive logic attached to a pseudo-element is a black box for assistive technologies. A screen reader builds its understanding from the DOM via the accessibility tree, and pseudo-elements aren't really there now. Though, probably, it can be fixed with spec changes?
• Keyboard Unreachability: Since generally a pseudo-element can't get focus, it's unreachable via keyboard navigation. Any click listener on a pseudo is therefore mouse-only logic. This creates a significant barrier for users who rely on keyboards.

3. Stateful UI

The model works for simple, one-off clicks but breaks down for any stateful UI interaction.

• Drag and Drop: Trying to use a ::before as a "drag handle" is problematic. The dragstart event on the pseudo is disconnected from the element you actually want to drag.

4. Ambiguous in Complex Layouts and Debugging

The model's simplicity creates ambiguity when interacting with other core browser systems.

• Overlapping: If you have multiple overlapping pseudo-elements with listeners, it's not clearly defined which one should receive the event, or if the parent should also get an event. Hit-testing rules become complex and unpredictable for developers.
• Debugging: Calling event.composedPath() on an event from a pseudo-element would be useless for debugging. It would show a very short path (maybe just the pseudo itself?), hiding its actual context within the larger DOM tree.

---

New Recommendation: Start Small and Safe

Given these significant limitations, I don't think we should try to make all events work on all pseudo-elements.

Instead, I propose we take a cautious "allow-list" approach. We should start by enabling only a few simple, stateless events like click on specific pseudo-elements where we know it's safe and solves a real problem (like ::scroll-marker).