# HextaAI

> A complete AI chat app built from the HextaUI AI blocks. Handles streaming, tool approvals and plan review end to end on AI SDK message parts.

Canonical: https://hextaui.com/blocks/hexta-ai
Last updated: 2026-10-29

## Overview

HextaAI is a complete AI chat app made from every HextaUI AI block. Chat Sidebar holds the history, Chat Thread holds the conversation, Prompt Input is the composer, and each reply is drawn from its parts: Thinking for reasoning, Tool Calls for what the agent did, Agent Todos for its plan, Code Block for diffs and terminals, and Streaming Markdown for the answer. Artifact opens web pages, documents and files the model makes in a panel beside the chat, with versions, and small changes are typed into the open file instead of rewriting it. Voice Mode opens from the composer and drops the conversation into the chat when you hang up.

The core is HextaMessageParts. It takes the same message parts the AI SDK’s useChat returns, groups neighbouring reasoning and tool calls, keeps one live plan at the top of the reply, and renders text with citations linked to the sources the model found. Reads, edits, writes, searches, web fetches and shell commands each get a fitting view, and you can add renderers for your own tools.

The demo runs on ScriptedChats, a small engine that streams realistic parts offline. Try a suggestion: make a pricing page and watch it open beside the chat, research a question and watch sources come in, ask for a feature and review the plan before it runs, approve a test run that fails and gets fixed, or ask for an explanation with code and tables. Stop, regenerate, edit and switch chats while replies keep streaming in the background, then open voice mode and talk.

## Installation

### Step 1: Get HextaUI Pro

