Building your own visualizations for New Relic dashboards enables you and your organization to query data from any source and display it on your dashboard. In this guide, you'll learn how to use the CLI to generate a visualization file structure, run it locally where you can quickly test and iterate, and then deploy it for use in a dashboard.
Before you begin
To get started, make sure you have a New Relic account.
To complete this guide, you need the New Relic One CLI (command line interface). If you haven't already installed it, do the following:
- Install Node.js.
- Complete all the steps in the CLI quick start.
Create a new visualization
In this first set of steps you will use the CLI to quickly generate the boilerplate for a new visualization.
Ensure you're working with the latest version of the New Relic One CLI:
$nr1 update
Start with a new Nerdpack. If you just installed the New Relic One CLI, then you have a new Nerdpack project directory (called something like my-awesome-nerdpack
). If you need to create one, run nr1 create
and select the nerdpack
option.
$nr1 create --type nerdpack --name my-awesome-nerdpack
Tip
Note: If you only want to build a visualization in your Nerdpack, you can remove the nerdlets/
and launchers/
folders from the nerdpack
Navigate to the root of your Nerdpack project and run the nr1 create
command, selecting the visualization
option.
$cd my-awesome-nerdpack$nr1 create --type visualization --name my-awesome-visualization
As a result, you have a new visualization directory matching the name you gave your visualization. It is located in the visualizations
directory in the root of your Nerdpack project.

The files created provide an example visualization – a radar chart populated by a basic NRQL query.
The nr1.json
file provides metadata. The configuration
key in this metadata defines the prop-input fields to be shown in the UI. These are the fields users will fill in to create an instance of the visualization. Supported input types are:
boolean
string
number
json
enum
: a developer-defined list of string options.nrql
: a single NRQL query string.namespace
: a group of input fields to be displayed together under a shared heading in the prop-editing UI.collection
: a repeatable group of input fields to be displayed together under a shared heading in the prop-editing UI. ThenrqlQueries
entry is an example of a collection type.
The index.js
file is where you define the React component that receives the props and renders the visualization. You can install and import any JavaScript libraries you find useful. The example component imports Recharts, a library that wraps D3 submodules for easy-to-compose visualizations.
If your visualization queries data over a time range and you want it to utilize the platform time range setting, you will need to utilize the timeRange
value from PlatformStateContext. The timeRange
can be passed directly to the NrqlQuery component. Setting the NrqlQuery component's pollInterval
prop to NrqlQuery.AUTO_POLL_INTERVAL
automatically handles calculating an appriate data polling interval.
<PlatformStateContext.Consumer> {({timeRange}) => ( <NrqlQuery timeRange={timeRange} pollInterval={NrqlQuery.AUTO_POLL_INTERVAL} > ...
Render the visualization in local development
Now run the generated visualization locally, and view it in Custom Visualizations. There you can quickly test changes to your code.
Start the local Node server for your Nerdpack.
$nr1 nerdpack:serve
Important
To see changes to the nr1.json file take effect, restart the local Node server. Changes to the definition of the configuration field will not show up in the prop configuration side bar of the Custom Visualizations UI until you stop the local Node server and start it back up.
In a browser, open https://one.newrelic.com/?nerdpacks=local. This url is also shown in the terminal when the Node server starts. The nerdpacks=local
query string will direct the UI to load your new visualization artifact from the local Node server.
Advanced nerdpack configuration
See the advanced nerdpack configuration section for detailed information about how your local Node server is proxied to the browser and how you can override webpack configuration if needed.
Open the Apps page, and navigate to Custom Visualizations, which you will find favorited by default.

In the Custom Visualizations listing, find and click on the tile for your visualization. If the tile is not showing up or it is not indicating that it is running locally, restart the Node server and refresh the browser.
When you select your locally running visualization, the visualization hosted by your local Node server is rendered with prop-configuration inputs. Here you can take advantage of the features outlined in the following steps.
You can set prop values and see the visualization update automatically. The prop inputs are listed as defined in the prop definitions located in the nr1.json
file in the visualization folder (for example ./visualizations/my-awesome-visualization/nr1.json
). Fill in values for the props and see the visualization update automatically. As you change props in the sidebar, a render cycle of your visualization's React component is triggered.

Modify the visualization's Javascript code and see the result automatically update in the UI. For example, you can change the value for fillOpacity
on the Radar component in index.js
. Upon save, you will see the page automatically update.
fillOpacity={1.0}
To add more props, you must update the configuration
field in the nr1.json
file for your visualization and restart the local Node server. The props you define in the configuration
field allow New Relic One to cleanly display a prop-editing UI for users interacting with your visualization. See above for more information about the configuration
field.
Deploy and use your visualization
When your visualization is ready to be added to a dashboard, just follow these steps.
Open and follow the guide to publish and deploy the Nerdpack to New Relic One and subscribe accounts to it.
Then you can add your visualization to a dashboard.
Summary
Congratulations on completing the steps in this example! You've learned how to:
- Create a visualization and run it locally
- Quickly test and iterate on visualization code changes in Custom Visualizations
- Deploy a visualization
- Add a custom visualization to a dashboard
Additional resources
- New Relic Quick Tips video: Dashboards and Custom Visualizations (6 minutes)
- New Relic NerdBytes video: Configuring custom visualizations for dashboards (7 minutes)
- New Relic Nerdlog live stream: Custom Data Visualizations on New Relic (30 minutes)