Installation

Install the React SDK using your preferred package manager:

npm install @usetransactional/react

pnpm add @usetransactional/react

yarn add @usetransactional/react

Then import the base stylesheet in your application entry point:

import '@usetransactional/react/styles.css';

Quick Start

Add a fully functional chat widget to your app in under a minute:

import '@usetransactional/react/styles.css';
import { ChatWidget } from '@usetransactional/react';
 
function App() {
  return (
    <ChatWidget
      inboxId="your-inbox-id"
      user={{
        id: 'user-123',
        email: 'jane@example.com',
        name: 'Jane Doe',
      }}
    />
  );
}

Chat Module

The Chat module provides embeddable live chat components for real-time customer communication.

ChatWidget

The primary component for adding chat to your application. Renders a floating launcher button and an expandable chat window.

import { ChatWidget } from '@usetransactional/react';
 
function App() {
  return (
    <ChatWidget
      inboxId="your-inbox-id"
      user={{
        id: 'user-123',
        email: 'jane@example.com',
        name: 'Jane Doe',
        avatar: 'https://example.com/avatar.jpg',
      }}
      metadata={{
        plan: 'pro',
        company: 'Acme Inc',
      }}
      position="bottom-right"
      launcher={<button>Need help?</button>}
      onOpen={() => console.log('Chat opened')}
      onClose={() => console.log('Chat closed')}
      onNewMessage={(message) => console.log('New message:', message)}
    />
  );
}

Props:

Prop	Type	Required	Description
`inboxId`	`string`	Yes	Your Transactional inbox ID
`user`	`User`	No	Authenticated user information
`user.id`	`string`	Yes	Unique user identifier
`user.email`	`string`	No	User email address
`user.name`	`string`	No	Display name
`user.avatar`	`string`	No	Avatar image URL
`metadata`	`Record<string, string>`	No	Custom metadata attached to the conversation
`position`	`"bottom-right" \| "bottom-left"`	No	Widget position on screen. Defaults to `"bottom-right"`
`launcher`	`ReactNode`	No	Custom launcher element to replace the default button
`onOpen`	`() => void`	No	Callback when the chat window opens
`onClose`	`() => void`	No	Callback when the chat window closes
`onNewMessage`	`(message: Message) => void`	No	Callback when a new message is received

ChatWindow

A standalone chat window component without the floating launcher. Use this when you want to embed chat directly into a page layout rather than as an overlay.

import { ChatWindow } from '@usetransactional/react';
 
function SupportPage() {
  return (
    <div style={{ height: '600px' }}>
      <ChatWindow
        inboxId="your-inbox-id"
        user={{ id: 'user-123', name: 'Jane Doe' }}
      />
    </div>
  );
}

ChatProvider

A context provider that manages chat state. Use this when you need to access chat state or actions from multiple components in your tree.

import { ChatProvider, ChatWindow } from '@usetransactional/react';
 
function App() {
  return (
    <ChatProvider inboxId="your-inbox-id" user={{ id: 'user-123' }}>
      <ChatWindow />
      <MessageCounter />
    </ChatProvider>
  );
}

Knowledge Base Module

The Knowledge Base module provides components for embedding searchable help centers and documentation directly in your application.

KnowledgeBase

The all-in-one knowledge base component that renders a full help center with search, collections, and article views.

import { KnowledgeBase } from '@usetransactional/react';
 
function HelpCenter() {
  return (
    <KnowledgeBase
      projectId="your-project-id"
      theme="system"
      header={<h1>Help Center</h1>}
      hideSearch={false}
      hideCollections={false}
      onArticleView={(article) => console.log('Viewed:', article.title)}
      onSearch={(query) => console.log('Searched:', query)}
    />
  );
}

Props:

Prop	Type	Required	Description
`projectId`	`string`	Yes	Your Transactional project ID
`theme`	`"light" \| "dark" \| "system"`	No	Color theme. Defaults to `"system"`
`header`	`ReactNode`	No	Custom header element
`hideSearch`	`boolean`	No	Hide the search bar
`hideCollections`	`boolean`	No	Hide the collections grid
`onArticleView`	`(article: Article) => void`	No	Callback when an article is viewed
`onSearch`	`(query: string) => void`	No	Callback when a search is performed

Individual KB Components

For more granular control, use the individual knowledge base components:

import {
  KBProvider,
  KBSearch,
  KBCollections,
  KBArticle,
} from '@usetransactional/react';
 
function CustomHelpCenter() {
  return (
    <KBProvider projectId="your-project-id">
      <div className="search-container">
        <KBSearch />
      </div>
 
      <div className="collections-grid">
        <KBCollections />
      </div>
 
      <div className="article-view">
        <KBArticle articleId="article-slug-or-id" />
      </div>
    </KBProvider>
  );
}

