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

Read more:

• 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

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

• Layout components and spacings
• Theming, Colors & Branding
• Typography
• Migration to v8

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.