# @gravity-ui/aikit documentation

Documentation for the **installed** version of `@gravity-ui/aikit`.
Your training data may be outdated — these files are the source of truth.

Paths are relative to this file (`node_modules/@gravity-ui/aikit/build/docs/`).

## 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`](https://gravity-ui.com/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`](https://github.com/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.

## Install

```bash
npm install @gravity-ui/aikit
```

## Usage

```typescript
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
            }}
        />
    );
}
```

## Guides

- [Adding a New Component](./guides/guidelines/new-component.md) — A checklist for everything that must be wired up when creating a new component inside src/components/<level>/<Name>/. Missing any of these makes the component invisible to consumers, breaks tree-shaking, or fails CI.
- [AIKit Library Architecture](./guides/ARCHITECTURE.md)
- [AIKit Project Structure](./guides/PROJECT_STRUCTURE.md) — This document describes the layout of the @gravity-ui/aikit source tree.
- [Code Style and Language Requirements](./guides/guidelines/code-style.md) — CRITICAL: All code documentation, comments, and JSDoc must be written in English.
- [Components](./guides/COMPONENTS.md) — 49 components organized by Atomic Design level. Each component lives in src/components/<level>/<Name>/ and ships with its own README and Storybook stories.
- [Documentation](./guides/README.md) — This directory contains all @gravity-ui/aikit documentation.
- [Examples](./guides/EXAMPLES.md) — Practical patterns for common AIKit integrations.
- [Generative UI (toolset)](./guides/GENUI.md)
- [Hooks](./guides/HOOKS.md) — AIKit exports 8 public hooks. All are re-exported from the package root and from the @gravity-ui/aikit/hooks subpath.
- [Internationalization (i18n)](./guides/I18N.md) — AIKit localizes user-facing strings on a per-component basis using @gravity-ui/i18n. There is no global i18n provider — each component bundles its own keyset.
- [Playwright Commands Quick Reference](./guides/PLAYWRIGHT.md)
- [Quick Start](./guides/GETTING_STARTED.md) — This guide walks you through installing @gravity-ui/aikit and rendering your first chat.
- [README Documentation](./guides/guidelines/readme.md) — Every component must have a comprehensive README.md file documenting its purpose, usage, and API.
- [Storybook Files Creation](./guides/guidelines/storybook.md) — All components should have Storybook stories for documentation and testing purposes. Stories are located in the __stories__ directory within each component folder.
- [Testing Guide](./guides/TESTING.md) — This project uses Playwright Component Testing for visual regression testing and component validation.
- [Testing Guidelines](./guides/guidelines/testing.md) — Tests should be created based on Storybook stories to ensure consistency between documentation and functionality. We use Playwright Component Testing for visual regression testing and interaction testing.
- [Theming](./guides/THEMING.md) — AIKit uses CSS variables for theming, in the --g-aikit-* namespace. Values fall back to Gravity UI's --g-color-* system so AIKit picks up your existing uikit theme automatically.
- [Troubleshooting](./guides/TROUBLESHOOTING.md) — Common issues when integrating @gravity-ui/aikit.
- [Using AIKit with AI Agents (Claude Code / Cursor)](./guides/AI_AGENTS.md) — When you install @gravity-ui/aikit in a downstream project, you can teach Claude Code and Cursor about it so they write correct code without you spelling out the API every time.

## Components

