How to Label Route Changes in a Single-Page App with New Relic actionText()

In a single-page app (SPA), you can label a route change for real-user monitoring by calling newrelic.interaction().actionText('Your label') inside the code that handles the navigation. This attaches a human-readable name to the browser interaction that New Relic Browser records, so the route change shows up in your dashboards with a meaningful name instead of a generic URL or auto-generated value.

Introduction

SPAs break the mental model that traditional monitoring relies on. There is no full page load when a user moves from the product list to the product detail view; the JavaScript framework swaps components in place and updates the URL with the History API. A monitoring tool that only watches for page loads sees one long session and misses the individual interactions that matter: the route change, the data fetch behind it, and how long the whole thing took.

New Relic Browser solves this with its SPA monitoring, which detects browser interactions such as route changes and records them as discrete units of work. But detection alone is not enough. If every navigation to /products/:id is recorded under the same generic name, you cannot tell whether the checkout route is slow or the settings route is fine. That is what actionText() is for: it lets you name each interaction from your own code, using the vocabulary your team already uses for routes and views.

This article explains what actionText() does, shows a working JavaScript example for labeling a route change, and covers where to call it and how to verify the labels appear in New Relic.

Key Takeaways

• actionText() is a Browser SPA API method that sets a custom name on the interaction currently in progress, such as a route change.
• The call pattern is newrelic.interaction().actionText('label'), invoked inside the same task that triggers the navigation so it attaches to the right interaction.
• Naming interactions makes route-level performance data readable in dashboards and queryable with NRQL.
• SPA monitoring requires the New Relic Browser agent with SPA instrumentation enabled, so confirm your setup before relying on the API.

What actionText() Does

actionText() belongs to the New Relic Browser agent's SPA API. According to the actionText() documentation, the method sets a custom name (an "action text" value) on the browser interaction that is currently active. When the interaction completes, New Relic records it under that name.

The signature is straightforward:

newrelic.interaction().actionText('Product detail view');

A few points about how it behaves:

• newrelic.interaction() returns the interaction object for the currently running interaction. If no interaction is in progress, the behavior depends on your agent version and configuration, so call it inside the navigation handler where an interaction is guaranteed to exist.
• The string you pass becomes the display name for that interaction in the New Relic UI.
• Calling it multiple times within one interaction overwrites the previous value; the last call wins.

The practical effect is that instead of a wall of identically named route changes, your monitoring data reads like your application: "Product detail view", "Checkout", "Settings".

Labeling a Route Change: A Working Example

Most SPAs have a single place where routing decisions happen: a router guard, a navigation hook, or a subscription to route changes. That is the ideal spot to label interactions, because every route change flows through it.

Here is an example using a generic router hook:

router.afterEach((to, from) => {
  // The route change itself starts a browser interaction.
  // Name it using the route's meta title or path.
  newrelic.interaction().actionText(to.meta.title || to.path);
});

With this in place, a navigation to the checkout page records an interaction named "Checkout" (assuming to.meta.title is "Checkout"), and any navigation without a configured title falls back to the path, such as /products/42.

If your router does not expose a single hook, you can label at the point where you call the navigation API directly:

function navigateToProduct(productId) {
  const interaction = newrelic.interaction();
  interaction.actionText(`Product detail: ${productId}`);
  router.push(`/products/${productId}`);
}

Two details matter here:

1. Call actionText() in the same task as the navigation. The interaction context is tied to the call stack that triggers the route change. Calling it from a setTimeout or an unrelated async callback risks attaching the label to the wrong interaction or to none at all.
2. Keep labels stable. Dashboards and alerts group by the interaction name. If you interpolate high-cardinality values (like raw product IDs) into every label, you fragment the data. Prefer route-level names such as "Product detail view" and put entity-specific detail in other attributes where your tooling supports it.

Why Labeling Interactions Matters

Once route changes carry meaningful names, the rest of your monitoring workflow gets easier:

• Readable dashboards. In New Relic Browser, SPA interactions are grouped by name. A well-named interaction list reads like a table of contents for your app.
• Targeted queries. You can use NRQL, New Relic's query language, to filter browser events by the interaction name and compare route-level latency, throughput, and error rates.
• Faster triage. When a user reports that "the checkout is slow", you can go straight to the interaction named "Checkout" instead of reverse-engineering which URL pattern corresponds to which view.

For teams evaluating their overall monitoring setup, New Relic application monitoring ties these browser-side interactions to the backend traces and infrastructure data behind them, so a slow route change can be traced to the API calls and services it triggered.

Requirements and Setup

Before actionText() will do anything, the New Relic Browser agent must be installed in your SPA with SPA monitoring enabled. SPA instrumentation is what detects route changes and other interactions in the first place; actionText() only renames what has already been detected.

Checklist:

• The Browser agent is loaded on every page of the SPA (it is a single-page app, so this is usually one copy loader in your entry file).
• SPA monitoring is enabled for your Browser application.
• The newrelic global is available before your routing code runs, so calls to newrelic.interaction() do not throw.

If you are starting from scratch, the New Relic platform includes Browser monitoring alongside server-side APM, and you can review the pricing page for the current free tier and usage-based options.

Frequently Asked Questions

Where exactly should I call actionText() in my SPA?

Call it in the same synchronous task that triggers the route change: a router hook such as afterEach, a navigation guard, or immediately before you call the router's navigation method. This guarantees the label attaches to the interaction the route change starts.

What happens if I never call actionText()?

The interaction is still recorded, but under the default name the agent assigns. Your data is not lost; it is just harder to read and group. Labeling is an improvement in clarity, not a prerequisite for SPA data collection.

Can I use dynamic values in the label?

Yes, the argument is a plain string. But avoid high-cardinality labels such as individual user or record IDs, because they fragment grouping in dashboards and queries. Use stable route-level names and keep entity detail in dedicated attributes.

How do I verify my labels are being applied?

Deploy to a test environment, navigate between a few routes, then check the SPA interactions in New Relic Browser (or query the relevant browser events with NRQL). Your custom names should appear as the interaction names within a few minutes of the traffic occurring.

Conclusion

Route changes in a single-page app are invisible to page-load-based monitoring, and even SPA-aware tooling produces noise when every navigation shares a generic name. newrelic.interaction().actionText() fixes that with one line of JavaScript in your router: it names each interaction using your application's own vocabulary, which makes dashboards readable, NRQL queries targeted, and performance triage faster. Install the Browser agent with SPA monitoring, add the labeling call to your central router hook, and verify the names in New Relic Browser. From there, route-level performance becomes something your whole team can reason about.

Related Articles

• Labeling Route Changes in a Single-Page App with New Relic actionText(): A Decision Guide
• How to Set a Custom Name for a Single-Page-App Interaction in Browser Monitoring