@gravity-ui/chartkit

中文文档
8.13.0发布于 2026/11/16MITTypeScriptCommonJS近 30 天下载 3.5万

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

原始使用文档
文档目录21 节
  1. Table of contents
  2. Getting started
  3. Requirements
  4. Install
  5. Styles
  6. Basic usage
  7. SplitTooltip
  8. Updating charting packages
  9. Development
  10. Prerequisites
  11. Setup
  12. Running Storybook
  13. Developing with a local dependency
  14. Running tests
  15. Contributing
  16. License
  17. For AI agents
  18. When to use
  19. When not to use
  20. Common pitfalls
  21. Documentation for AI agents

Gravity UI ChartKit · npm package License CI storybook

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:

Table of contents

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:

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

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.

版本与发布记录

@gravity-ui/chartkit 共发布 351 个版本,首次发布于 2022/10/04;过去 12 个月发布了 112 个版本。

版本发布日期距今
8.13.0latest2026/11/16今天
8.12.12026/11/106 天前
9.0.02026/11/0610 天前
8.12.02026/11/0313 天前
8.11.02026/10/3017 天前
8.10.12026/10/2225 天前

其他发布通道:beta → 4.0.0-beta.7,untagged → 5.23.0。

关于 @gravity-ui/chartkit 的常见问题

@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

如何安装 @gravity-ui/chartkit?

在项目目录运行 npm install @gravity-ui/chartkit,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:react(^16.0.0 || ^17.0.0 || ^18.0.0 || ^19.0.0)、@gravity-ui/uikit(^7.0.0)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@gravity-ui/chartkit 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@gravity-ui/chartkit 支持 ESM 还是 CommonJS?

以 CommonJS 形式发布,可以直接 require();在 ES Module 项目中也可以用 import 引入(Node.js 会把 module.exports 作为默认导出)。

@gravity-ui/chartkit 可以商用吗?

@gravity-ui/chartkit 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@gravity-ui/chartkit 的下载量有多少?

根据 npm 官方下载统计,@gravity-ui/chartkit 在 2026/10/17 – 2026/11/15 这 30 天内被下载 35,114 次,日均约 1,170 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@gravity-ui/chartkit 还在维护吗?

最新版本 8.13.0 发布于 2026/11/16(今天);至今共发布 351 个版本,其中过去 12 个月发布了 112 个;首次发布于 2022/10/04。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。