- [atoms/ActionButton](./components/atoms/ActionButton.md) — A button component with integrated tooltip functionality, combining Button and ActionTooltip from Gravity UI.
- [atoms/Alert](./components/atoms/Alert.md) — An alert message with an indicator of alert's type opportunity to pass a button
- [atoms/ChatDate](./components/atoms/ChatDate.md) — A ChatDate component displays formatted dates with time and locale support.
- [atoms/ContextIndicator](./components/atoms/ContextIndicator.md) — A circular progress indicator that visualizes context usage as a percentage (0-100%).
- [atoms/ContextItem](./components/atoms/ContextItem.md) — A label for rendering context
- [atoms/DiffStat](./components/atoms/DiffStat.md) — A compact component that displays diff statistics showing the number of added and deleted lines.
- [atoms/Disclaimer](./components/atoms/Disclaimer.md) — A Disclaimer component displays informational or warning messages
- [atoms/FileIcon](./components/atoms/FileIcon.md) — Displays an icon representing a file based on its MIME type or file name extension.
- [atoms/IntersectionContainer](./components/atoms/IntersectionContainer.md) — Wrapper component for Intersection Observer API. Used for automatic loading of previous messages when scrolling up in MessageList.
- [atoms/Loader](./components/atoms/Loader.md) — A Loader visualizes loading state
- [atoms/MarkdownRenderer](./components/atoms/MarkdownRenderer.md) — A MarkdownRenderer component for rendering Yandex Flavored Markdown (YFM) content to HTML.
- [atoms/MessageBalloon](./components/atoms/MessageBalloon.md) — Visual wrapper for user's message
- [atoms/Shimmer](./components/atoms/Shimmer.md) — A loading animation component that creates a shimmer effect over its children.
- [atoms/SubmitButton](./components/atoms/SubmitButton.md) — A submit button component with state management through props and send/cancel icon switching.
- [atoms/ToolIndicator](./components/atoms/ToolIndicator.md) — A status indicator component that displays different icons based on the tool execution status. Shows a loader for loading state.
- [molecules/ActionPopup](./components/molecules/ActionPopup.md) — Universal anchored popup container for displaying content near action buttons.
- [molecules/BaseMessage](./components/molecules/BaseMessage.md) — Base wrapper for message with support for rendering action buttons
- [molecules/ButtonGroup](./components/molecules/ButtonGroup.md) — Wrapper for buttons group
- [molecules/FeedbackForm](./components/molecules/FeedbackForm.md) — Reusable feedback form component with reason selection and comment field.
- [molecules/FileDropZone](./components/molecules/FileDropZone.md) — A drag-and-drop area with a hidden file input. No external dependencies — uses native HTML5 DnD.
- [molecules/FileItem](./components/molecules/FileItem.md) — Displays a single file row with icon, name, optional size, upload status indicator, and remove button.
- [molecules/InputContext](./components/molecules/InputContext.md) — React context provider for prompt input attachments: queued files, removable chips in the prompt header, and an attachment picker slot. Pairs with useInputContext() for consumers inside the provider tree.
- [molecules/PromptInputBody](./components/molecules/PromptInputBody.md) — A body component for prompt input that displays a textarea with auto-growing capabilities or custom content.
- [molecules/PromptInputFooter](./components/molecules/PromptInputFooter.md) — A footer component for prompt input that displays action icons (settings, attachment, microphone) and a submit button.
- [molecules/PromptInputHeader](./components/molecules/PromptInputHeader.md) — A header component for prompt input that displays context items, context indicator, or custom content.
- [molecules/PromptInputPanel](./components/molecules/PromptInputPanel.md) — A simple panel container component that displays custom content.
- [molecules/RatingBlock](./components/molecules/RatingBlock.md) — Universal rating block with title and star rating.
- [molecules/StarRating](./components/molecules/StarRating.md) — A star rating component for displaying and collecting user ratings from 1 to 5 stars.
- [molecules/Suggestions](./components/molecules/Suggestions.md) — A Suggestions component displays a group of clickable suggestion buttons arranged in either horizontal (grid) or vertical (list) layout.
- [molecules/Tabs](./components/molecules/Tabs.md) — Tabs component for switching between sections with optional delete functionality. Built on top of Gravity UI's Label component.
- [molecules/ToolFooter](./components/molecules/ToolFooter.md) — Footer component for tool messages with action buttons and status message
- [molecules/ToolHeader](./components/molecules/ToolHeader.md) — Header component for tool messages with icon, name, actions, and status indicators
- [molecules/ToolStatus](./components/molecules/ToolStatus.md) — Component for displaying tool status with indicators and localized text
- [organisms/AssistantMessage](./components/organisms/AssistantMessage.md) — Component for rendering assistant messages with support for multiple message parts and custom renderers. Built on top of BaseMessage component with assistant variant styling.
- [organisms/AttachmentPicker](./components/organisms/AttachmentPicker.md) — A paperclip button that opens a file upload dialog.
- [organisms/FileUploadDialog](./components/organisms/FileUploadDialog.md) — A dialog with a drag-and-drop zone and a list of queued/uploaded files. Pure UI — upload logic is wired externally via useFileUploadStore.
- [organisms/Header](./components/organisms/Header.md) — Header component for displaying chat header with navigation and actions.
- [organisms/MessageList](./components/organisms/MessageList.md) — Component for displaying a list of messages. Supports custom message renderers through MessageRendererRegistry.
- [organisms/PromptInput](./components/organisms/PromptInput.md) — A flexible input component for chat interfaces with support for simple and full views, expandable panels, attachments, suggestions, and more.
- [organisms/ThinkingMessage](./components/organisms/ThinkingMessage.md) — A message component that displays AI thinking process with collapsible content and a status indicator.
- [organisms/ToolMessage](./components/organisms/ToolMessage.md) — Complete tool message component with automatic expand/collapse functionality and status-based behavior
- [organisms/UserMessage](./components/organisms/UserMessage.md) — Component for rendering a user message in a chat interface.
- [pages/AIStudioChat](./components/pages/AIStudioChat.md) — A ready-to-use chat component with built-in OpenAI streaming support. Wraps ChatContainer and manages all internal state — requires only an API URL to start working.
- [pages/ChatContainer](./components/pages/ChatContainer.md) — A fully assembled chat component - the main exportable component of the library that integrates Header, ChatContent, and History.
- [templates/ChatContent](./components/templates/ChatContent.md) — Main chat content container with view switching between empty state and message list.
- [templates/EmptyContainer](./components/templates/EmptyContainer.md) — A template component for displaying a welcome screen with image, title, description, and suggestions.
- [templates/History](./components/templates/History.md) — A comprehensive chat history component that displays a list of chats in a popup with integrated search, grouping, and action capabilities.