One payment unlocks every block, including future ones. [See pricing](https://hextaui.com/pricing).

### Step 2: Add the Pro registry to components.json

```json title="components.json"
{
  "registries": {
    "@hextaui-pro": {
      "url": "https://hextaui.com/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${HEXTAUI_PRO_TOKEN}"
      }
    }
  }
}
```

### Step 3: Add your token

Create a token on your [account page](https://hextaui.com/account) and put it in `.env.local` as `HEXTAUI_PRO_TOKEN`.

### Step 4: Add the block

```bash
npx shadcn@latest add @hextaui-pro/hexta-ai
```

## Usage

### With the AI SDK

Pass useChat messages straight to HextaMessageParts. Tool approvals and plan reviews answer through addToolApprovalResponse, and an edited plan goes back to the model as the approval reason.

```tsx
"use client"

import { useChat } from "@ai-sdk/react"
import { lastAssistantMessageIsCompleteWithApprovalResponses } from "ai"

import { ChatAssistantMessage, ChatThread, ChatUserMessage } from "../chat-thread/chat-thread"
import { PromptInput, PromptInputActions, PromptInputBody, PromptInputSubmit, PromptInputTextarea } from "../prompt-input/prompt-input"
import { HextaMessageParts } from "@/components/blocks/hexta-ai/message-parts"
import { textOf, type HextaMessage, type ToolPart } from "@/components/blocks/hexta-ai/parts"

export function Assistant() {
  const { messages, status, sendMessage, stop, regenerate, addToolApprovalResponse } = useChat({
    sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithApprovalResponses,
  })
  const busy = status === "submitted" || status === "streaming"
  const chat = messages as HextaMessage[]

  const approvalId = (toolCallId: string) =>
    chat
      .flatMap((message) => message.parts)
      .find((part): part is ToolPart => "toolCallId" in part && part.toolCallId === toolCallId)
      ?.approval?.id

  return (
    <ChatThread
      busy={busy}
      composer={
        <PromptInput status={status} onStop={stop} onSubmit={({ text }) => sendMessage({ text })}>
          <PromptInputBody>
            <PromptInputTextarea />
            <PromptInputActions>
              <PromptInputSubmit />
            </PromptInputActions>
          </PromptInputBody>
        </PromptInput>
      }
    >
      {chat.map((message, index) => {
        const last = index === chat.length - 1
        if (message.role === "user") {
          return <ChatUserMessage key={message.id} id={message.id} text={textOf(message)} />
        }
        return (
          <ChatAssistantMessage
            key={message.id}
            id={message.id}
            text={textOf(message)}
            streaming={last && busy}
            last={last}
            onRetry={last ? () => regenerate() : undefined}
          >
            <HextaMessageParts
              parts={message.parts}
              streaming={last && busy}
              onApproval={(toolCallId, { approved, reason }) => {
                const id = approvalId(toolCallId)
                if (id) addToolApprovalResponse({ id, approved, reason })
              }}
              onPlanApprove={(toolCallId, todos) => {
                const id = approvalId(toolCallId)
                if (!id) return
                addToolApprovalResponse({
                  id,
                  approved: true,
                  reason: `Run this plan:\n${todos.map((todo, step) => `${step + 1}. ${todo.content}`).join("\n")}`,
                })
              }}
              onPlanCancel={(toolCallId) => {
                const id = approvalId(toolCallId)
                if (id) addToolApprovalResponse({ id, approved: false })
              }}
            />
          </ChatAssistantMessage>
        )
      })}
    </ChatThread>
  )
}
```

### Your own tools

Map a tool name to a renderer that returns its kind, subject and content. Tools you don't map fall back to built-in views or a JSON view.

```tsx
"use client"

import { CodeBlock } from "../code-block/code-block"
import { HextaMessageParts, type ToolRenderer } from "@/components/blocks/hexta-ai/message-parts"
import type { MessagePart } from "@/components/blocks/hexta-ai/parts"

const tools: Record<string, ToolRenderer> = {
  create_chart: (part) => {
    const input = part.input as { title?: string; spec?: string } | undefined
    return {
      kind: "write",
      subject: input?.title ?? "Chart",
      content: input?.spec ? <CodeBlock code={input.spec} language="json" filename="chart.json" /> : undefined,
    }
  },
}

export function Reply({ parts, streaming }: { parts: MessagePart[]; streaming: boolean }) {
  return <HextaMessageParts parts={parts} streaming={streaming} tools={tools} />
}
```

### Scripted demos

ScriptedChats streams AI SDK-shaped parts from a script, with real pacing, approvals and stop. Use it for product tours, onboarding and offline demos.

```tsx
"use client"

import * as React from "react"

import { HextaMessageParts } from "@/components/blocks/hexta-ai/message-parts"
import { textOf } from "@/components/blocks/hexta-ai/parts"
import { ScriptedChats, useScriptedChat, type Script } from "@/components/blocks/hexta-ai/scripted-chat"

const onboarding: Script = async (run) => {
  await run.think("**Picking a first step**\nShow them the one thing that makes the product click.")
  const search = await run.tool("web_search", { query: "best onboarding checklists" })
  await run.pause(600)
  search.finish({ results: 4 })
  await run.say("Start with **one task they can finish in a minute**, then show what it unlocked.")
}

export function ProductTour() {
  const [store] = React.useState(() => new ScriptedChats(() => onboarding))
  const { messages, status } = useScriptedChat(store, "tour")
  const busy = status === "submitted" || status === "streaming"

  return (
    <div className="flex flex-col gap-4">
      <button onClick={() => void store.send("tour", "How should onboarding start?")}>Play</button>
      {messages.map((message, index) =>
        message.role === "user" ? (
          <p key={message.id}>{textOf(message)}</p>
        ) : (
          <HextaMessageParts
            key={message.id}
            parts={message.parts}
            streaming={busy && index === messages.length - 1}
            reasoningDurations={message.metadata?.thoughts}
            onApproval={(id, approval) => store.decide(id, approval)}
          />
        )
      )}
    </div>
  )
}
```

## Anatomy

The parts you compose, from the outside in.

| Part | Description |
| --- | --- |
| `HextaMessageParts` | Renders one assistant message from its parts, in order: reasoning, plan, tool calls and Markdown. |
| `defaultTools` | Built-in renderers for read_file, list_files, grep, web_search, fetch, edit_file, write_file, bash and runTests. A failed command shows its error with Stack Trace, runTests streams into Test Results, and task calls run as Subagents. |
| `ScriptedChats, useScriptedChat` | An offline engine that streams AI SDK-shaped parts from scripts, with stop, regenerate, edit, approvals and plan review. |
| `textOf, sourcesOf, toBlocks` | Helpers that read text and sources from a message and group its parts the way the renderer does. |
| `HextaAIDemo` | The full app: Chat Sidebar, Chat Thread, Prompt Input and Voice Mode wired to ScriptedChats. |

## API reference

### HextaMessageParts

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `parts` | `MessagePart[]` | – | The message’s parts: text, reasoning, source-url, file and tool parts, as useChat returns them. |
| `streaming` | `boolean` | `false` | Whether this message is still arriving. The last reasoning or text block animates, and running tools stay live. |
| `stopped` | `boolean` | `false` | Marks running tools as cancelled and hides a pending plan review. |
| `tools` | `Record<string, ToolRenderer>` | `{}` | Renderers by tool name. Each gets the part and { stopped }, returns kind, subject, title, meta, content, exitCode or error, and overrides the built-in view. |
| `onApproval` | `(toolCallId, { approved, reason?, always? }) => void` | – | Called when someone allows or denies a tool call that is waiting for approval. |
| `onPlanApprove` | `(toolCallId, todos) => void` | – | Called with the edited plan when someone runs it from the review. |
| `onPlanCancel` | `(toolCallId) => void` | – | Called when the plan review is cancelled. |
| `onStop` | `() => void` | – | Called from Stop all while subagents are running. |
| `reasoningDurations` | `number[]` | – | Seconds spent on each reasoning block, so “Thought for” stays right after a reload. |

### ScriptedChats

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `new ScriptedChats(respond)` | `(prompt, files) => Script` | – | Picks the script that answers each message. |
| `send(chatId, text, files?, options?)` | `Promise<void>` | – | Adds a user message and streams the reply. options: model, thinking and instant, which skips all waiting. |
| `stop, regenerate, edit, append, remove` | `methods` | – | Stop the reply, redo the last one, resend from an edited message, add finished messages, or drop a chat. |
| `restore(chatId, checkpointId)` | `{ text, files, undo } \| null` | – | Drops the turn that left the checkpoint and everything after it, and returns its prompt with an undo. |
| `decide(toolCallId, decision)` | `void` | – | Answers a pending approval or plan review. Pass todos to run an edited plan. |
| `useScriptedChat(store, chatId)` | `{ messages, status, pinned }` | – | Subscribes a component to one chat. |

### Script

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `think(text)` | `Promise<void>` | – | Streams a reasoning part. Skipped when thinking is off. |
| `say(markdown)` | `Promise<void>` | – | Streams a text part in uneven chunks, like a real model. |
| `tool(name, input, { stream? })` | `Promise<ToolHandle>` | – | Adds a tool call, optionally streaming one input field. The handle can approve, progress, finish or fail it. |
| `plan(todos)` | `Promise<Todo[] \| null>` | – | Shows a plan for review and waits. Returns the edited plan, or null if cancelled. |
| `todos(todos), source(page), pause(ms)` | `methods` | – | Update the plan, cite a source, or wait. |

## Keyboard

| Key | Action |
| --- | --- |
| `⌘` `K` | Searches your chats. |
| `⌘` `⇧` `O` | Starts a new chat. |
| `⌘` `B` | Collapses the sidebar to icons, or opens it full screen on phones. |
| `Enter` | Sends the message. Shift+Enter adds a line. |
| `⌘` `↵` | Runs the plan while it’s being reviewed, or allows a tool call that is waiting. |
| `⌘` `⌫` | Denies the tool call that is waiting. |
| `Esc` | Stops the reply, closes a menu, or ends voice mode. |

## Accessibility

- Every part keeps the accessibility of the block that draws it: the thread announces new replies politely, tool calls and plans expose their state in text, citations name their source, and approvals are real buttons with keyboard shortcuts.
- Nothing important is shown only by motion or color. Spinners have labels like “Replying”, finished chats in the background get an “Unread reply” label, and diffs mark added and removed lines with signs as well as color.
- Streaming, shader and sheet animations all respect reduced motion. Voice mode works without speaking replies aloud, shows captions, and plays a sample conversation when there’s no microphone.

## Built with

The free HextaUI components HextaAI is made from. Each one installs on its own.

- [Button](https://hextaui.com/docs/button) - Buttons in every variant and size, with a built-in loading, success and error flow that skips the spinner for fast requests.
- [Dropdown menu](https://hextaui.com/docs/dropdown-menu) - A menu of actions and options behind a button, with groups, submenus, checkbox and radio items, and shortcuts.
- [Sidebar](https://hextaui.com/docs/sidebar) - An app sidebar that collapses to icons or off canvas, stays pinned under your header, and becomes a swipeable sheet on phones.
- [Toast](https://hextaui.com/docs/toast) - Brief messages that stack neatly, expand on hover, swipe away, and turn a loading state into success or error in place.
- [Tooltip](https://hextaui.com/docs/tooltip) - A short hint on hover or keyboard focus that opens after a brief rest, switches instantly between neighbours and shows shortcuts.

## Code

5 files, added to components/blocks/hexta-ai.
