Your data. Anywhere you go.

New Relic for iOS or Android

Download on the App Store    Android App on Google play

New Relic Insights App for iOS

Download on the App Store

Learn more

Close icon

How To: Understand Nerdlet URL state


Understand Nerdlet URL State

Difficulty Level: Intermediate
Products: N/A

Getting Started

For this how-to example, we are going through examples of how you can access the Nerdlet URL state using the nr1 SDK in the applications you build on the New Relic platform.

To get started, we will clone the example applications from our how-to GitHub repo:

Next, we will use the NR1 CLI to update the application UUID and run our application locally. In the terminal, change into the /nr1-howto/understand-url-state directory.

cd /nr1-howto/understand-url-state

Now, we want to update the UUID and serve our application.

nr1 nerdpack:uuid -gf
nr1 nerdpack:serve

Once your app is successfully served, in the terminal, you’ll be provided with a URL to access New Relic One and see your running application.

New Relic One link:

Now on the New Relic homepage, you should have a new launcher to the how-to example.

Understanding the URL state

If you were to copy and paste the URL from the local running how-to example, you should have a long URL that looks something like below:

What a long URL! But, what’s really going on here?

This long hash in the URL contains information about the application’s state. The information stored in the URL is arbitrary and used to be able to point back to the same state that was initially shared.

Encoded into the URL could be information similar to below and more about your application state:

pane = {
  "nerdletId": "understand-url-state",
  "entityDomain": "APM",
  "entityType": "APPLICATION",

Reading the Nerdlet URL state

After getting an understanding of the application URL and the fact that it contains a hash with your application state, we want to be able to store and access data from the Nerdlet URL.

We’ll implement the NerdleStateContext component into our running application and how we can read data stored in the URL. You can find details about the component on the API and components page on

In the text editor of your choice, navigate to the ‘./nr1-howto/understand-url-state/nerdlets/understand-url-state-nerdlet’ and open the index.js file.

In the index.js import the NerdletStateContext component. After importing the NerdStateContext replace the file’s render method with the code below:

render() {
    return (
            {(nerdletState) => {
                console.log('Nerdlet URL State:', nerdletState);
                return null

This application is extending APM and BROWSER applications in New Relic One, access it from one of your services using the entity explorer.

Your Nerdlet’s render method id returning null show your application should be black in your browser but open your browser console and you should see something similar to below:

The nerdletState is logged to your browser console before the app returns null. By default, the entityGuid is decoded from the URL and included in the nerdletState.

Storing data in the Nerdlet URL State

In the last section, you used the NerdletStateContext component to access the data stored in your application’s URL and saw that by default, you’re provided the entityGuid for the service you’ve selected in the Entity Explorer.

Let’s see how more data can be added to your URL state and accessed within the running application.

From the New Relic developer website, we need another platform API component. Import nerdlet into your application. And in your index.js file, inside of the render method just before the return add the following code:

    foo: 'bar',
    fizz: 'buzz',
    cool: true,
    number: 1,

Using the nerdlet.setUrlState() is similar to using React’s setState. It performs a shallow merge between the current URL state and the provided state in the urlState parameter.

The data we added is arbitrary, but if you look at your browser console again, you will see the following:

Showing we can store data in the application URL state and then access it within an application using the NerdletStateContext component.

Navigating and passing URL state

You can also pass data into your URL state while navigating inside your application. We’re going to update the running application to link a second Nerdlet and pass data into the URL.

Update your import statement to match below:

import { PlatformStateContext, NerdletStateContext, navigation, nerdlet, BlockText, Button } from 'nr1';

Add a constructor method to your app and add your account id:

    this.accountId =  '<REPLACE ME WITH YOUR ID>';

Replace your render method with the code below:

render() {
    return (
            {(nerdletState) => {
                console.log('Nerdlet URL State:', nerdletState);
                return <div className="launch-btn">
                        Click this button to launch the Transaction Nerdlet.
                        Launch Transactions App

Go back to the application in your browser, and you will see the screen below. But, if you click the launch button, you will notice it doesn’t take you to the Transactions App.

To navigate to the Transactions Nerdlet, let’s use the navigation platform API. Details about the navigation API can be found on the developer website.

Inside of the render method in the index.js file, add the following line code above the return statement.

const location = navigation.getOpenNerdletLocation(nerdlet);

The navigation.getOpenNerdletLocation will return a location object that can be used by the Button component, but we need to create the nerdlet object being passed. This nerdlet object will direct the button to the Transactions Nerdlet by its id and update the urlState.

const nerdlet = {
    id: 'transactions',
    urlState: {
        facet: 'appName',
        accountId: this.accountId,

Now the location object can be added to the Button component by using its to prop. Update your Button with the code below:


Going back to the application and clicking on the launch button in your browser will now take you to the Transaction Application. Your screen should look similar to below:

Looking at the application on the screen, you will see a transaction overview faceted by App Name. And, if you navigate to ‘./nr1-howto/understand-url-state/nerdlets/transactions/index.js’ you can see how the application is using the NerdletStateContext component to read the data added into the URL state.

How to add the time picker recap

Wrapping up this how-to example, you’ve successfully decoded data from the Nerdlet’s URL state and updated the state with new data using the NerdletStateContext andnerdletPlatform API components. Then using thenavigation.getOpenNerdletLocation` method you linked to a Nerdlet while updating the URL state to be accessed by that Nerdlet.

More detail about the various New Relic Platform APIs and how to use them can be found on the developer website.

To continue your learning, take a look at our self-paced workshop on Github.