Skip to content

Click track plugin (Heatmaps) - #1914

Open
eoghanmurray wants to merge 15 commits into
rrweb-io:mainfrom
eoghanmurray:click-track-plugin
Open

Click track plugin (Heatmaps)#1914
eoghanmurray wants to merge 15 commits into
rrweb-io:mainfrom
eoghanmurray:click-track-plugin

Conversation

@eoghanmurray

@eoghanmurray eoghanmurray commented Jul 31, 2026

Copy link
Copy Markdown
Collaborator

Add a click track plugin which generates an additional event for each click (touch or mouse) in addition to the regular rrweb click event.
The regular click event only makes sense in relation to the replay state at the time of the click (viewport position, and the internal-to-rrweb id of the target element), whereas this plugin aims to extract 'semantic' information about the click, with the primary intended use-case being Heatmaps.

The plugin uses a css selector to identify ('triangulate') an element independently of the initial FullSnapshot, without regard to uniqueness on the page. I have developed and separately published the semantic-selector library to generate meaningful css selectors with the intention that the selector is useful longer term (in terms of page lifecycle) and is not overly affected by the current state of the page.

What it does:

  • record pointer type (touch/mouse/pen)
  • when selector is non-unique, record the index and total count of other similar elements
  • sometimes walk up the DOM tree to prefer a more significant target with a href attached (configurable, but e.g. prefer a button instead of an icon inside the button)
  • recursively walk down again to record the original inner target, and in the case of shadowDom, to record the target from within the shadow root
  • record an x/y in percentage terms of the target element only (not the viewport)
  • record aspect ratio of the click target
  • record (a substring of) innerText for a significant element (configurable)

This was originally explored as #503 and #659

This is the first record-only plugin, there is deliberately no replay version as the existing click event covers that, but that is not stopping the plugin events from being made use of in or adjacent to the replayer e.g. for displaying enriched timeline info.

eoghanmurray and others added 15 commits June 22, 2026 19:48
… identify ('triangulate') an element independently of the initial FullSnapshot. See https://github.com/antonmedv/Finder for inspiration on the CSS selector.

 - record relX/relY in terms of the target element as well as the viewport
 - walk up the DOM tree to prefer more significant targets (e.g. prefer a button instead of an icon inside the button)
 - record (a substring of) innerText for a significant element\
 - record hrefs on anchors so we can ensure the underlying anchor hasn't changed when we later match

This was originally explored as rrweb-io#503 and rrweb-io#659
… element, and remove viewport x/y as that isn't really useful given the focus on a particular element. The viewport width at time of click is important for consideration of media queries (at different breakpoints elements might be displayed differently, and you wouldn't want to consider an element specified by a selector to necessarily be 'the same one')
…d to support a significant element vs. the actual element clicked (allowing us to easily record both)
@changeset-bot

changeset-bot Bot commented Jul 31, 2026

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: d18fd2f

The changes in this PR will be included in the next version bump.

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

@eoghanmurray eoghanmurray mentioned this pull request Jul 31, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant