HTML variants

usertrax controls HTML element visibility via data attributes. You can test content versions without writing custom show/hide JavaScript.

Overview

The HTML element visibility feature:

Shows/hides elements based on A/B test variants
Handles fallback content when no variant is assigned yet
Works with multiple simultaneous tests
Observes dynamically inserted elements (e.g. in SPAs)
Requires no JavaScript knowledge for the basic case

data-usertrax-ab-test-group must match the test key, and data-usertrax-ab-test-variant must match the variant key from the dashboard.

Data attributes

Attribute	Description	Required
`data-usertrax-ab-test-group`	Unique identifier for the test group (= test key)	Yes
`data-usertrax-ab-test-variant`	The variant this element belongs to	Yes
`data-usertrax-ab-test-fallback`	Mark as fallback (visible until a variant is assigned)	No

<!-- Fallback element (shown by default) -->
<div
  data-usertrax-ab-test-group="pricing-display"
  data-usertrax-ab-test-variant="single-price"
  data-usertrax-ab-test-fallback
>
  <span class="price">$99/month</span>
</div>

<!-- Alternative variant (hidden by default) -->
<div
  style="display: none"
  data-usertrax-ab-test-group="pricing-display"
  data-usertrax-ab-test-variant="price-range"
>
  <span class="price">$89 – $129/month</span>
</div>

Page load: Elements with data-usertrax-ab-test-fallback are visible; other variants stay hidden via display: none.
A/B test load: Once the assignment is ready, the tracker shows only elements for the assigned variant.
Automatic: The tracker handles visibility changes — including after SPA navigation and late-loaded DOM.

Hero and CTA examples

Hero headline
CTA button

<h1
  data-usertrax-ab-test-group="hero_headline"
  data-usertrax-ab-test-variant="control"
  data-usertrax-ab-test-fallback
>
  Track conversions. Without cookies.
</h1>

<h1
  style="display: none"
  data-usertrax-ab-test-group="hero_headline"
  data-usertrax-ab-test-variant="benefit_first"
>
  More attribution. Less banner friction.
</h1>

Both headlines should be meaningful for users and SEO — not keyword spam. See Best practices.

<div
  data-usertrax-ab-test-group="cta_button"
  data-usertrax-ab-test-variant="get_started"
  data-usertrax-ab-test-fallback
>
  <button type="button" data-usertrax="signup" class="btn-primary">
    Get started
  </button>
</div>

<div
  style="display: none"
  data-usertrax-ab-test-group="cta_button"
  data-usertrax-ab-test-variant="free_trial"
>
  <button type="button" data-usertrax="signup" class="btn-primary">
    Start free trial
  </button>
</div>

data-usertrax="signup" makes the click count as a conversion — and the A/B assignment is attached automatically.

Advanced examples

Multiple test groups
Complex layout variations

<!-- Test group 1: Header style -->
<div
  data-usertrax-ab-test-group="header-style"
  data-usertrax-ab-test-variant="minimal"
  data-usertrax-ab-test-fallback
>
  <header class="header-minimal">
    <nav>Home | About | Contact</nav>
  </header>
</div>

<div
  style="display: none"
  data-usertrax-ab-test-group="header-style"
  data-usertrax-ab-test-variant="featured"
>
  <header class="header-featured">
    <nav>Home | About | Contact</nav>
    <div class="announcement">New features available!</div>
  </header>
</div>

<!-- Test group 2: CTA button -->
<div
  data-usertrax-ab-test-group="cta-button"
  data-usertrax-ab-test-variant="primary"
  data-usertrax-ab-test-fallback
>
  <button class="btn-primary">Get started</button>
</div>

<div
  style="display: none"
  data-usertrax-ab-test-group="cta-button"
  data-usertrax-ab-test-variant="secondary"
>
  <button class="btn-secondary">Start free trial</button>
</div>

<!-- Layout variant A: Single column -->
<div
  data-usertrax-ab-test-group="page-layout"
  data-usertrax-ab-test-variant="single-column"
  data-usertrax-ab-test-fallback
>
  <div class="content-single">
    <h1>Welcome</h1>
    <p>Single column layout for better readability.</p>
    <div class="sidebar">Quick links</div>
  </div>
