§AIKit ·

UI component library for AI chats built with Atomic Design principles.

§Description

@gravity-ui/aikit is a flexible and extensible React component library for building AI chats of any complexity. The library provides a set of ready-made components that can be used as-is or customized to fit your needs.

§Key Features

• 🎨 Atomic Design — clear component hierarchy from atoms to pages
• 🔧 SDK Agnostic — independent of specific AI SDKs
• 🎭 Two-Level Approach — ready-made components + hooks for customization
• 🎨 CSS Variables — easy theming without component overrides
• 📦 TypeScript — full type safety out of the box
• 🔌 Extensible — custom message type registration system

§Project Structure

src/
├── components/
│   ├── atoms/          # Basic indivisible UI elements
│   ├── molecules/      # Simple groups of atoms
│   ├── organisms/      # Complex components with logic
│   ├── templates/      # Complete layouts
│   └── pages/          # Full integrations with data
├── hooks/              # General purpose hooks
├── types/              # TypeScript types
├── utils/              # Utilities
└── themes/             # CSS themes and variables

§Installation

npm install @gravity-ui/aikit

§Quick Start

import { ChatContainer } from '@gravity-ui/aikit';
import type { ChatType, TChatMessage } from '@gravity-ui/aikit';

function App() {
    const [messages, setMessages] = useState<TChatMessage[]>([]);
    const [chats, setChats] = useState<ChatType[]>([]);
    const [activeChat, setActiveChat] = useState<ChatType | null>(null);

    return (
        <ChatContainer
            chats={chats}
            activeChat={activeChat}
            messages={messages}
            onSendMessage={async (data) => {
                // Your sending logic
                console.log('Message:', data.content);
            }}
            onSelectChat={setActiveChat}
            onCreateChat={() => {
                // Create new chat
            }}
            onDeleteChat={(chat) => {
                // Delete chat
            }}
        />
    );
}

§Architecture

The library is built on Atomic Design principles:

§🔹 Atoms

Basic indivisible UI elements without business logic:

• ActionButton — button with integrated tooltip
• Alert — alert messages with variants
• ChatDate — date formatting with relative dates
• ContextIndicator — token context usage indicator
• ContextItem — context label with remove action
• DiffStat — code change statistics display
• Disclaimer — disclaimer text component
• InlineCitation — text citations
• Loader — loading indicator
• MarkdownRenderer — Yandex Flavored Markdown renderer
• MessageBalloon — message wrapper
• Shimmer — loading animation effect
• SubmitButton — submit button with states
• ToolIndicator — tool execution status indicator

§🔸 Molecules

Simple combinations of atoms:

• BaseMessage — base wrapper for all message types
• ButtonGroup — button group with orientation support
• InputContext — context management
• PromptInputBody — textarea with auto-growing
• PromptInputFooter — footer with action icons and submit button
• PromptInputHeader — header with context items and indicator
• PromptInputPanel — panel container for custom content
• Suggestions — clickable suggestion buttons
• Tabs — navigation tabs with delete functionality
• ToolFooter — tool message footer with actions
• ToolHeader — tool message header with icon and actions

§🔶 Organisms

Complex components with internal logic:

• AssistantMessage — AI assistant message
• Header — chat header
• MessageList — message list
• PromptInput — message input field
• ThinkingMessage — AI thinking process
• ToolMessage — tool execution
• UserMessage — user message

§📄 Templates

Complete layouts:

• ChatContent — main chat content
• EmptyContainer — empty state
• History — chat history

§📱 Pages

Full integrations:

• ChatContainer — fully assembled chat

§Documentation

• Quick Start Guide
• Architecture
• Project Structure
• Testing Guide
• Playwright Guide

§Testing

The project uses Playwright Component Testing for visual regression testing.

§Run tests

Important: All tests must be run via Docker to ensure consistent screenshots across different environments.

# Run all component tests in Docker (recommended)
npm run playwright:docker

# Update screenshot baselines in Docker
npm run playwright:docker:update

# Run specific test by grep pattern in Docker
npm run playwright:docker -- --grep "@ComponentName"

# Clear Docker cache if needed
npm run playwright:docker:clear-cache

§Local testing (Linux only)

If you're on Linux, you can run tests locally:

# Install Playwright browsers (run once)
npm run playwright:install
# Run all component tests
npm run playwright
# Update screenshot baselines
npm run playwright:update

For detailed testing documentation, see Playwright Guide.

§Development

Development and contribution instructions are available in CONTRIBUTING.md.

§License

MIT

§For AI agents

A React component library for building AI chat interfaces, organized by Atomic Design (atoms → molecules → organisms → templates → pages) and SDK-agnostic — reach for it to assemble a chat UI (message lists, prompt input, tool calls, attachments) instead of composing those primitives out of @gravity-ui/uikit by hand.

§When to use

• Building an AI/LLM chat UI (assistant/user/tool messages, prompt input with suggestions, attachment uploads, thinking states).
• Wanting ready-made chat layouts (ChatContainer, MessageList, PromptInput) plus hooks to customize behavior.
• Embedding into the Gravity UI ecosystem with shared theming via CSS variables.

§When not to use

• For general-purpose UI primitives (buttons, inputs, modals), use @gravity-ui/uikit directly — AIKit builds on top of it for chat-specific needs.
• To render rich markdown in messages, AIKit's MarkdownRenderer wraps @gravity-ui/markdown-editor; for standalone markdown rendering use that package directly.
• For a single chat bubble without chat orchestration, a uikit MarkdownRenderer/text block is lighter than the full AIKit message pipeline.

§Common pitfalls

• Hallucinating an AI SDK import — AIKit is SDK-agnostic; it provides components/hooks, not an LLM client. Bring your own data source and feed messages via props.
• Reaching for <Chat> / <AIChat> — the page-level export is ChatContainer (and AIStudioChat); there is no component literally named Chat.
• Skipping message-type registration for custom types — custom message kinds must be registered in the message type system, or they render as unknown.
• Editing base components instead of using hooks — the two-level design expects you to customize via hooks/composition; overriding internals directly breaks upgrades.

§Documentation for AI agents

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