@splunk/visualizations

A visualization is a React component that you can use in an application like Dashboard Studio, add to a custom application using Splunk UI and Unified Dashboard Framework (UDF), or include as a chart in a web page. Because the components are packaged in a library, you can use them in search, dashboards, and many other applications across the Splunk product line. A visualization provides a graphical representation of what can occasionally be complex data, and lets you see the data in a meaningful and structured way. It also helps you to understand the data and provides support for data-driven decision making.

The visualizations library consists of React components built on top of Highcharts and D3.js. If you’re familiar with these libraries, you can build on that knowledge and add tooltips, legends, and data series to a chart. You can choose from more than 20 different visualizations that show data in a variety of formats. If you would like to use Splunk visualizations in your applications, read on to learn more.

Documentation for the Splunk Visualizations library can be found at @splunk/visualizations.

Install

Install @splunk/visualizations

1. Install peer dependencies

   npm install react@^16 react-dom@^16 styled-components@5 @splunk/visualization-context --save
   

2. Install the visualizations package

   npm install @splunk/visualizations
   

Using the Components

In your dashboard presets:

import SingleValue from '@splunk/visualizations/SingleValue';
import SingleValueIcon from '@splunk/visualizations/SingleValueIcon';
import ChoroplethSvg from '@splunk/visualizations/ChoroplethSvg';

export default {
    visualizations: {
        'splunk.singlevalue': SingleValue,
        'splunk.singlevalueicon': SingleValueIcon,
        'splunk.choropleth.svg': ChoroplethSvg,
    },
};

Outside of a dashboard:

import Line from '@splunk/visualizations/Line';

const MyAppWithSplunkLineChart = props => {
    const { dataSource } = props; // see API page for dataSource shape
    return <Line width={600} height={400} dataSources={{ primary: dataSource }} />;
};

Get started with visualizations

You can use UDF to create dashboards with visualizations, or you can work directly with the visualizations library. If you're not familiar with UDF, it is a unified library of UI components that render a dashboard for developers who write JavaScript, and is well suited for Splunk Enterprise and Splunk Cloud Platform apps. For developers, UDF offers:

• two distinct layout systems, as well as custom layout
• search lifecycle management
• inputs for text entry, dropdown, multiselect, timerange, and numbers
• Splunk visualizations to enhance data presentation
• tokens to pass runtime values within a dashboard

To install the UDF library, see the setup guide in the Quick Start. When you have it installed, follow the quick start to install dependencies and learn about using the libraries.

You can also include visualizations in single page apps by using visualizations directly. To use visualizations directly, follow the Splunk UI tutorials to create a component and a simple app. The tutorials will create the app structure for other development.

Install the visualizations libraries and dependencies listed in the Visualizations docs. Some of the packages may have been installed with the Splunk UI setup.

Customize a visualization

A React visualization is reusable bits of code that you can use in an app or dashboard. Each visualization component's documentation includes the following:

• Overview and commonly used configurations
• Examples of how to use various options
• Options available and their respective types and defaults
• Events available and their respective payloads

Examples depict a visualization as it will appear in an app or dashboard. When you click on Show Code, the UI displays the React component code.

Options provide an extensive set of builtin properties that you configure. In React, properties are referred to as props. You can set props programmatically, or use an app to set them. For every visualization, there is a description and a type. In some cases, a prop value is selected from a set of values or an enumeration. In other cases, the author specifies the value of a prop. By setting props, you can change fonts, colors, data sources, or opacity of colors in a chart. Default values exist for most components so you can also leave a prop as is.

Events offer a mechanism to capture user activity on a chart. Activities can include point clicks on a chart or legend, range selection on a chart, as well as events like holding the pointer over a point or moving the pointer away. Each platform visualization has a tab for events that lists the events available for the chart. When an event occurs, such as a point click, the click event captures the data. You can use the data to drill down further by using the data points. For more information, see the Interaction Guide.

Dynamic options syntax (DOS), also referred to as DSL in the docs, exposes even more functionality in charts. A chart that presents text or background display according to a threshold value makes a data presentation more impactful. Dynamic options are a domain-specific language to bind data to options and make data presentation more reflective of changes. The dynamic options syntax consists of data sources, selector functions, and formatters. In the dynamic options syntax, the categories can be combined to create a pipeline. The pipeline begins with a data source, then includes selector functions to extract the data of interest, and formatters to transform and map the data. For more information about dynamic options syntax, see DSL.