Data Attributes
We tag elements in the platform with data- attributes so they can be selected reliably, without depending on class names, DOM structure or copy that may change.
These attributes are used by two tools:
- Cypress E2E tests - to find and interact with elements during a test.
- PostHog reporting - to identify elements captured by Autocapture, and to build PostHog Actions from them.
Attribute Types
data-nav- Tag elements that have a sole purpose of moving a user from one place to another. This is used for any navigation item in a side bar, tab or any of the primary navigation dropdown menus for switching team or user options.data-form- Identify particular form elements like text-input, textarea or dropdowns using this tag.data-action- Used to identify buttons that do not navigate, but instead complete an action. This could include submitting a form, or opening a dialog.data-el- A catch all for everything else, an element that we're likely going to want to capture, but doesn't fit into any of the other categories.
Naming Structure
We use hierarchical querying in both E2E test and PostHog queries. This means that you can name a parent eleemnt and a child element in isolation and use a nested query to fetch the specific element you want, e.g.
[data-el="header"] [data-action="header.notifications-btn"]
Would select the button with the data-action="header.notifications-btn" attribute inside the element with the data-el="header" attribute. As such, convention is that each element is named ins isolation of it's context, just name the element based on it's own reason for existence, e.g. "add-vendor".
An example would be:
<button data-action="add-vendor">...</button>
Usage in E2E Tests
Select elements in Cypress by their data- attribute rather than by class or text:
cy.get('[data-action="add-vendor"]').click()
If there are multiple buttons or elements with the sme data attribute, you can use a nested query to select the specific element you want, e.g.
cy.get('[data-el="header"]').get('[data-action="add-vendor"]').click()
See Testing for how to run and write E2E tests.
Usage in PostHog
PostHog Autocapture records the relevant data- attributes on any element a user interacts with. Because the names are stable, we can filter events and define PostHog Actions against them, knowing that refactoring a component's markup won't silently break our reporting.
See Platform Ops for how we use PostHog across the platform.

