DocsReact UIReact Ui

Pre-built React UI components for creating AI agent chat interfaces with Hexos.

Installation

npm install @hexos/react-ui

Peer dependencies: react ^18.0.0 || ^19.0.0, react-dom ^18.0.0 || ^19.0.0

Required: @hexos/react-core (installed automatically as a dependency)

Quick Start

import { AgentProvider } from '@hexos/react-core';
import { ChatWindow, AgentUIProvider } from '@hexos/react-ui';
import '@hexos/react-ui/styles.css';
 
function App() {
  return (
    <AgentProvider config={{ endpoint: '/api/agent/chat' }}>
      <AgentUIProvider>
        <ChatWindow config={{ endpoint: '/api/agent/chat' }} />
      </AgentUIProvider>
    </AgentProvider>
  );
}

CSS Imports

The package provides two CSS options:

import '@hexos/react-ui/styles.css';    // Custom CSS (lighter)
import '@hexos/react-ui/tailwind.css';  // Compiled Tailwind CSS

Components

Core Chat

ComponentDescription
ChatWindowFull chat interface with messages, input, streaming indicator, and agent status
MessageListScrollable message history with auto-scroll
MessageBubbleSingle message with role-specific styling, tool calls, and reasoning
InputComposerAuto-resizing textarea with submit on Enter
StreamingIndicatorAnimated typing indicator during streaming
QuickRepliesSuggestion chips for quick user actions

Agent Coordination

ComponentDescription
AgentBadgeColor-coded agent identity chip
AgentSwitcherMulti-agent selection interface
AgentStatusBarCurrent agent status display
HandoffIndicatorVisual marker for agent-to-agent transitions

Tool Execution

ComponentDescription
ToolCallRendererTool execution display with state (pending/executing/completed/failed)
ToolApprovalDialogModal for human-in-the-loop approval decisions
ToolApprovalContainerAutomatic approval dialog management
PendingApprovalBadgeApproval queue count badge
ActionConfirmDialogConfirmation dialog for agent-triggered actions
ActionConfirmContainerAutomatic action confirmation management

Primitives

ComponentDescription
ButtonStyled button with CVA variants
TextareaAuto-resizing textarea

ChatWindow Props

<ChatWindow
  config={{ endpoint: '/api/agent/chat' }}
  variant="default"          // 'default' | 'floating' | 'fullscreen' | 'sidebar'
  placeholder="Type a message..."
  showReasoning              // Show LLM extended thinking
  showAgentBadges            // Show agent identity badges on messages
  showHandoffs               // Show handoff indicators between messages
  showAgentStatus            // Show agent status bar
  enableMessageActions       // Enable edit/regenerate on messages
  handoffVariant="inline"    // 'inline' | 'card'
  header={<CustomHeader />}
  emptyState={<Welcome />}
  renderMessage={(msg) => <CustomMessage message={msg} />}
  renderInput={(props) => <CustomInput {...props} />}
  suggestions={['Hello', 'Help me with...']}
  suggestionsTitle="Quick start"
  agents={[
    { id: 'main', name: 'Main Assistant' },
    { id: 'code', name: 'Code Helper' },
  ]}
/>

Theming

Customize the appearance with AgentUIProvider:

import { AgentUIProvider } from '@hexos/react-ui';
 
<AgentUIProvider
  theme={{
    colors: {
      primary: '#8b5cf6',
      userBubble: '#3b82f6',
      assistantBubble: '#f3f4f6',
      toolCall: '#fef3c7',
      reasoning: '#f9fafb',
    },
    borderRadius: '0.75rem',
    fonts: {
      body: 'Inter, sans-serif',
    },
  }}
  displayConfig={{
    toolDisplayMode: 'minimal',  // 'full' | 'minimal' | 'hidden'
  }}
>
  {children}
</AgentUIProvider>

Access theme values in custom components:

import { useAgentUITheme, useDisplayConfig } from '@hexos/react-ui';
 
const theme = useAgentUITheme();
const displayConfig = useDisplayConfig();

License

MIT

API Reference

Ui Components Ui Primitives Ui Theme
TransportMessageActionConfirmContainer