KBSearch - A search input with a results dropdown. Handles debounced search queries and displays matching articles inline.

KBArticle - Renders a single knowledge base article by its ID or slug, including the title, body content, and metadata.

KBCollections - Displays all collections in a list or grid view, with article counts and navigation.

KBProvider - Context provider that manages knowledge base state including the active article, search query, and navigation history. Wrap your individual KB components with this provider.

Forms Module

The Forms module lets you embed Transactional forms directly in your application with automatic validation and submission handling.

TransactionalForm

Renders a complete form by its ID, including all fields, validation rules, and submission logic.

import { TransactionalForm } from '@usetransactional/react';
 
function ContactPage() {
  return (
    <TransactionalForm
      formId="contact-form-id"
      onSubmit={(data) => {
        console.log('Form submitted:', data);
      }}
      onError={(errors) => {
        console.error('Validation errors:', errors);
      }}
    />
  );
}

Props:

Prop	Type	Required	Description
`formId`	`string`	Yes	The form ID from your Transactional dashboard
`onSubmit`	`(data: Record<string, unknown>) => void`	No	Callback on successful submission
`onError`	`(errors: unknown[]) => void`	No	Callback on validation or submission errors

FormField and FormProvider

For advanced use cases, you can compose forms using individual field components:

import { FormProvider, FormField } from '@usetransactional/react';
 
function CustomForm() {
  return (
    <FormProvider formId="contact-form-id">
      <FormField name="email" />
      <FormField name="message" />
      <button type="submit">Send</button>
    </FormProvider>
  );
}

FormField - Renders an individual form field with its label, input, and validation messages.

FormProvider - Context provider that manages form state, validation, and submission. Wrap your FormField components with this provider.

Styling

CSS Variables

Customize the look and feel of all Transactional components by overriding CSS variables in your stylesheet:

:root {
  --transactional-primary: #3b82f6;
  --transactional-primary-hover: #2563eb;
  --transactional-background: #ffffff;
  --transactional-foreground: #09090b;
  --transactional-muted: #f4f4f5;
  --transactional-muted-foreground: #71717a;
  --transactional-border: #e4e4e7;
  --transactional-radius: 0.5rem;
}

Variable	Description
`--transactional-primary`	Primary brand color for buttons, links, and accents
`--transactional-primary-hover`	Hover state for primary elements
`--transactional-background`	Background color for widget surfaces
`--transactional-foreground`	Primary text color
`--transactional-muted`	Muted background for secondary surfaces
`--transactional-muted-foreground`	Muted text color for secondary content
`--transactional-border`	Border color for inputs, cards, and dividers
`--transactional-radius`	Border radius for all rounded elements

Component-Specific Stylesheets

If you only use a subset of the SDK, you can import styles per module to reduce your CSS bundle size:

// Chat styles only
import '@usetransactional/react/chat/styles.css';
 
// Knowledge Base styles only
import '@usetransactional/react/kb/styles.css';
 
// Forms styles only
import '@usetransactional/react/forms/styles.css';

When using the React SDK with Next.js App Router, all Transactional components must be rendered in a Client Component. Add the 'use client' directive at the top of any file that uses these components:

'use client';
 
import { ChatWidget } from '@usetransactional/react';
 
export default function ChatWrapper() {
  return (
    <ChatWidget
      inboxId="your-inbox-id"
      user={{ id: 'user-123' }}
    />
  );
}

This is required because the SDK uses browser APIs, React state, and effects that are not available in Server Components. A common pattern is to create a thin client wrapper component and import it into your server-rendered layout:

// app/layout.tsx (Server Component)
import ChatWrapper from '@/components/chat-wrapper';
 
export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {children}
        <ChatWrapper />
      </body>
    </html>
  );
}

TypeScript Types

The SDK exports all relevant types for full type safety:

import type {
  ChatWidgetProps,
  KnowledgeBaseProps,
  TransactionalFormProps,
  User,
  Message,
  Article,
} from '@usetransactional/react';

Key types:

Type	Description
`ChatWidgetProps`	Props for the `ChatWidget` component
`KnowledgeBaseProps`	Props for the `KnowledgeBase` component
`TransactionalFormProps`	Props for the `TransactionalForm` component
`User`	User object with `id`, `email`, `name`, and `avatar` fields
`Message`	Chat message with `id`, `content`, `sender`, `timestamp`, and `type` fields
`Article`	Knowledge base article with `id`, `title`, `slug`, `body`, `collection`, and `metadata` fields

Requirements

Dependency	Version
React	18.0 or higher
React DOM	18.0 or higher
Next.js	13.0 or higher (optional)