Installation

To use the visualizations components, you need to install the @hitachivantara/uikit-react-viz package:

npm install @hitachivantara/uikit-react-viz

pnpm add @hitachivantara/uikit-react-viz

yarn add @hitachivantara/uikit-react-viz

bun add @hitachivantara/uikit-react-viz

Apache ECharts

UI Kit charts are built on Apache ECharts.
For advanced features not covered here, see the Apache ECharts documentation.

Provider

Before using any UI Kit visualizations, wrap your app with the HvVizProvider component to enable theming.
It should be placed near the root of your component tree and must be wrapped by HvProvider, as it relies on the UI Kit theme.

import { HvProvider } from "@hitachivantara/uikit-react-core";
import { HvVizProvider } from "@hitachivantara/uikit-react-viz";
 
const MyApp = ({ children }) => {
  return (
    <HvProvider>
      <HvVizProvider>{children}</HvVizProvider>
    </HvProvider>
  );
};

The HvVizProvider only accepts a children and doesn’t need any extra configuration to work.

Data

The data prop in visualizations supports the columns format:

• Columns format: An object where each key is a column name and its value is an array of values (all arrays must have the same length).

Both examples below represent a table with 3 columns (Month, Sales Target, and Monthly Sales) and 12 rows.

{
    Month: ["January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December"],
    "Sales Target": [5929, 2393, 1590, 7817, 4749, 1702, 2381, 2909, 6732, 3098, 2119, 2146],
    "Monthly Sales": [4563, 1920, 6738, 1832, 7346, 1938, 7261, 1938, 2739, 5729, 9028, 4562]
}

new Map()
  .set("Month", [
    "January",
    "February",
    "March",
    "April",
    "May",
    "June",
    "July",
    "August",
    "September",
    "October",
    "November",
    "December",
  ])
  .set(
    "Sales Target",
    [5929, 2393, 1590, 7817, 4749, 1702, 2381, 2909, 6732, 3098, 2119, 2146],
  )
  .set(
    "Monthly Sales",
    [4563, 1920, 6738, 1832, 7346, 1938, 7261, 1938, 2739, 5729, 9028, 4562],
  );

• Rows format: an array containing a set of objects where each object is a row. Each key-value pair from the row object represent the column name (key) and row value (value).

Example illustrating a table with 3 columns (Country, Population, and Area) and 4 rows.

[
  {
    Country: "Portugal",
    Population: 10.33,
    Area: 92212,
  },
  {
    Country: "Spain",
    Population: 47.42,
    Area: 505990,
  },
  {
    Country: "US",
    Population: 331.9,
    Area: 9834000,
  },
  {
    Country: "Canada",
    Population: 38.25,
    Area: 9984670,
  },
];

• Arquero table format: A table created using the Arquero library, which provides powerful data transformation and query capabilities. UI Kit visualizations support Arquero tables as a valid data format. While we use Arquero internally, not all of its features are exposed—refer to the official documentation for advanced usage.

For instance, if your data is a JSON, you can use Arquero to transform it into a table and pass it to a visualization. The example below creates a table with 2 columns (Country and Population) and 2 rows.

aq.fromJSON('{"Country":["Portugal","Spain"],"Population":[10.33,47.42]}');

For more details, see the Arquero API documentation.

Axis types

For charts with axes, xAxis defaults to categorical and yAxis to continuous.
In horizontal bar charts, these defaults are inverted.

You can change the axis type based on your data:

• continuous – for numeric data
• categorical – for discrete categories
• time – for time series data

Visual roles

To create visualizations, you must define visual roles for your data table columns. Supported roles include:

• groupBy Groups data by the selected columns.
• measures: Specifies numeric columns to be measured. Defaults to sum if no aggregation is provided.
  Supported aggregations: sum, average, min, max, count.
• splitBy: Splits data series based on the selected columns.
• sortBy: Sorts data points by column(s). Defaults to ascending order.
  Sorting options: asc, desc.

Please find below an example with the HvLineChart.

In this example, a data table with 4 columns (Country, Year, Medal, and Total) and 8 rows was used.

To visualize total medals by year:

• groupBy: Year – groups data by year
• measures: Total – measures total medals (default aggregation: sum)
• splitBy: Country – displays one line per country
• sortBy: Year – ensures chronological order since the input wasn’t sorted

Filters

You can filter data points using the filters prop—an array of objects that define which columns and values to filter.

Each filter object supports:

• column: the column name to filter on
• values: an array of values to include

type HvChartFilterOperation =
  | "is"
  | "isNot"
  | "contains"
  | "notContains"
  | "greaterThan"
  | "greaterThanOrEqual"
  | "lessThan"
  | "lessThanOrEqual"
  | "between"
  | "ends"
  | "notEnds"
  | "starts"
  | "notStarts";
 
type HvChartFilter = {
  field: string;
  operation: HvChartFilterOperation;
  value: string | string[] | number | number[];
};

In this HvBarChart example, two filters are applied:

• Country: displays data points for the selected country only
• Sales: filters data points within a selected sales range

<HvBarChart
  data={{
    Country: data.map((item) => item.label),
    Sales: data.map((item) => item.value),
  }}
  groupBy="Country"
  measures="Sales"
  filters={[
    {
      field: "Country",
      operation: "is",
      value: country,
    },
    {
      field: "Sales",
      operation: "between",
      value: [sales[0], sales[1]],
    },
  ]}
/>