@gravity-ui/components

中文文档
5.0.0发布于 2026/10/24MITTypeScriptESM + CJS近 30 天下载 5.8万

A set of complex React components built on top of @gravity-ui/uikit. Part of the Gravity UI design system.

原始使用文档
文档目录13 节
  1. Install
  2. Usage
  3. Migrating to UIKit 8
  4. Confirmation dialog
  5. More examples
  6. Development
  7. Contributing
  8. License
  9. For AI agents
  10. When to use
  11. When not to use
  12. Common pitfalls
  13. Documentation for AI agents

@gravity-ui/components · npm package CI storybook

A set of complex React components built on top of @gravity-ui/uikit. Part of the Gravity UI design system.

Install

npm install @gravity-ui/components

Usage

@gravity-ui/uikit 8 and React 18/19 are required. Install the current UIKit 8 prerelease with npm install @gravity-ui/uikit@beta.

@gravity-ui/uikit is a peer dependency: install it, import its styles once at the app entry point, and wrap the app in Provider. The components in this package render unstyled without that setup.

import {Provider, TextInput} from '@gravity-ui/uikit';
import {FormRow} from '@gravity-ui/components';
import '@gravity-ui/uikit/styles/fonts.css';
import '@gravity-ui/uikit/styles/styles.css';

export function App() {
  return (
    <Provider theme="light">
      <FormRow label="Name" fieldId="name">
        <TextInput id="name" name="name" />
      </FormRow>
    </Provider>
  );
}

Migrating to UIKit 8

  • Replace the application-level ThemeProvider with Provider.
  • Use onOpenChange instead of onClose in ConfirmDialog and ChangelogDialog. ConfirmDialog accepts the new Dialog props, including maxWidth and fullWidth instead of size.
  • Remove disableHeightTransition from ChangelogDialog and cookie consent popup settings; UIKit no longer animates content height.
  • Stories and StoriesGroup keep onClose, with optional event/reason arguments and UIKit 8 reasons (escape-key, outside-press, click).
  • Pass native HTML attributes directly to button/link props, including StoreBadge, instead of extraProps. Use UIKit 8 Button views in custom story actions.

See the UIKit 8 migration guide for the underlying API changes. This package uses the new List, Menu, and Popover APIs without the legacy entry point.

Confirmation dialog

import {ConfirmDialog} from '@gravity-ui/components';

<ConfirmDialog
  open={open}
  title="Delete the project?"
  message="This cannot be undone."
  textButtonApply="Delete"
  textButtonCancel="Cancel"
  onClickButtonApply={handleDelete}
  onClickButtonCancel={() => setOpen(false)}
  onOpenChange={setOpen}
/>;

More examples

Every component has a README next to its source with props and examples — see src/components/<Component>/README.md. Live demos: Storybook.

Development

git clone [email protected]:gravity-ui/components.git
cd components
npm ci
npm run start   # launches Storybook at http://localhost:7009

Other useful commands:

npm test              # run unit tests
npm run lint          # lint JS and SCSS
npm run typecheck     # TypeScript type-check

Contributing

Contributions are welcome! Please read CONTRIBUTING.md before submitting a pull request.

License

Distributed under the MIT License. See LICENSE for details.

For AI agents

The composite-component layer of Gravity UI — ready-made form rows, confirmation dialogs, notifications, stories, galleries and similar product-level widgets assembled from @gravity-ui/uikit primitives, so you do not rebuild them by hand.

When to use

  • Form layout: FormRow (label + field + description) instead of a hand-made label/input wrapper.
  • Confirmation flows: ConfirmDialog instead of composing Dialog with two buttons yourself.
  • Product widgets: Notifications, Stories / StoriesGroup, ChangelogDialog, OnboardingMenu, PromoSheet, CookieConsent, Reactions, SharePopover, StoreBadge.
  • Data helpers: InfiniteScroll, ItemSelector, DelayedTextInput, TokenizedInput, Gallery.

When not to use

Common pitfalls

  • Nothing is styled without uikit setup. Install @gravity-ui/uikit, import @gravity-ui/uikit/styles/styles.css (plus fonts.css) once, and wrap the app in Provider — this package ships no global styles of its own.
  • FormRow does not render the input. Pass the control as children and link it with fieldId matching the control's id; the label prop is the label text, not a <label> element.
  • ConfirmDialog has no onConfirm / onCancel. The handlers are onClickButtonApply and onClickButtonCancel, and textButtonApply / textButtonCancel are required.
  • Hallucinated imports. Everything is exported from the package root: import {FormRow} from '@gravity-ui/components'. There are no subpath imports like @gravity-ui/components/FormRow.

Documentation for AI agents

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

版本与发布记录

@gravity-ui/components 共发布 127 个版本,首次发布于 2023/03/15;过去 12 个月发布了 15 个版本。

版本发布日期距今
5.0.0latest2026/10/2424 天前
4.24.12026/10/121 个月前
4.24.02026/08/202 个月前
4.23.12026/08/043 个月前
4.23.02026/07/144 个月前
4.22.02026/06/165 个月前

其他发布通道:beta → 4.0.0-beta.5,untagged → 3.15.1。

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

@gravity-ui/components 是什么?

A set of complex React components built on top of @gravity-ui/uikit. Part of the Gravity UI design system.

如何安装 @gravity-ui/components?

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

@gravity-ui/components 支持 TypeScript 吗?

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

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

同时提供 ES Module 与 CommonJS 入口,import 和 require() 都可以使用,打包工具会自动选择合适的版本。

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

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

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

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

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

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