Types

Overview

react-ai-chat provides TypeScript types for embedding providers, RAG indexes, chatbot configuration, and theme customization.

You can import the types directly from the package:

import type {
  ChatbotProps,
  ChatbotTheme,
  ChatbotThemeTokens,
  EmbeddingIndex,
  EmbeddingProvider,
} from "react-ai-chat";

`EmbeddingProvider`

Defines the interface required by an embedding provider.

interface EmbeddingProvider {
  name: string;
  model: string;
  maxBatchSize: number;

  embed(text: string, type?: "document" | "query"): Promise<number[]>;

  embedMany?(texts: string[], type?: "document" | "query"): Promise<number[][]>;
}

Properties

Property	Type	Description
`name`	`string`	Provider name
`model`	`string`	Embedding model
`maxBatchSize`	`number`	Maximum number of texts supported per batch
`embed`	`function`	Generates an embedding vector for one text
`embedMany`	`function`	Optionally generates embeddings for many texts

The optional type argument identifies whether the text is being embedded as a document or query.

await provider.embed(text, "document");
await provider.embed(question, "query");

`Document`

Represents a source document before it is split into chunks.

interface Document {
  id: string;
  text: string;
}

`Chunk`

Represents a document chunk before an embedding is generated.

interface Chunk {
  id: string;
  source: string;
  chunk: number;
  text: string;
}

Property	Type	Description
`id`	`string`	Unique chunk identifier
`source`	`string`	Source document
`chunk`	`number`	Chunk number
`text`	`string`	Chunk content

`EmbeddedChunk`

Represents a chunk together with its embedding vector.

interface EmbeddedChunk {
  id: string;
  source: string;
  chunk: number;
  text: string;
  embedding: number[];
  embeddingModel?: string;
}

The embeddingModel property is optional.

`EmbeddingIndex`

Represents the generated RAG index.

interface EmbeddingIndex {
  provider: string;
  model: string;
  fallbackModel?: string;
  dimensions: number;
  chunks: EmbeddedChunk[];
}

Properties

Property	Type	Description
`provider`	`string`	Provider used to generate the index
`model`	`string`	Primary embedding model
`fallbackModel`	`string`	Fallback model, when configured
`dimensions`	`number`	Vector dimensions
`chunks`	`EmbeddedChunk[]`	Embedded document chunks

This is the structure stored in the generated embeddings.json.

`CreateIndexOptions`

Options used when creating an embedding index.

interface CreateIndexOptions {
  provider: EmbeddingProvider;
  fallbackProvider?: EmbeddingProvider;
  documentsPath?: string;
  outputPath?: string;
  embeddingBatchSize?: number;
}

Properties

Property	Type	Description
`provider`	`EmbeddingProvider`	Primary embedding provider
`fallbackProvider`	`EmbeddingProvider`	Optional fallback provider
`documentsPath`	`string`	Source documents directory
`outputPath`	`string`	Generated index output path
`embeddingBatchSize`	`number`	Optional batch size used during index generation

`RetrieveContextOptions`

Options used when retrieving relevant document chunks.

interface RetrieveContextOptions {
  question: string;
  embeddings: EmbeddedChunk[];
  embedFn: (text: string) => Promise<number[]>;
  topK?: number;
}

Properties

Property	Type	Description
`question`	`string`	User's retrieval query
`embeddings`	`EmbeddedChunk[]`	Indexed document chunks
`embedFn`	function	Generates the query embedding
`topK`	`number`	Maximum number of chunks to retrieve

`ChatRouteOptions`

Options accepted by createChatRoute().

interface ChatRouteOptions {
  model: LanguageModel;
  systemPrompt?: string;
  maxMessages?: number;
  rag?: {
    index: EmbeddingIndex;
    provider: EmbeddingProvider;
    topK?: number;
  };
}

`model`

The AI SDK language model used to generate the response.

`systemPrompt`

Optional system instructions.

`maxMessages`

Optional limit for the number of messages processed by the route.

`rag`

Optional RAG configuration.

