Gravity UI ChartKit ·

Plugin-based React component that renders charts from multiple charting libraries, such as Gravity Charts and Yagr, through a single ChartKit API, with mobile-friendly tooltips and custom plugin support. You register one or more plugins and render charts via <ChartKit type="..." data={...} /> — ChartKit dispatches to the correct renderer automatically.

Each plugin renderer is lazy-loaded, so the underlying library code is only downloaded when ChartKit is actually rendered in the UI. ChartKit also handles mobile-friendly tooltip display out of the box. You can use the built-in plugins or implement your own.

When to use:

• You need modern declarative charts (gravity-charts) or time-series / monitoring charts (yagr)
• You need multiple chart types under a single consistent API
• You want charts that follow the same light/dark theme as the rest of your UI out of the box

When not to use:

• You only need one specific chart library — prefer using @gravity-ui/charts directly

Table of contents

• Get started
• Updating charting packages
• Development

Getting started

Requirements

• React 16, 17, or 18
• @gravity-ui/uikit — required peer dependency (provides theming and UI primitives)

Install

npm install @gravity-ui/chartkit @gravity-ui/uikit

Styles

Import the styles from @gravity-ui/uikit in your entry point:

import '@gravity-ui/uikit/styles/fonts.css';
import '@gravity-ui/uikit/styles/styles.css';

For full setup details see the uikit styles guide.

Basic usage

ChartKit uses a global plugin registry. Call settings.set once at your app entry point to register the plugins you need. When <ChartKit type="..." /> renders, it looks up the matching plugin — if none is found, an error is thrown. Each plugin's renderer is a React.lazy component, so its code is fetched only when ChartKit first appears in the UI.

You can register multiple plugins at once:

settings.set({plugins: [GravityChartsPlugin, YagrPlugin]});

Or call settings.set multiple times — it merges the plugin list rather than replacing it.

Basic example:

import {ThemeProvider} from '@gravity-ui/uikit';
import ChartKit, {settings} from '@gravity-ui/chartkit';
import {GravityChartsPlugin} from '@gravity-ui/chartkit/gravity-charts';

import '@gravity-ui/uikit/styles/fonts.css';
import '@gravity-ui/uikit/styles/styles.css';

settings.set({plugins: [GravityChartsPlugin]});

const data = {
  series: {
    data: [
      {
        type: 'line',
        name: 'Series',
        data: [
          {x: 0, y: 10},
          {x: 1, y: 25},
          {x: 2, y: 18},
          {x: 3, y: 30},
        ],
      },
    ],
  },
};

export default function App() {
  return (
    <ThemeProvider theme="light">
      <div style={{height: 300}}>
        <ChartKit type="gravity-charts" data={data} />
      </div>
    </ThemeProvider>
  );
}

ChartKit adapts to its parent's size — make sure the container has an explicit height.

SplitTooltip

The split-pane tooltip layout that gravity-charts uses on touch devices (tooltip={{splitted: true}}) is also available as a standalone component. It works with any content: it renders the main pane and the tooltip pane side by side (or stacked, depending on the container size) with a draggable resizer between them.

import {SplitTooltip} from '@gravity-ui/chartkit';

export function Panel() {
  return (
    <div style={{height: 400}}>
      <SplitTooltip
        renderMainPane={() => <MyVisualization />}
        renderTooltip={() => <MyTooltipContent />}
      />
    </div>
  );
}

See the SplitTooltipProps type for layout control, pane sizing and resizer options.

Updating charting packages

ChartKit bundles two Gravity UI charting libraries as dependencies:

• @gravity-ui/charts — powers the gravity-charts plugin
• @gravity-ui/yagr — powers the yagr plugin

If you need a newer version of one of these packages, open a Package update request issue and select the package(s) you need. Maintainers will bump the selected packages and release the update.

Development

Prerequisites

• Node.js 22 (see .nvmrc)
• npm 10 or later

Setup

Clone the repository and install dependencies:

git clone https://github.com/gravity-ui/ChartKit.git
cd ChartKit
npm ci

Running Storybook

npm run start

Storybook will be available at http://localhost:7007.

