NexusUI Echarts Utility

This package includes custom NexusUI themes for Apache Echarts as well as several related utilities to simplify your charting experience.

• We provide two themes, light and dark theme, Our themes include styles for:
  • Layout (title, axis, grid, legend) * Layout (title / axis/ grid /legend position and space)
  • Axes (label, line, ticks)
  • Color Palette (default sequence colors)
• Utilities
  • Custom Tooltips formatters
  • Custom Zoom (Not yet)

Installation

Add the required dependencies to your project:

# With yarn
yarn add echarts echarts-for-react @nexusui/echarts-utility

# With npm
npm install echarts echarts-for-react @nexusui/echarts-utility

If your project does not already contain the MUI components and NexusUI theme, you must also install @mui/material and @nexusui/theme.

Usage

Basic usage

The ReactEChartsWithTheme component automatically handles theming for both light and dark themes, so you only need to configure the other echarts related props.

import { ReactEChartsWithTheme } from '@nexusui/echarts-utility';
import * as echarts from 'echarts';

// option for echarts
const option = {
  xAxis: {
    type: 'category',
    data: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun']
  },
  yAxis: {
    type: 'value'
  },
  series: [
    {
      data: [150, 230, 224, 218, 135, 147, 260],
      type: 'line'
    }
  ]
};

export default () => {
  return <ReactEChartsWithTheme echarts={echarts} option={option} />
}

Minimal bundle usage

If your project only uses a few chart types, you can reduce your overall bundle size by only importing the specific modules you need.

import { ReactEChartsWithTheme } from '@nexusui/echarts-utility';
import * as echarts from 'echarts/core';
import { TitleComponent, TooltipComponent, GridComponent, LegendComponent, ToolboxComponent } from 'echarts/components';
import type {
  TitleComponentOption,
  TooltipComponentOption,
  GridComponentOption,
  LegendComponentOption,
  ToolboxComponentOption
} from 'echarts/components';
import { LineChart } from 'echarts/charts';
import type { LineSeriesOption } from 'echarts/charts';
import { UniversalTransition } from 'echarts/features';
import { CanvasRenderer } from 'echarts/renderers';

// Register the required components, it will generate minimal bundle
echarts.use([
  TitleComponent,
  TooltipComponent,
  GridComponent,
  LegendComponent,
  LineChart,
  CanvasRenderer,
  UniversalTransition,
  ToolboxComponent
]);

// Combine an Option type with only required components and charts via ComposeOption
type ECOption = echarts.ComposeOption<
  TitleComponentOption | TooltipComponentOption | GridComponentOption | LegendComponentOption | LineSeriesOption | ToolboxComponentOption
>;

// option for echarts
const option: ECOption = {
  title: {
    text: 'Sample Line chart',
  },
  toolbox: {
    show: true,
    feature: {
      dataView: {},
      saveAsImage: {}
    },
  },
  tooltip: {
    trigger: 'axis',
  },
  xAxis: {
    type: 'category',
    data: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun']
  },
  yAxis: {
    type: 'value'
  },
  series: [
    {
      data: [150, 230, 224, 218, 135, 147, 260],
      type: 'line'
    }
  ]
};

export default () => {
  return <ReactEChartsWithTheme echarts={echarts} option={option} />
}

Custom Tooltips formatter

Usage

import { getLineTooltipFormatter } from '@nexusui/echarts-utility';

export const options = {
  // tooltip config options
  tooltip: {
    formatter: getLineTooltipFormatter({ xAxisTitle: 'Strain / mm/mm', yAxisTitle: 'Stress / MPa' })
  },
  //...other options
};

You can also use a param mapper to show the values you want in the tooltip

import { getTooltipFormatter } from '@nexusui/echarts-utility';
import type { TooltipFormatterDataParams } from '@nexusui/echarts-utility';
const paramMapper = (param: TooltipFormatterDataParams) => {
  return {
    seriesColor: param.color,
    seriesName: param.seriesName,
    xAxisValue: param.value[0],
    yAxisValue: param.value[2]
  };
};

const additionalParams = { xAxisTitle: 'Strain / mm/mm', yAxisTitle: 'Stress / MPa' }
export const options = {
  // tooltip config options
  tooltip: {
    formatter: getTooltipFormatter(paramMapper,additionalParams)
  },
  //...other options
};

If you need further configuration abilities, you can use the axisDict attribute as follows. The keys of axisDict are items like axisTitle and the values of axisDict are things like axisValue.

import { getTooltipFormatter } from '@nexusui/echarts-utility';
import type { TooltipFormatterDataParams } from '@nexusui/echarts-utility';
const paramMapper = (param: TooltipFormatterDataParams) => {
  return {
    seriesColor: param.color,
    seriesName: param.seriesName,
    axisDict: {
      [param.name]: `${param.value}(${param.percent}%)`
    }
  };
};
export const options = {
  // tooltip config options
  tooltip: {
    formatter: getTooltipFormatter(paramMapper)
  },
  //...other options
};