rag?: {
  index: EmbeddingIndex;
  provider: EmbeddingProvider;
  topK?: number;
}

See RAG.

`GoogleEmbeddingOptions`

interface GoogleEmbeddingOptions {
  model?: string;
  dimensions?: number;
}

`OpenAIEmbeddingOptions`

interface OpenAIEmbeddingOptions {
  model?: string;
  dimensions?: number;
}

`VoyageEmbeddingOptions`

interface VoyageEmbeddingOptions {
  model?: string;
  dimensions?: number;
}

`CohereEmbeddingOptions`

interface CohereEmbeddingOptions {
  model?: string;
  dimensions?: number;
}

`JinaEmbeddingOptions`

interface JinaEmbeddingOptions {
  model?: string;
  dimensions?: number;
}

`HuggingFaceEmbeddingOptions`

interface HuggingFaceEmbeddingOptions {
  model?: string;
  dimensions?: number;
}

All embedding provider options use the same shape. model selects the embedding model and dimensions can be used when the provider supports configurable dimensions.

`ChatbotThemeTokens`

Defines the individual theme values used by the chatbot.

interface ChatbotThemeTokens {
  primaryColor?: string;
  primaryForeground?: string;
  background?: string;
  foreground?: string;
  mutedBackground?: string;
  mutedForeground?: string;
  borderColor?: string;
}

Theme tokens

Token	Description
`primaryColor`	Primary accent color for buttons, header, and user bubbles
`primaryForeground`	Text color on primary elements
`background`	Main chat window background
`foreground`	Main text color
`mutedBackground`	Background for bot messages, input, and chips
`mutedForeground`	Secondary text color
`borderColor`	Border color for inputs and prompt chips

Example:

const theme = {
  primaryColor: "#7c3aed",
  primaryForeground: "#ffffff",
  background: "#ffffff",
  foreground: "#18181b",
  mutedBackground: "#f4f4f5",
  mutedForeground: "#71717a",
  borderColor: "#e4e4e7",
};

`ChatbotTheme`

Supports flat theme tokens and separate light and dark overrides.

type ChatbotTheme = ChatbotThemeTokens & {
  light?: ChatbotThemeTokens;
  dark?: ChatbotThemeTokens;
};

Example:

const theme = {
  primaryColor: "#7c3aed",

  light: {
    background: "#ffffff",
    foreground: "#18181b",
  },

  dark: {
    background: "#18181b",
    foreground: "#fafafa",
  },
};

`ChatbotProps`

Defines the props accepted by the ready-made <Chatbot /> component.

interface ChatbotProps {
  title?: string;
  subtitle?: string;
  triggerText?: string;
  triggerIcon?: ReactNode;
  sendIcon?: ReactNode;
  closeIcon?: ReactNode;
  position?: "bottom-right" | "bottom-left" | "top-right" | "top-left";
  starterPrompts?: string[];
  emptyStateText?: string;
  placeholder?: string;
  starterPromptsLabel?: string;
  apiEndpoint?: string;
  initialOpen?: boolean;
  themeMode?: "auto" | "light" | "dark";
  classNames?: {
    wrapper?: string;
    trigger?: string;
    window?: string;
    header?: string;
  };
  theme?: ChatbotTheme;
  onError?: (error: Error) => void;
}

`classNames`

The ready-made chatbot accepts four custom class names:

classNames?: {
  wrapper?: string;
  trigger?: string;
  window?: string;
  header?: string;
}

Example:

<Chatbot
  classNames={{
    wrapper: "my-chatbot",
    trigger: "my-trigger",
    window: "my-window",
    header: "my-header",
  }}
/>

`themeMode`

The supported values are:

themeMode?: "auto" | "light" | "dark";

Use auto to follow the system preference.

<Chatbot themeMode="auto" />

`onError`

Receives an Error when the chatbot encounters an error.

<Chatbot
  onError={(error) => {
    console.error(error);
  }}
/>

Chatbot

Complete API reference for the ready-made chatbot.

RAG

Configure retrieval augmented generation.

Providers

Configure embedding providers.

Chatbot

RAG

Providers

On this page