Skip to Content
APIAPI Reference

API Reference

Complete API documentation for all hooks, components, and TypeScript interfaces in the AI Chat Bootstrap library.

Hooks

Chat Management

  • useAIChat - Main hook for managing chat state and AI interactions with automatic context and tool integration

Context & Focus

  • useAIContext - Share React component state with the AI without causing re-renders
  • useAIFocus - Enable users to explicitly mark which items should be prioritized in AI conversations

Tools

  • useAIFrontendTool - Register tools that the AI can execute in your React components for direct UI interaction

Components

Chat Interface Components

  • ChatContainer - Main chat interface component with message display and input
  • ChatMessage - Individual message component with support for different message types
  • ChatInput - Standalone input component for chat interfaces

Core Concepts

Message Format

The library uses the Vercel AI SDK UIMessage format for all chat interactions:

interface UIMessage {
  id: string;
  role: 'system' | 'user' | 'assistant';
  metadata?: unknown;
  parts: Array<UIMessagePart>;
}

Context vs Focus

  • Context (useAIContext): Automatic, ambient information that’s always available to the AI
  • Focus (useAIFocus): User-controlled, explicit items that are temporarily prioritized

Tools Integration

Frontend tools execute in the browser and allow the AI to:

  • Modify React component state
  • Trigger UI actions
  • Fetch data from APIs
  • Update forms and user interfaces

Getting Started

  1. Install peers + library:
npm install ai-chat-bootstrap react react-dom ai @ai-sdk/react @ai-sdk/openai zod
# or pnpm add ... (preferred)
  1. Import styles (choose ONE mode): Zero-config:
@import "ai-chat-bootstrap/tokens.css";
@import "ai-chat-bootstrap/ai-chat.css";

Tailwind-native (no ai-chat.css): add preset in tailwind config and include library source in content.

  1. Use the main chat hook: 
    import { useAIChat } from 'ai-chat-bootstrap';
 
const chat = useAIChat({ api: '/api/chat' });

Quick Examples

Basic Chat

import { ChatContainer, useAIChat } from 'ai-chat-bootstrap';
 
function MyChat() {
  const chat = useAIChat({
    api: '/api/chat',
    systemPrompt: 'You are a helpful assistant.'
  });
 
  return (
    <ChatContainer
      chat={chat}
      header={{ title: 'My Chat' }}
    />
  );
}

With Context

import { useAIChat, useAIContext } from 'ai-chat-bootstrap';
 
function ChatWithContext() {
  const [user] = useState({ name: 'Alice', role: 'admin' });
  
  // Share user context with AI
  useAIContext({ description: 'User Profile', value: user });
 
  const chat = useAIChat({ api: '/api/chat' });
  
  return <ChatContainer chat={chat} />;
}

With Tools

import { useAIChat, useAIFrontendTool } from 'ai-chat-bootstrap';
import { z } from 'zod';
 
function ChatWithTools() {
  const [count, setCount] = useState(0);
 
  // Register a tool the AI can use
  useAIFrontendTool({
    name: 'increment',
    description: 'Increment the counter',
    parameters: z.object({
      amount: z.number().default(1)
    }),
    execute: async ({ amount }) => {
      setCount(prev => prev + amount);
      return { newValue: count + amount };
    }
  });
 
  const chat = useAIChat({ api: '/api/chat' });
  
  return (
    <div>
      <div>Count: {count}</div>
      <ChatContainer chat={chat} />
    </div>
  );
}

Component Reference

ChatContainer

Main chat interface component with messages UI and input. Prefer passing the hook result via the chat prop.

type ChatContainerProps = {
  // Preferred
  chat?: ReturnType<typeof useAIChat>;
 
  // Optional: group overrides when not using `chat`
  state?: { messages?: UIMessage[]; isLoading?: boolean; status?: ChatStatus };
  inputProps?: { value?: string; onChange?: (v: string) => void; onSubmit?: (e: FormEvent) => void; onAttach?: () => void };
  header?: { title?: string; subtitle?: string; avatar?: React.ReactNode; badge?: React.ReactNode; actions?: React.ReactNode; className?: string };
  ui?: { placeholder?: string; className?: string; classes?: { header?: string; messages?: string; message?: string; input?: string }; emptyState?: React.ReactNode };
  suggestions?: { enabled?: boolean; prompt?: string; count?: number; api?: string; onAssistantFinish?: (cb: () => void) => void; onSendMessage?: (message: string) => void };
  commands?: { enabled?: boolean; onExecute?: (commandName: string, args?: string) => void; onAICommandExecute?: (message: string, toolName: string, systemPrompt?: string) => void };
  threads?: { enabled?: boolean; scopeKey?: string; threadId?: string; onThreadChange?: (id: string) => void };
};