</div>

<!-- Layout variant B: Two column -->
<div
  style="display: none"
  data-usertrax-ab-test-group="page-layout"
  data-usertrax-ab-test-variant="two-column"
>
  <div class="content-two-column">
    <div class="main-content">
      <h1>Welcome</h1>
      <p>Two column layout for more content.</p>
    </div>
    <div class="sidebar">Additional information</div>
  </div>
</div>

Anti-patterns

FOUC without fallback

<!-- Bad: both variants hidden, no fallback → brief empty space -->
<div style="display: none" data-usertrax-ab-test-group="hero" data-usertrax-ab-test-variant="a">
  …
</div>
<div style="display: none" data-usertrax-ab-test-group="hero" data-usertrax-ab-test-variant="b">
  …
</div>

<!-- Good: control visible as fallback until assignment is ready -->
<div
  data-usertrax-ab-test-group="hero"
  data-usertrax-ab-test-variant="a"
  data-usertrax-ab-test-fallback
>
  …
</div>
<div style="display: none" data-usertrax-ab-test-group="hero" data-usertrax-ab-test-variant="b">
  …
</div>

More tips against flicker: Troubleshooting.

Mismatched keys

<!-- Bad: group ≠ test key in dashboard (button_color_test) -->
<div data-usertrax-ab-test-group="buttonColor" …>

<!-- Good: exact same string as test and variant keys -->
<div
  data-usertrax-ab-test-group="button_color_test"
  data-usertrax-ab-test-variant="variant_red"
  …
>

Case and underscores matter. getAssignments() in the console helps you verify the match.

Best practices for HTML element visibility

<!-- Good: Clear and descriptive -->
data-usertrax-ab-test-group="hero-headline-test"

<!-- Avoid: Too generic -->
data-usertrax-ab-test-group="test1"

<!-- Good: Consistent naming pattern -->
data-usertrax-ab-test-variant="variant-control"
data-usertrax-ab-test-variant="variant-treatment"

<!-- Avoid: Inconsistent names -->
data-usertrax-ab-test-variant="control"
data-usertrax-ab-test-variant="treatment_b"

<!-- Always include a fallback element -->
<div
  data-usertrax-ab-test-group="important-content"
  data-usertrax-ab-test-variant="default"
  data-usertrax-ab-test-fallback
>
  <p>Default content visible on first paint</p>
</div>

Troubleshooting HTML element visibility

Element not showing
Multiple elements showing

Check A/B test assignment:

console.log("Current variants:", window.usertrax.getAssignments());

Verify data attributes:

<!-- Ensure group and variant match exactly -->
data-usertrax-ab-test-group="my-test"
data-usertrax-ab-test-variant="my-variant"

Check for duplicate groups:

<!-- Ensure unique group names -->
data-usertrax-ab-test-group="unique-test-name"

Verify variant names:

<!-- Ensure variant names are unique within a group -->
data-usertrax-ab-test-variant="variant-a"
data-usertrax-ab-test-variant="variant-b"

More detail: Troubleshooting.

Integration with other features

CSS variants
Event tracking

<!-- HTML visibility control -->
<div
  data-usertrax-ab-test-group="layout"
  data-usertrax-ab-test-variant="compact"
  data-usertrax-ab-test-fallback
>
  <div class="content-compact">
    <h2>Compact layout</h2>
  </div>
</div>

<!-- CSS from the A/B test config is applied in addition -->
<div
  style="display: none"
  data-usertrax-ab-test-group="layout"
  data-usertrax-ab-test-variant="expanded"
>
  <div class="content-expanded">
    <h2>Expanded layout</h2>
  </div>
</div>

<!-- Elements automatically include A/B test data in conversions -->
<div
  data-usertrax-ab-test-group="cta-style"
  data-usertrax-ab-test-variant="button"
  data-usertrax-ab-test-fallback
>
  <button data-usertrax="signup" class="btn-primary">Sign up</button>
</div>

<div
  style="display: none"
  data-usertrax-ab-test-group="cta-style"
  data-usertrax-ab-test-variant="link"
>
  <a href="#" data-usertrax="signup" class="btn-link">Sign up</a>
</div>