@colossal-sh/chat-react

React components for embedding the Colossal chat widget in your own app: ChatProvider, ChatWidget, and extension points for custom output renderers. Built on the framework-agnostic @colossal-sh/chat-client.

Install

npm install @colossal-sh/chat-react @colossal-sh/chat-client @astryxdesign/core @stylexjs/stylex

Peer dependencies: @astryxdesign/core >=0.1.4, @stylexjs/stylex ^0.19.0, react >=19, react-dom >=19.

Styles

With a bundler (Vite, webpack, …), import one stylesheet:

import "@colossal-sh/chat-react/styles.css";

styles.css pulls in @astryxdesign/core's reset and component CSS from your installed version (via CSS @import, resolved by your bundler) plus the widget styles — so the astryx CSS always matches the astryx components. It also pins the CSS cascade-layer order (@layer properties, reset, theme, base, components, utilities, astryx-base;) so Tailwind v4's preflight cannot override the widget's component styles: without that, a host app that declares Tailwind's base layer after astryx-base strips the widget's paddings, borders, and button backgrounds (a later-declared layer beats specificity).

Without a bundler (e.g. plain <link> tags), or if your app already loads the astryx CSS, load the pieces individually — and if your app uses Tailwind v4, declare that same @layer order in a stylesheet loaded before the astryx CSS:

import "@astryxdesign/core/reset.css";
import "@astryxdesign/core/astryx.css";
import "@colossal-sh/chat-react/widget.css";

Quickstart

import { createChatClient } from "@colossal-sh/chat-client";
import { ChatProvider, ChatWidget } from "@colossal-sh/chat-react";
import "@colossal-sh/chat-react/styles.css";

const chatClient = createChatClient({
  agentUid: "<agent-uid>",
  adapter: { baseUrl: "https://<your-workspace-host>/api/v1" },
});

export function SupportChat() {
  return (
    <ChatProvider client={chatClient}>
      <ChatWidget />
    </ChatProvider>
  );
}

The agentUid is the widget agent's uid, shown on the agent's Embed tab in Colossal. createChatClient accepts the full WidgetConfig from @colossal-sh/chat-client (launcher.position, theme, logoUrl, identity, strings, …). Prefer a module-level client passed via the client prop as above; with the config prop the provider creates the client after the first render, so components that read the chat context on mount (including ChatWidget) throw "must be inside <ChatProvider>" unless you gate them with useHasChatClient().

Customization

ChatProvider props beyond client/config:

• components — swap built-in UI parts (ChatComponents: launcher, panel header, conversation list item, …).
• componentRenderers — map an automation output type to your own React component:

<ChatProvider
  config={{ agentUid, adapter: { baseUrl } }}
  componentRenderers={{ warranty_check: WarrantyCard }}
>
  <ChatWidget />
</ChatProvider>

Built-in types you can override: product_list, cart_add / cart_remove, cart_view, order_details, button_link. See Custom components for payload shapes.

• dataPartRenderers / toolPartRenderers — lower-level stream part rendering.
• portalTarget — where the widget portal mounts.

Hooks are exported from the ./hooks subpath (useChatClient, useWidgetState, useConversations, useCart, …), and individual building blocks (Launcher, WidgetPanel, ConversationView, Composer, …) from the package root for fully custom layouts.

Documentation

• Widget agents
• Custom components

License

MIT