Why: Groups keep layout independent from hook wiring and avoid prop soup while still allowing targeted overrides.

ChatMessage

Individual message component with support for different message types.

interface ChatMessageProps {
  message: UIMessage;
  className?: string;
}

ChatInput

Standalone input component for chat interfaces.

interface ChatInputProps {
  input: string;
  onInputChange: (e: ChangeEvent<HTMLInputElement | HTMLTextAreaElement>) => void;
  onSubmit: (e?: FormEvent) => void;
  isLoading?: boolean;
  placeholder?: string;
  className?: string;
}

TypeScript Interfaces

Core Types

// Focus item structure
interface FocusItem {
  id: string;
  label?: string;
  description?: string;
  data?: Record<string, unknown>;
}
 
// Context item structure
interface ContextItem {
  id: string;
  label?: string;
  description?: string;
  scope: "session" | "conversation" | "message";
  priority: number;
  data: Record<string, unknown>;
}
 
// Frontend tool definition
interface FrontendTool {
  name: string;
  description: string;
  parameters: ZodSchema;
  execute: (params: any) => Promise<any> | any;
}

Message Types

// Message part types
type UIMessagePart = 
  | { type: 'text'; text: string; state?: 'streaming' | 'done' }
  | { type: 'reasoning'; text: string; state?: 'streaming' | 'done' }
  | { type: 'file'; mediaType: string; filename?: string; url: string }
  | { type: 'source-url'; sourceId: string; url: string; title?: string }
  | { type: 'tool-*'; toolCallId: string; /* ... */ }
  | { type: 'data-*'; id?: string; data: any };

Backend Integration

The library automatically sends structured payloads to your API endpoint:

interface ChatRequestPayload {
  messages: UIMessage[];
  /**
   * Original system prompt provided by the app (optional).
   * Its content is appended inside the enrichedSystemPrompt automatically.
   */
  systemPrompt?: string;
  /**
   * Automatically generated enriched system prompt (always sent unless explicitly overridden).
   * Contains standardized preamble + conditional Tools / Context / Focus sections + appended original systemPrompt.
   */
  enrichedSystemPrompt: string;
  tools?: Record<string, ToolDefinition>;
  context?: ContextItem[];
  focus?: FocusItem[];
}

Example API Route (Next.js)

import { createAzure } from '@ai-sdk/azure';
import { convertToModelMessages, streamText } from 'ai';
 
const azure = createAzure({
  resourceName: process.env.AZURE_RESOURCE_NAME!,
  apiKey: process.env.AZURE_API_KEY!,
  apiVersion: process.env.AZURE_API_VERSION ?? 'preview',
});
 
const model = azure(process.env.AZURE_DEPLOYMENT_ID!);
 
export async function POST(req: Request) {
  const { messages, enrichedSystemPrompt, tools } = await req.json();
 
  const result = await streamText({
    model,
    messages: [
      { role: 'system', content: enrichedSystemPrompt },
      ...convertToModelMessages(messages),
    ],
    tools,
  });
 
  return result.toUIMessageStreamResponse();
}

Best Practices

Performance

  • Use useMemo for expensive context computations
  • Limit message history in long conversations
  • Follow Zustand patterns to avoid re-render loops

Security

  • Never share sensitive data in context or focus items
  • Validate all tool parameters
  • Sanitize user inputs

User Experience

  • Provide clear loading states
  • Handle errors gracefully with user-friendly messages
  • Show visual feedback for focused items and active context

Migration from Other Libraries

The AI Chat Bootstrap library is designed to work seamlessly with the Vercel AI SDK while adding powerful context and tool management capabilities. If you’re migrating from other chat libraries, the useAIChat hook provides a familiar interface while adding automatic integration with context, focus, and tools.

Examples & Tutorials

Support

For issues, feature requests, or questions:

Last updated on
CommandsComponents