UIKit ·

English | Русский

A set of flexible, highly practical, and efficient React components for creating rich web applications. Part of the Gravity UI design system.

Website Documentation Figma Themer Storybook Community

About

UIKit is the foundational package of the Gravity UI design system — a battle-tested set of 70+ React components built for production web applications. It handles the hard parts: theming, accessibility, RTL layout, server-side rendering, and internationalization, so you can focus on building your product.

Key features:

70+ components — inputs, overlays, data display, layout primitives, feedback, and more
Built-in theming — light, dark, and high-contrast variants with a live Themer tool to customize tokens
RTL support — full right-to-left layout direction

Browse the full component catalog in Storybook or the documentation.

Getting Started

Prerequisites

React 18 or 19 must be installed in your project.

Installation

npm install @gravity-ui/uikit

Usage

Import components directly from the package:

import {Button} from '@gravity-ui/uikit';

const SubmitButton = (
  <Button view="action" size="l">
    Submit
  </Button>
);

Styles

Include the base styles and fonts once at the top of your app entry point:

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

A SCSS mixins file with useful helpers is also available for use in your own stylesheets.

Guides

Migration to v8 — the breaking changes of v8 and the way through each of them
Layout components and spacings — compose responsive pages with the shared grid and spacing scale
Theming — enable light, dark, and high-contrast themes
Typography — use and customize the shared text scale
Server-side rendering — generate the root CSS class on the server
Internationalization — set the built-in component language

Entry points

Entry point	What is there	When to use
`@gravity-ui/uikit`	Components, hooks and utilities	Always — this is the package
`@gravity-ui/uikit/styles/*`	The global CSS and the SCSS mixins	Once at the entry point of the app, see Styles
`@gravity-ui/uikit/i18n`	`addLanguageKeysets`, `addComponentKeysets`	Adding or overriding the built-in component strings
`@gravity-ui/uikit/server`	`getRootClassName`	Generating the root class on the server, see SSR
`@gravity-ui/uikit/toaster-singleton`	A ready-made `Toaster` instance	Showing toasts outside of the React tree
`@gravity-ui/uikit/virtualizer`	`Virtualizer`, `ListVirtualizer`	Rendering only the visible window of a long list
`@gravity-ui/uikit/hello-pangea-dnd`	`ListHelloPangeaDnd`, `useListHelloPangeaDnd`	Reordering the rows of a list with `@hello-pangea/dnd`
`@gravity-ui/uikit/unstable`	Components whose API is still moving	At your own risk — these break outside of major releases
`@gravity-ui/uikit/legacy`	`DropdownMenu`, `List`, `Menu`, `Table`, `TableColumnSetup`	Only while migrating away from them, see Migration to v8

Some entry points need packages of their own, declared as optional peer dependencies: install them next to @gravity-ui/uikit when you import from there. Everything else comes with the package itself.

Entry point	What to install
`@gravity-ui/uikit/virtualizer`	`@tanstack/react-virtual`
`@gravity-ui/uikit/hello-pangea-dnd`	`@hello-pangea/dnd`
`@gravity-ui/uikit/legacy`	`@hello-pangea/dnd`, `react-window`, `react-virtualized-auto-sizer`

Development

Use Node.js 24 or newer and npm 11 or newer for development.

git clone git@github.com:gravity-ui/uikit.git
cd uikit
npm ci
npm run start   # launches Storybook at http://localhost:7007

Other useful commands:

npm test              # run unit tests
npm run lint          # lint JS, SCSS, and Markdown
npm run typecheck     # TypeScript type-check
npm run playwright    # run visual regression tests

Maintainers

_@amje

_@ValeraS

_@korvin89

Contributing

Contributions are welcome! Please read CONTRIBUTING.md before submitting a pull request. For detailed PR guidelines see contribute/pull-request.md.

We have contributors and counting — join us!

Join the community on Telegram for questions and discussion.

License

Distributed under the MIT License. See LICENSE for details.

For AI agents

The base React component and design-token library for Gravity UI apps — controls, inputs, overlays, layout, and theming that every other @gravity-ui package builds on.

When to use

Standard application UI: buttons, form controls, modals and popups, menus, tabs, labels, typography, and layout primitives.
Selectable, navigable lists (List) and select controls (Select).
The theming foundation of a Gravity UI app: Provider, design tokens, and CSS variables the rest of the @gravity-ui/* ecosystem expects to be present.

When not to use

Tables and data grids (selection, sorting, virtualization, column resizing, grouping, reordering) — use @gravity-ui/table, a separate headless package. The Table component of uikit lives in @gravity-ui/uikit/legacy since v8 and is kept only for existing code.
Charts and data visualization — use @gravity-ui/charts (@gravity-ui/chartkit is the legacy wrapper).
Application navigation shells (aside header, footer, logo) — use @gravity-ui/navigation.
Date pickers, calendars, and range controls — use @gravity-ui/date-components.
The SVG icon set itself — use @gravity-ui/icons; uikit only ships the Icon renderer.

Common pitfalls

Button styling prop is view, not variant or color
Components render unstyled without setup. Wrap the app in Provider and import @gravity-ui/uikit/styles/styles.css (plus fonts.css) once at the entry point — both are required.
Icon has no name prop. Pass an imported icon component through data: import {Gear} from '@gravity-ui/icons'; <Icon data={Gear} size={16} />.
theme values are light | dark | light-hc | dark-hc | system. system (the default) follows the OS preference and resolves to light or dark. There is no theme="default".
List in v8 is a new component. The v7 List lives in @gravity-ui/uikit/legacy; see the List migration guide.

Useful docs

Documentation for AI agents

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

Star History

If you find UIKit useful, please consider giving it a ⭐ on GitHub — it helps others discover the project.