QueriesKit ·

React component library for building query pages — history, tutorials, editors, and related UI. Part of the Gravity UI design system.

Install

npm install @gravity-ui/querieskit

Peer dependencies

Your project must also provide:

• react / react-dom (^18 or ^19)
• @gravity-ui/uikit (>=7)
• @gravity-ui/icons (>=2)

See peerDependencies in package.json for the exact ranges.

Setup

QueriesKit builds on UIKit theming and styles. At the app entry point:

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

Wrap the app in ThemeProvider:

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

createRoot(document.getElementById('root')).render(
  <ThemeProvider theme="light">
    <App />
  </ThemeProvider>,
);

See UIKit docs for theming and i18n setup.

Architecture

The public API has three levels:

Level	Path	Role
Widgets	src/widgets	Ready-to-use feature blocks for a queries page
Modules	src/modules	Scenario blocks composed from components (lists, rows, headers)
Components	src/components	Small reusable UI pieces with a stable props contract

Import direction is one-way: widgets → modules → components.

Prefer widgets for product screens. Use modules and components when you need a custom layout or only a part of a scenario.

Usage

Widget imports

All six widgets support both root and individual imports:

import {SavedQueries} from '@gravity-ui/querieskit';

Alternatively, start directly from the widget's entrypoint:

import {SavedQueries} from '@gravity-ui/querieskit/widgets/SavedQueries';
import type {SavedQueriesProps} from '@gravity-ui/querieskit/widgets/SavedQueries';

Individual entrypoints are available for QueriesHistory, SavedQueries, TutorialsHistory, QueriesNavigation, QueryResults, and DashboardCharts. They expose each widget's existing public exports, including its props and helpers. Shared data types remain available from the package root.

Individual imports limit the dependency graph the bundler needs to traverse. Both forms support tree-shaking with an ESM-aware bundler; individual imports do not necessarily produce a smaller bundle. Existing root imports remain supported. Keep CSS processing enabled so that the selected widget's styles are included. Some bundlers, including esbuild, retain CSS from unused root re-exports even when their JavaScript is removed. Individual widget imports avoid introducing those unrelated styles.

QueriesHistory

Ready-made query history sidebar: search, filters, editable titles, row actions, and optional compare mode.

import {useState} from 'react';
import {QueriesHistory} from '@gravity-ui/querieskit';
import type {QueryHistoryItem, QueryHistoryRow} from '@gravity-ui/querieskit';

const items: QueryHistoryItem<QueryHistoryRow>[] = [
  {header: 'Today', height: 28},
  {
    id: 1,
    title: 'My query',
    status: 'completed',
    engine: 'YQL',
    startTime: Date.now() - 60_000,
    endTime: Date.now(),
    query: 'SELECT 1',
    height: 52,
  },
];

function HistoryPanel() {
  const [search, setSearch] = useState({value: '', fullSearch: false});

  return (
    <QueriesHistory
      title="History"
      items={items}
      search={{
        value: search.value,
        fullSearch: search.fullSearch,
        hasClear: true,
        onUpdate: setSearch,
      }}
      onListItemClick={(item) => {
        if ('id' in item) {
          // open query by id
        }
      }}
    />
  );
}

TutorialsHistory

Same layout pattern for tutorial lists — search, optional filters, and selectable rows.

import {TutorialsHistory} from '@gravity-ui/querieskit';

Browse interactive examples in Storybook.

Widgets

Widget	Description
QueriesHistory	Query history with search, filters, visible fields, editing, and comparison
TutorialsHistory	Tutorials list with search and filters

Development

git clone git@github.com:gravity-ui/querieskit.git
cd querieskit
npm ci
npm run storybook   # http://localhost:6006

Useful scripts:

npm run build            # library build
npm run lint:all         # ESLint
npm run build-storybook  # static Storybook

Contributing

Please read CONTRIBUTING.md before opening a pull request.

License

MIT — see LICENSE.