React SDK — Overview & Installation

The unifiedlayer-sdk package is UnifiedLayer's official React SDK. It lets you add AI-powered chat, generative UI, tool calling, and thread management to any React or Next.js application in minutes — without writing any backend plumbing.

What the SDK does

Generative UI — The AI can render React components directly inside a chat message. You register components once; the LLM decides when and how to render them based on conversation context.

Tool calling — Define JavaScript/TypeScript functions that the AI can call during a response. The SDK runs the tool, feeds the result back to the LLM, and loops until the AI produces a final reply.

Thread management — Every conversation is a persistent thread stored on the UnifiedLayer backend. The SDK exposes hooks to list threads, switch between them, and stream responses in real time.

Drop-in chat UI — UnifiedLayerChatUI is a fully styled, production-ready chat component. Mount it with a userId and it handles sessions, message history, streaming, and markdown rendering automatically.

Installation

bash

npm install unifiedlayer-sdk

bash

# or with yarn / pnpm
yarn add unifiedlayer-sdk
pnpm add unifiedlayer-sdk

Peer dependencies

The SDK requires React 17 or later and its companion DOM package:

json

{
  "peerDependencies": {
    "react": ">=17",
    "react-dom": ">=17"
  }
}

If your project already has React installed, no additional steps are needed.

Core concepts

The SDK is built around three layers that compose together:

1. Provider

UnifiedLayerProvider sits at the root of your component tree and holds the SDK configuration, registered components, and registered tools. Everything else in the SDK reads from this context.

2. Hooks

Six hooks give you fine-grained access to sessions, threads, messages, streaming state, and input state. You can compose them to build a completely custom chat UI, or ignore them entirely if you use UnifiedLayerChatUI.

3. Render

ComponentRenderer takes a message object and renders it as plain text, as a generative UI component, or as both combined. UnifiedLayerChatUI uses ComponentRenderer internally for every message bubble.

Minimal working example

The fastest way to add a fully functional AI chat to your app:

tsx

// app/layout.tsx  (Next.js App Router)
import { UnifiedLayerProvider } from 'unifiedlayer-sdk';

const unifiedLayerConfig = {
  appId: process.env.NEXT_PUBLIC_UL_APP_ID!,
  baseUrl: 'https://www.unifiedlayer.space',
  credentials: {
    clientId: process.env.NEXT_PUBLIC_UL_CLIENT_ID!,
    apiKey: process.env.NEXT_PUBLIC_UL_API_KEY!,
  },
};

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <UnifiedLayerProvider config={unifiedLayerConfig}>
          {children}
        </UnifiedLayerProvider>
      </body>
    </html>
  );
}

tsx

// app/chat/page.tsx
import { UnifiedLayerChatUI } from 'unifiedlayer-sdk';

export default function ChatPage() {
  return (
    <UnifiedLayerChatUI
      userId="user_abc123"
      title="Ask me anything"
      placeholder="Type your message..."
    />
  );
}

That is the entire integration. UnifiedLayerChatUI handles session creation, thread creation, message streaming, and rendering.

When to use `UnifiedLayerChatUI` vs a custom UI

Requirement	`UnifiedLayerChatUI`	Custom UI with hooks
Drop-in chat in under 5 minutes	Yes	No
Full control over message layout	No	Yes
Custom input controls (voice, file upload)	No	Yes
Generative UI components rendered inline	Yes (automatic)	Yes (via `ComponentRenderer`)
Markdown rendering	Yes (built-in)	Bring your own
Streaming typing indicator	Yes (built-in)	Yes (via `useUnifiedLayerStreamStatus`)
Multiple threads / thread switcher	No	Yes (via `useUnifiedLayerThreadList`)
Style via CSS or Tailwind	Limited (style prop)	Complete freedom
Fastest path to production	Best choice	More work, more control

Use UnifiedLayerChatUI for prototypes, embedded widgets, and any case where you do not need to deviate from a standard chat layout. Switch to hooks-based custom UI when you need a bespoke experience.

TypeScript support

The SDK is written in TypeScript and ships its own type declarations. No @types/ package is needed. All hooks, props, and utility functions are fully typed.

import type {
  UnifiedLayerConfig,
  UnifiedLayerMessage,
  UnifiedLayerThread,
  ToolDefinition,
  ComponentDefinition,
} from 'unifiedlayer-sdk';

React SDK — Overview & Installation ​

What the SDK does ​

Installation ​

Peer dependencies ​

Core concepts ​

1. Provider ​

2. Hooks ​

3. Render ​

Minimal working example ​

When to use UnifiedLayerChatUI vs a custom UI ​

TypeScript support ​

What to read next ​