Developing with a local dependency

To work on a dependency (e.g. @gravity-ui/charts) and see your changes live in Storybook without publishing to npm:

1. Link the local package

# In your local clone of @gravity-ui/charts:
git clone https://github.com/gravity-ui/charts.git
cd charts
npm ci
# make your changes
npm run build
npm link

# In ChartKit:
npm link @gravity-ui/charts

2. Configure local package watching

Create a .env.local file in the ChartKit root (it is gitignored):

LOCAL_PKG=@gravity-ui/charts

This tells Vite to watch that package in node_modules and skip pre-bundling it. After rebuilding @gravity-ui/charts, Storybook will hot-reload automatically.

For multiple packages, use a comma-separated list:

LOCAL_PKG=@gravity-ui/charts,@gravity-ui/uikit

3. Start Storybook

npm run start

4. Restore the original package

When you're done:

1. Comment out LOCAL_PKG in .env.local
2. Run npm install in ChartKit — it replaces the symlink with the registry version

# In ChartKit:
npm ci

Running tests

npm test

Visual regression tests run in Docker to ensure consistent screenshots across environments:

npm run test:docker

To update the reference screenshots after intentional UI changes:

npm run test:docker:update

Contributing

Please refer to the contributing guide before submitting a pull request.

License

Distributed under the MIT License. See LICENSE for details.

For AI agents

A plugin-based React component that renders charts from multiple charting libraries, such as Gravity Charts and Yagr, through a single <ChartKit type="..." data={...} /> API, lazy-loading each library only when its chart type is rendered.

When to use

• Rendering more than one charting engine behind one consistent component: gravity-charts (declarative SVG charts via @gravity-ui/charts) and yagr (uPlot-based time-series via @gravity-ui/yagr).
• Lazy-loading chart bundles — each plugin's renderer is React.lazy, so a library's code is only fetched when its chart type is actually shown.
• Mobile-friendly tooltips out of the box — the chart and its tooltip are shown in resizable split panes instead of a hover popup; for gravity-charts turn it on with <ChartKit type="gravity-charts" tooltip={{splitted: true}} />.
• Using the split-pane tooltip layout on its own — SplitTooltip is a standalone component exported from the root entry: pass renderMainPane and renderTooltip, and it lays them out as resizable panes (vertical or horizontal, picked from the container size) for any content, not only ChartKit charts.
• Writing your own plugin — register {type, renderer} via settings.set({plugins: [...]}), where renderer is a React.lazy component; ChartKit dispatches to it by type exactly like to the built-in plugins.
• Consistent light/dark theming across every chart engine out of the box — the charts follow the @gravity-ui/uikit theme of the surrounding app.

When not to use

• For a single chart type only, import @gravity-ui/charts (general) or @gravity-ui/yagr (high-performance time-series) directly — the plugin registry is overhead for one engine.
• To compose a dashboard grid of widgets, use @gravity-ui/dashkit — ChartKit renders a chart; DashKit arranges many widgets.

Common pitfalls

• Rendering <ChartKit> before settings.set({plugins: [...]}) — the global plugin registry must be populated at app entry; an unregistered type throws at render time.
• Hallucinated prop chartType / library — the dispatch prop is type (e.g. type="gravity-charts"), and the data is data.
• Importing plugins from the root entry — plugins live in subpath exports (e.g. @gravity-ui/chartkit/gravity-charts, @gravity-ui/chartkit/yagr); the root @gravity-ui/chartkit entry does not re-export them.
• Assuming one data shape for every type — the shape depends on the plugin, e.g. gravity-charts takes ChartData from @gravity-ui/charts ({series: {data: [...]}}), while yagr takes {data: {graphs, timeline}, libraryConfig} with libraryConfig required.
• Forgetting a container height — ChartKit fills its parent; without an explicit height on the wrapper, the chart collapses to zero.
• Missing the uikit styles import — theming depends on @gravity-ui/uikit/styles/styles.css; without it, charts render unstyled.

Documentation for AI agents

Agent-readable documentation for the installed version is located in node_modules/@gravity-ui/chartkit/build/docs/INDEX.md.