buildship-agent-ui

Drop-in React components for AI agent chat interfaces. Built for BuildShip.

Install

npm install buildship-agent-ui

Quick Start

import { SupportAgent } from "buildship-agent-ui";
import "buildship-agent-ui/styles.css";

function App() {
  return (
    <div style={{ height: 600, width: 400 }}>
      <SupportAgent
        agentUrl="https://your-buildship-agent-url"
        agentAccessKey="bs_ak_..."
        emptyMessage="Hi! How can I help?"
      />
    </div>
  );
}

Features

| Feature | Description | | ---------------------- | ------------------------------------------------------------ | | Inline chat | <SupportAgent /> fills its parent container | | Popup widget | <SupportAgentPopup /> — floating FAB + slide-up panel | | Headless hook | useSupportAgent() — full control, bring your own UI | | Slot-based styling | classNames prop for granular CSS overrides | | Refresh | Built-in reset button clears messages & starts a new session | | Tree-shakable | ESM with code splitting — import only what you use |

Components

<SupportAgent />

Inline chat that fills its parent container.

<SupportAgent
  agentUrl="https://..."
  agentAccessKey="bs_ak_..."
  title="Help Center"
  subtitle="We're online"
  emptyMessage="Ask us anything!"
/>

| Prop | Type | Default | Description | | ---------------- | ------------------- | ---------------- | ---------------------------------- | | agentUrl | string | — | BuildShip agent endpoint URL | | agentAccessKey | string | — | Agent access key | | emptyMessage | string | — | Placeholder shown when no messages | | title | string | "Support Chat" | Header title | | subtitle | string | "Online" | Header subtitle | | className | string | — | Root container class | | classNames | ChatBoxClassNames | — | Slot-based class overrides |

<SupportAgentPopup />

Floating chat widget with a FAB trigger button.

<SupportAgentPopup
  agentUrl="https://..."
  agentAccessKey="bs_ak_..."
  position="bottom-right"
  defaultOpen={false}
/>

| Prop | Type | Default | Description | | ------------------ | --------------- | ---------------- | ----------------- | | position | PopupPosition | "bottom-right" | Corner placement | | triggerIcon | ReactNode | — | Custom FAB icon | | triggerClassName | string | — | FAB button class | | popupClassName | string | — | Popup panel class | | defaultOpen | boolean | false | Start open |

useSupportAgent(options)

Headless hook — returns state and handlers, no UI.

const { messages, handleSend, inProgress, isOpen, toggle, close, reset } =
  useSupportAgent({
    agentUrl: "https://...",
    agentAccessKey: "bs_ak_...",
  });

<ChatBox />

Low-level chat UI component used internally by SupportAgent and SupportAgentPopup. Use directly when you need full control over state.

<ChatBox
  messages={messages}
  handleSend={handleSend}
  inProgress={inProgress}
  onRefresh={reset}
/>

Slot-Based Styling

Override any part of the chat UI via classNames:

<SupportAgent
  agentUrl="..."
  agentAccessKey="..."
  classNames={{
    root: "bg-purple-950 border-purple-800",
    header: "bg-purple-900",
    messageList: "bg-purple-950/50",
    userMessage: "bg-purple-700 text-white",
    agentMessage: "text-purple-100",
    inputWrapper: "bg-purple-900",
    footer: "border-purple-800",
  }}
/>

Available slots

| Slot | Target | | -------------- | --------------------- | | root | Root container | | header | Header bar | | messageList | Conversation area | | userMessage | User message bubble | | agentMessage | Agent message bubble | | inputWrapper | Input area wrapper | | footer | Footer below textarea |

License

MIT