references/elements-chain-format.md
elements_chain format
The elements_chain column stores the clicked DOM element and its ancestors as a single string.
Structure
tag_name.class1.class2:key1="value1":key2="value2";parent_tag.parent_class:key="val"
- Elements are separated by
;(semicolons) - First element is the clicked element, subsequent elements are ancestors up the DOM tree
- Each element starts with
tag_nameoptionally followed by.classsegments (sorted alphabetically) - After the tag/class portion, key-value attributes follow as
:key="value"pairs - Quotes within values are escaped as
\"
Standard attribute keys
| Key | Description |
| ------------- | ------------------------------------------------- |
| text | Inner text content of the element |
| href | Link href attribute |
| attr_id | HTML id attribute |
| nth-child | Position among siblings |
| nth-of-type | Position among siblings of the same type |
| attr_class | CSS classes (also encoded in the .class prefix) |
Custom attributes
Custom DOM attributes appear verbatim in the chain.
The most useful for analytics are data-* attributes:
data-attr— PostHog's default data attribute (configurable per team)data-testid— common testing attribute, also useful for analyticsaria-label— accessibility label, sometimes useful as a selector
Example chain with a data-attr:
button.btn.primary:data-attr="checkout":text="Buy Now";div.container:attr_id="main"
How CSS selectors map to regex
PostHog converts CSS selectors to regex patterns matched against elements_chain:
button→(^|;)button(\.|$|;|:)button.cta→(^|;)button.*?cta.*?#submit→ usesindexOf(elements_chain_ids, 'submit') > 0(optimized)[data-attr="checkout"]→(^|;).*?data-attr="checkout".*?button[data-attr="checkout"]→(^|;)button.*?data-attr="checkout".*?
In HogQL, use elements_chain =~ '{regex}' for matching.