Install the following dependencies:
Copy and paste the following code into your project.
Update import paths to match your project setup.
Install the AI SDK
```bash npm install ai @ai-sdk/react ```Create a chat API route that streams tool and text parts
You can use any `streamText(...).toUIMessageStreamResponse()` route shape used in your app. See [Prompt Input docs](/docs/components/prompt-input#vercel-ai-sdk-integration) for a minimal route scaffold.Map assistant parts to Chain of Thought steps
```tsx "use client"; import { useChat } from "@ai-sdk/react"; import { DefaultChatTransport, type UIMessage } from "ai"; import { ChainOfThought, ChainOfThoughtTrigger, ChainOfThoughtContent, ChainOfThoughtStep, ChainOfThoughtStepTitle, ChainOfThoughtStepContent, ChainOfThoughtComplete, type ChainOfThoughtStepStatus, } from "@/components/nexus-ui/chain-of-thought"; type StepVM = { id: string; label: string; status: ChainOfThoughtStepStatus; hasContent?: boolean; content?: React.ReactNode; }; function stepsFromAssistant(message: UIMessage): StepVM[] { return message.parts.flatMap((part, index) => { // AI SDK UI emits tool-specific part types: tool-Fetching forecast...
,
},
];
case "output-available":
return [
{
id: `weather-${index}`,
label: "Weather tool",
status: "completed" as const,
hasContent: true,
content: {JSON.stringify(part.output, null, 2)},
},
];
case "output-error":
return [
{
id: `weather-${index}`,
label: "Weather tool failed",
status: "error" as const,
hasContent: true,
content: {part.errorText}
,
},
];
}
}
if (part.type === "tool-getStockPrice") {
switch (part.state) {
case "input-available":
return [
{
id: `stock-${index}`,
label: "Running stock tool...",
status: "active" as const,
},
];
case "output-available":
return [
{
id: `stock-${index}`,
label: "Stock price tool",
status: "completed" as const,
hasContent: true,
content: {JSON.stringify(part.output, null, 2)},
},
];
case "output-error":
return [
{
id: `stock-${index}`,
label: "Stock price tool failed",
status: "error" as const,
hasContent: true,
content: {part.errorText}
,
},
];
}
}
return [];
});
}
export default function ChainOfThoughtWithUseChat() {
const { messages } = useChat({
transport: new DefaultChatTransport({ api: "/api/chat" }),
});
const assistant = [...messages].reverse().find((m) => m.role === "assistant");
if (!assistant) return null;
const steps = stepsFromAssistant(assistant);
if (steps.length === 0) return null;
return (
Install the following dependencies:
Copy and paste the following code into your project.
Update import paths to match your project setup.
Install the AI SDK and a provider that emits sources
Add **`ai`**, **`@ai-sdk/react`**, and a provider package whose models surface search or citation URLs in the UI message stream (for example **`@ai-sdk/perplexity`** for Sonar). Many chat models stream text only—without **`source-url`** (or equivalent) parts, you have nothing to map **`[1]`** to. ```bash npm install ai @ai-sdk/react @ai-sdk/perplexity ```Create a chat API route that streams sources
Call **`streamText`**, then return **`toUIMessageStreamResponse({ sendSources: true })`** so the client receives source metadata alongside text. Without **`sendSources`**, assistant messages may omit **`source-url`** parts even when the underlying model found URLs. Pick a model your provider documents as search- or citation-capable. ```ts title="app/api/chat/route.ts" import { convertToModelMessages, streamText, type UIMessage } from "ai"; import { perplexity } from "@ai-sdk/perplexity"; export async function POST(req: Request) { const { messages }: { messages: UIMessage[] } = await req.json(); const result = streamText({ model: perplexity("sonar"), messages: await convertToModelMessages(messages), }); return result.toUIMessageStreamResponse({ sendSources: true, }); } ```Add helpers that turn markers into citation UI
Assistant prose often contains bracket references (**`[1]`**, **`[1][2][4]`**). Treat the ordered list of **`source-url`** parts as the bibliography: **`[1]`** is the first URL, **`[2]`** the second, and so on. **`withInlineCitationLinks`** rewrites each run of adjacent markers into a single markdown link whose **`href`** uses a dedicated **`https://…`** prefix (custom schemes are often stripped by sanitizers). **`createInlineCitationComponents`** passes a custom **`a`** component to Streamdown: real links stay as **``**; marker links parse the id list, resolve rows from your sources array, and render **`Citation`**, **`CitationTrigger`**, and **`CitationContent`**. ```tsx title="lib/inline-citations.tsx" "use client"; import * as React from "react"; import { Citation, CitationCarousel, CitationCarouselContent, CitationCarouselHeader, CitationCarouselIndex, CitationCarouselItem, CitationCarouselNext, CitationCarouselPagination, CitationCarouselPrev, CitationContent, CitationItem, CitationSourcesBadge, CitationTrigger, type CitationSourceInput, } from "@/components/nexus-ui/citation"; const GROUP_RE = /((?:\[\d+\])+)/g; const ID_RE = /\[(\d+)\]/g; const PREFIX = "https://citations.local/"; export function withInlineCitationLinks(text: string) { return text.replace(GROUP_RE, (match) => { const ids = [...match.matchAll(ID_RE)] .map(([, id]) => Number(id)) .filter((id) => Number.isInteger(id) && id > 0); if (ids.length === 0) return match; const label = ids.map((id) => `[${id}]`).join(""); return `[${label}](${PREFIX}${ids.join(",")})`; }); } function parseIdsFromHref(href: string) { if (!href.startsWith(PREFIX)) return []; return href .slice(PREFIX.length) .split(",") .map((id) => Number(id)) .filter((id) => Number.isInteger(id) && id > 0); } function citationsFromIds(ids: number[], sources: CitationSourceInput[]) { return Array.from(new Set(ids)) .map((id) => sources[id - 1]) .filter(Boolean) as CitationSourceInput[]; } export function createInlineCitationComponents(sources: CitationSourceInput[]) { return { a: ({ href, children, ...props }: any) => { if (typeof href !== "string") { return React.createElement("a", { ...props, href }, children); } const ids = parseIdsFromHref(href); if (ids.length === 0) { return React.createElement("a", { ...props, href }, children); } const citations = citationsFromIds(ids, sources); if (citations.length === 0) return <>{children}; return ( <> {" "}Render assistant markdown with `useChat` and MessageMarkdown
For each assistant message, join **`text`** parts (for example with **`isTextUIPart`**), collect **`source-url`** parts into **`{ url, title }`** objects for **`Citation`**, then pass **`createInlineCitationComponents(sources)`** into **`MessageMarkdown`** via **`components`**. Feed **`withInlineCitationLinks(text)`** as children so markers become links before Streamdown renders. The example below shows one assistant turn; in a full chat, map **`messages`** the same way as in [Message](/docs/components/message#vercel-ai-sdk-integration). ```tsx title="app/citations-chat/page.tsx" "use client"; import * as React from "react"; import { useChat } from "@ai-sdk/react"; import { DefaultChatTransport, isTextUIPart, type UIMessage } from "ai"; import { MessageMarkdown } from "@/components/nexus-ui/message"; import { createInlineCitationComponents, withInlineCitationLinks, } from "@/lib/inline-citations"; function textFromMessage(message: UIMessage) { return message.parts.filter(isTextUIPart).map((p) => p.text).join(""); } function sourceUrlPartsFromMessage(message: UIMessage) { return message.parts.filter( (p): p is ExtractInstall the following dependencies:
Copy and paste the following code into your project.
Update import paths to match your project setup.
{messages
.filter((m) => m.role === "assistant")
.map((m) => (
{votes[m.id] ? "Thanks for your feedback." : "Was this response helpful?"}
))}
);
}
```
Conversation-based feedback [#conversation-based-feedback]
Show one feedback bar for the whole conversation (for example at the end of the thread).
```tsx
"use client";
import { useState } from "react";
import { useChat } from "@ai-sdk/react";
import { DefaultChatTransport } from "ai";
import { HugeiconsIcon } from "@hugeicons/react";
import { ThumbsUpIcon, ThumbsDownIcon } from "@hugeicons/core-free-icons";
import { Button } from "@/components/ui/button";
import {
FeedbackBar,
FeedbackBarAction,
FeedbackBarActions,
FeedbackBarContent,
FeedbackBarLabel,
FeedbackBarPrompt,
} from "@/components/nexus-ui/feedback-bar";
type Vote = "up" | "down";
export default function ConversationFeedback() {
const { messages } = useChat({
transport: new DefaultChatTransport({ api: "/api/chat" }),
});
const conversationId = "replace-with-your-session-id";
const [vote, setVote] = useStateInstall the following dependencies:
Copy and paste the following code into your project.
Update import paths to match your project setup.
Install the AI SDK
```bash npm install ai @ai-sdk/openai ```Create your chat route
```ts title="app/api/chat/route.ts" import { openai } from "@ai-sdk/openai"; import { generateImage } from "ai"; export async function POST(req: Request) { const { prompt }: { prompt: string } = await req.json(); const { image } = await generateImage({ model: openai.image("dall-e-3"), prompt: prompt, size: "1024x1024", }); return Response.json({ base64: image.base64, uint8Array: image.uint8Array ? Array.from(image.uint8Array) : undefined, mediaType: image.mediaType, }); } ```Call the route and render the generated image
```tsx "use client"; import { useState } from "react"; import { Image } from "@/components/nexus-ui/image"; type GeneratedImage = { base64?: string; uint8Array?: number[]; mediaType?: string; }; export function ChatWithImages() { const [prompt, setPrompt] = useState("A futuristic city skyline at sunset"); const [generatedImage, setGeneratedImage] = useState
setPrompt(e.target.value)}
className="w-full rounded-md border px-3 py-2"
/>
{generatedImage?.base64 || binaryImage ? (
);
}
```
Install the following dependencies:
Copy and paste the following code into your project.
Update import paths to match your project setup.
Install the AI SDK
```bash npm install ai @ai-sdk/react @ai-sdk/openai ```Create your chat API route
Use the same handler as in the Prompt Input docs: **`messages: await convertToModelMessages(messages)`** and **`return result.toUIMessageStreamResponse()`**.Map `messages` to Message
Use **`isTextUIPart`** from **`ai`** so you only aggregate **`type: "text"`** segments. Skip **`system`** turns unless you surface them deliberately. Assistant messages can also include **reasoning**, **tool**, **source**, and other part types—extend this loop when you need those in the UI. ```tsx "use client"; import { useChat } from "@ai-sdk/react"; import { DefaultChatTransport, isTextUIPart, type UIMessage } from "ai"; import { Message, MessageStack, MessageContent, MessageMarkdown, } from "@/components/nexus-ui/message"; function textFromMessage(message: UIMessage) { return message.parts.filter(isTextUIPart).map((p) => p.text).join(""); } export default function ChatThread() { const { messages } = useChat({ transport: new DefaultChatTransport({ api: "/api/chat" }), }); return (
{messages
.filter((m) => m.role !== "system")
.map((m) => (
{textFromMessage(m)}
))}
);
}
```
Install the following dependencies:
Copy and paste the following code into your project.
Update import paths to match your project setup.
Install the AI SDK
```bash npm install ai @ai-sdk/react @ai-sdk/openai ```Create your chat API route
Create a route that reads `model` from the request body: ```ts title="app/api/chat/route.ts" import { convertToModelMessages, streamText, UIMessage } from "ai"; import { openai } from "@ai-sdk/openai"; export async function POST(req: Request) { const { messages, model = "gpt-4o-mini" }: { messages: UIMessage[]; model?: string } = await req.json(); const result = streamText({ model: openai(model), system: "You are a helpful assistant.", messages: await convertToModelMessages(messages), }); return result.toUIMessageStreamResponse(); } ```Wire Model Selector + Prompt Input to `useChat`
```tsx "use client"; import { useState } from "react"; import { useChat } from "@ai-sdk/react"; import { DefaultChatTransport } from "ai"; import { Button } from "@/components/ui/button"; import { PromptInput, PromptInputActions, PromptInputAction, PromptInputActionGroup, PromptInputTextarea, } from "@/components/nexus-ui/prompt-input"; import { ModelSelector, ModelSelectorContent, ModelSelectorGroup, ModelSelectorLabel, ModelSelectorRadioGroup, ModelSelectorRadioItem, ModelSelectorTrigger, } from "@/components/nexus-ui/model-selector"; import ChatgptIcon from "@/components/svgs/chatgpt"; import { ArrowUp02Icon, PlusSignIcon, SquareIcon, } from "@hugeicons/core-free-icons"; import { HugeiconsIcon } from "@hugeicons/react"; const models = [ { value: "gpt-4", icon: ChatgptIcon, title: "GPT-4", description: "Most capable" }, { value: "gpt-4o-mini", icon: ChatgptIcon, title: "GPT-4o Mini", description: "Fast" }, { value: "gpt-4o", icon: ChatgptIcon, title: "GPT-4o", description: "Multimodal" }, ]; export default function ChatWithModelSelector() { const [model, setModel] = useState("gpt-4o-mini"); const { sendMessage, status } = useChat({ transport: new DefaultChatTransport({ api: "/api/chat", prepareSendMessagesRequest: ({ body }) => ({ body: { ...body, model }, }), }), }); const [input, setInput] = useState(""); const isLoading = status !== "ready"; const handleSubmit = (value?: string) => { const text = (value ?? input).trim(); if (text) { sendMessage({ text }); setInput(""); } }; return ( ); } ```` props.
",
description: "Optional icon component for the item.",
},
indicator: {
type: "React.ReactNode",
default: "CheckIcon",
description:
"Custom indicator to show when selected. Renders inside ItemIndicator.",
},
title: {
type: "string",
description: "Optional title. Override with children for full control.",
},
description: {
type: "string",
description: "Optional description shown below the title.",
},
}}
/>
ModelSelectorRadioItem [#modelselectorradioitem]
A radio-style item for single selection. Shows a check when selected, or a lock icon when `disabled`.
",
description: "Optional icon component for the item.",
},
indicator: {
type: "React.ReactNode",
default: "CheckIcon",
description:
"Custom indicator to show when selected. Renders inside ItemIndicator.",
},
title: {
type: "string",
description: "Optional title. Override with children for full control.",
},
description: {
type: "string",
description: "Optional description shown below the title.",
},
}}
/>
Other primitives [#other-primitives]
`ModelSelectorContent`, `ModelSelectorPortal`, `ModelSelectorGroup`, `ModelSelectorLabel`, `ModelSelectorRadioGroup`,
`ModelSelectorSeparator`, `ModelSelectorSub`, `ModelSelectorSubTrigger`, and `ModelSelectorSubContent` accept the
same props as their Radix Dropdown Menu counterparts. See the
[Radix Dropdown Menu documentation](https://www.radix-ui.com/primitives/docs/components/dropdown-menu) for details.
`ModelSelectorItemTitle`, `ModelSelectorItemDescription`, `ModelSelectorItemIcon`, and `ModelSelectorItemIndicator`
are low-level building blocks used by CheckboxItem and RadioItem. Use them when composing custom item content with `children`.
# Prompt Input
import PromptInputDefault from "@/components/nexus-ui/examples/prompt-input/default";
import PromptInputBasic from "@/components/nexus-ui/examples/prompt-input/basic";
import GeminiInput from "@/components/nexus-ui/examples/prompt-input/gemini-input";
import PromptInputMultipleActions from "@/components/nexus-ui/examples/prompt-input/multiple-actions";
A flexible, composable input component for building chat interfaces. Includes an auto-resizing textarea with scroll support and customizable action slots for buttons like send, attach, and more.
Installation [#installation]
```bash
npx shadcn@latest add @nexus-ui/prompt-input
```
```bash
pnpm dlx shadcn@latest add @nexus-ui/prompt-input
```
```bash
yarn dlx shadcn@latest add @nexus-ui/prompt-input
```
```bash
bunx shadcn@latest add @nexus-ui/prompt-input
```
```bash
npx shadcn@latest add textarea scroll-area tooltip kbd && npm install @radix-ui/react-slot
```
```bash
pnpm dlx shadcn@latest add textarea scroll-area tooltip kbd && pnpm add @radix-ui/react-slot
```
```bash
yarn dlx shadcn@latest add textarea scroll-area tooltip kbd && yarn add @radix-ui/react-slot
```
```bash
bunx shadcn@latest add textarea scroll-area tooltip kbd && bun add @radix-ui/react-slot
```
Usage [#usage]
```tsx keepBackground
import {
PromptInput,
PromptInputTextarea,
PromptInputActions,
PromptInputActionGroup,
PromptInputAction,
} from "@/components/nexus-ui/prompt-input";
```
```tsx keepBackground
{/* Left-aligned actions */}
{/* Right-aligned actions */}
```
Examples [#examples]
Basic [#basic]
A minimal prompt input with just a textarea and send button.
With Multiple Actions [#with-multiple-actions]
Combine multiple action buttons in a single group and add built-in tooltips using `PromptInputAction`'s `tooltip` prop (string or object with `content`, optional `side`, and optional `shortcut`).
Vercel AI SDK Integration [#vercel-ai-sdk-integration]
Connect Prompt Input to the [Vercel AI SDK](https://sdk.vercel.ai) for streaming chat interfaces.
API Reference [#api-reference]
PromptInput [#promptinput]
The root container that wraps the textarea and action bar.
void (optional)",
description:
"Called when Enter is pressed in the textarea (without Shift). Receives the current textarea value. Use with value/onChange on PromptInputTextarea for controlled mode. Shift+Enter inserts a new line.",
},
className: {
type: "string",
description: "Additional CSS classes to apply to the container.",
},
onClick: {
type: "React.MouseEventHandler",
description:
"Called after the internal click handler. The internal handler focuses the textarea when clicking non-interactive areas.",
},
}}
/>
PromptInputTextarea [#promptinputtextarea]
An auto-resizing textarea wrapped in a scroll area. Accepts all standard `textarea` props including `disabled` and `onKeyDown`. Use `onSubmit` on PromptInput for Enter-to-submit; Shift+Enter inserts a new line.
",
description: "Called when the value changes. Use with value for controlled mode.",
},
onKeyDown: {
type: "React.KeyboardEventHandler",
description: "Called when a key is pressed. Fired after the internal Enter/Shift+Enter handler.",
},
placeholder: {
type: "string",
default: '"How can I help you today?"',
description: "Placeholder text displayed when the textarea is empty.",
},
ref: {
type: "React.Ref",
description:
"Forwarded ref to the textarea element. Merged with the internal ref used for click-to-focus.",
},
value: {
type: "string",
description: "Controlled value. Use with onChange for controlled mode.",
},
}}
/>
PromptInputActions [#promptinputactions]
A flex container for action buttons. Uses `justify-between` to position child groups at opposite ends.
Installation [#installation]
```bash
npx shadcn@latest add @nexus-ui/questions
```
```bash
pnpm dlx shadcn@latest add @nexus-ui/questions
```
```bash
yarn dlx shadcn@latest add @nexus-ui/questions
```
```bash
bunx shadcn@latest add @nexus-ui/questions
```
```bash
npx shadcn@latest add carousel button card checkbox && npm install @hugeicons/react @hugeicons/core-free-icons
```
```bash
pnpm dlx shadcn@latest add carousel button card checkbox && pnpm add @hugeicons/react @hugeicons/core-free-icons
```
```bash
yarn dlx shadcn@latest add carousel button card checkbox && yarn add @hugeicons/react @hugeicons/core-free-icons
```
```bash
bunx shadcn@latest add carousel button card checkbox && bun add @hugeicons/react @hugeicons/core-free-icons
```
Usage [#usage]
```tsx keepBackground noCollapse
import {
Question,
QuestionOption,
QuestionOptions,
QuestionOther,
Questions,
QuestionsFooter,
QuestionsHeader,
QuestionsSubmit,
QuestionsTitle,
type QuestionInput,
} from "@/components/nexus-ui/questions";
```
```tsx keepBackground noCollapse
const question: QuestionInput = {
id: "depth",
type: "single",
prompt: "How detailed should the explanation be?",
options: [
{ value: "brief", label: "Brief overview" },
{ value: "standard", label: "Standard depth" },
],
};
console.log(submission)}
>
{question.options.map((option) => (
{option.label}
))}
```
Pass **`items`** so **`QuestionsTitle`** and carousel pagination have question metadata on the first paint. For a single question, compose **`Question`** directly without **`QuestionsCarousel`**; use the carousel primitives when there are multiple slides.
Examples [#examples]
Multiple choice [#multiple-choice]
Set **`type: "multiple"`** in **`items`** to render checkbox rows. Users select one or more options before submitting—multiple choice does not auto-advance.
Multiple questions [#multiple-questions]
For two or more prompts, wrap slides in **`QuestionsCarousel`**. Prev/next controls and pagination stay in sync with the active index; required questions block forward navigation until answered.
Required questions [#required-questions]
Set **`required: true`** on every question in **`items`** to block forward navigation until each slide is answered. Omit **`QuestionsSkip`** when nothing is optional—skip only applies to unanswered optional questions. Omit **`QuestionsDismiss`** (and **`onDismiss`**) when you want a forced flow.
Fixed options [#fixed-options]
Omit **`QuestionOther`** when the question should only accept predefined options.
Vercel AI SDK Integration [#vercel-ai-sdk-integration]
Use **Questions** when an agent needs structured clarification before continuing—for example a **`askClarifyingQuestions`** tool that streams arguments to the client and waits for the user's answers.
The usual pattern:
1. Define a tool **without** **`execute`** so the model stops after emitting question definitions.
2. Render **`Questions`** when the tool part reaches **`input-available`**.
3. Call **`addToolOutput`** (or **`addToolResult`**) in **`onSubmit`** with the submission payload.
4. Optionally use **`sendAutomaticallyWhen`** so the chat resumes after the tool output is added.
This flow is client-side tool handling. The model proposes questions; your UI collects answers and returns them as the tool result so the agent can continue.
Render tool input as Questions and return answers with
Find the latest assistant message with an **`askClarifyingQuestions`** tool part in **`input-available`** state, map **`part.input.questions`** to **`items`**, and wire **`onSubmit`** to **`addToolOutput`**. Use **`sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithToolCalls`** (or your own predicate) so the model continues after answers are submitted.
```tsx title="app/clarification-chat/page.tsx"
"use client";
import { useChat } from "@ai-sdk/react";
import {
DefaultChatTransport,
lastAssistantMessageIsCompleteWithToolCalls,
type UIMessage,
} from "ai";
import {
Question,
QuestionOption,
QuestionOptions,
QuestionOther,
Questions,
QuestionsCarousel,
QuestionsCarouselContent,
QuestionsCarouselIndex,
QuestionsCarouselItem,
QuestionsCarouselNext,
QuestionsCarouselPagination,
QuestionsCarouselPrev,
QuestionsFooter,
QuestionsHeader,
QuestionsSkip,
QuestionsSubmit,
QuestionsTitle,
type QuestionInput,
type QuestionsSubmission,
} from "@/components/nexus-ui/questions";
type ClarifyingQuestionsInput = {
questions: QuestionInput[];
};
type ClarifyingQuestionsToolPart = {
type: "tool-askClarifyingQuestions";
toolCallId: string;
state: "input-available" | "output-available" | "output-error";
input?: ClarifyingQuestionsInput;
};
function findPendingClarification(messages: UIMessage[]) {
const assistant = [...messages].reverse().find((m) => m.role === "assistant");
if (!assistant) return null;
return assistant.parts.find(
(part): part is ClarifyingQuestionsToolPart =>
part.type === "tool-askClarifyingQuestions" &&
part.state === "input-available" &&
Boolean((part as ClarifyingQuestionsToolPart).input?.questions?.length),
);
}
export default function ClarificationChatPage() {
const { messages, addToolOutput, status } = useChat({
transport: new DefaultChatTransport({ api: "/api/chat" }),
sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithToolCalls,
});
const pending = findPendingClarification(messages);
if (!pending?.input?.questions) return null;
const items = pending.input.questions;
function handleSubmit(submission: QuestionsSubmission) {
void addToolOutput({
tool: "askClarifyingQuestions",
toolCallId: pending.toolCallId,
output: { answers: submission },
});
}
return (
) : null}
{items.map((question) => (
{question.options.map((option) => (
{option.label}
))}
))}
{items.length > 1 ?
);
}
```
API Reference [#api-reference]
Questions [#questions]
Root card and state container. Manages answer state, active index, carousel sync, skip/submit rules, and typed submission payloads. Extends shadcn **[Card](https://ui.shadcn.com/docs/components/radix/card)**.
void",
description:
"Fired when Submit is clicked and every required question is answered. Skipped or unanswered optional questions use answer label \"[No Preference]\". Clears selections and resets to the first question.",
},
onSkip: {
type: "(questionId: string) => void",
description: "Called when Skip advances past the current question.",
},
onDismiss: {
type: "() => void",
description: "Called when QuestionsDismiss is clicked.",
},
className: {
type: "string",
description: "Merged with the default card shell styles.",
},
children: {
type: "React.ReactNode",
description:
"Composition tree: header, carousel or question slides, and footer.",
},
}}
/>
QuestionsHeader [#questionsheader]
Top bar layout shell for title, pagination, and dismiss controls. Extends shadcn **`CardHeader`**.
",
description: "Optional click handler. Called before onDismiss runs.",
},
}}
/>
QuestionsCarousel [#questionscarousel]
[**Carousel**](https://ui.shadcn.com/docs/components/radix/carousel) root for multi-question slides. Registers the Embla API on **`Questions`** for index sync and animated viewport height.
void",
description:
"Optional; invoked when the Embla instance is ready or cleared.",
},
className: {
type: "string",
description: "Classes on the carousel region wrapper.",
},
children: {
type: "React.ReactNode",
description: "Typically QuestionsHeader and QuestionsCarouselContent.",
},
}}
/>
QuestionsCarouselPagination [#questionscarouselpagination]
Flex row for prev / index / next controls.
",
description:
"Optional click handler for single choice. Called before selection.",
},
}}
/>
QuestionOther [#questionother]
Free-text **Other** row. Compose only when free-text answers are allowed. Uses **`QUESTION_OTHER_VALUE`** (`"__other__"`) as the stored value when selected. Typing selects **Other** (single and multiple); multiple choice also pairs with a checkbox.
",
description: "Forwarded to the text input.",
},
}}
/>
QuestionsFooter [#questionsfooter]
Bottom bar layout shell for skip and submit actions. Extends shadcn **`CardFooter`**.
",
description: "Optional click handler. Called before skip runs.",
},
}}
/>
QuestionsSubmit [#questionssubmit]
Primary **Submit** button. Disabled while any **required** question is unanswered; optional unanswered questions are allowed. Extends shadcn **`Button`**.
",
description: "Optional click handler. Called before submit runs.",
},
children: {
type: "React.ReactNode",
default: '"Submit"',
description: "Button label.",
},
}}
/>
Types [#types]
```ts noCollapse
export type QuestionOptionInput = {
value: string;
label: React.ReactNode;
};
export type QuestionInput = {
id: string;
type: "single" | "multiple";
prompt: React.ReactNode;
options: QuestionOptionInput[];
required?: boolean;
};
export type QuestionSubmissionAnswer = {
value: string;
label: React.ReactNode;
};
export type QuestionsSubmission = Array<
| {
questionId: string;
prompt: React.ReactNode;
type: "single";
status: "answered";
answer: QuestionSubmissionAnswer;
}
| {
questionId: string;
prompt: React.ReactNode;
type: "single";
status: "skipped";
answer: QuestionSubmissionAnswer;
}
| {
questionId: string;
prompt: React.ReactNode;
type: "multiple";
status: "answered";
answer: QuestionSubmissionAnswer[];
}
| {
questionId: string;
prompt: React.ReactNode;
type: "multiple";
status: "skipped";
answer: QuestionSubmissionAnswer[];
}
>;
export const QUESTION_OTHER_VALUE = "__other__";
export const QUESTION_NO_PREFERENCE_VALUE = "__no_preference__";
export const QUESTION_NO_PREFERENCE_LABEL = "[No Preference]";
```
# Reasoning
import ReasoningDefault from "@/components/nexus-ui/examples/reasoning/default";
Collapsible reasoning UI for assistant "thinking" traces. The root tracks streaming state to update the trigger label (`Thinking...` -> `Thought for N seconds`) and auto-opens/closes content while reasoning streams.
Installation [#installation]
```bash
npx shadcn@latest add @nexus-ui/reasoning
```
```bash
pnpm dlx shadcn@latest add @nexus-ui/reasoning
```
```bash
yarn dlx shadcn@latest add @nexus-ui/reasoning
```
```bash
bunx shadcn@latest add @nexus-ui/reasoning
```
```bash
npx shadcn@latest add collapsible && npm install @hugeicons/react @hugeicons/core-free-icons streamdown tw-shimmer
```
```bash
pnpm dlx shadcn@latest add collapsible && pnpm add @hugeicons/react @hugeicons/core-free-icons streamdown tw-shimmer
```
```bash
yarn dlx shadcn@latest add collapsible && yarn add @hugeicons/react @hugeicons/core-free-icons streamdown tw-shimmer
```
```bash
bunx shadcn@latest add collapsible && bun add @hugeicons/react @hugeicons/core-free-icons streamdown tw-shimmer
```
Usage [#usage]
```tsx keepBackground
import {
Reasoning,
ReasoningTrigger,
ReasoningContent,
} from "@/components/nexus-ui/reasoning";
```
```tsx keepBackground noCollapse
{reasoningMarkdown}
```
Vercel AI SDK Integration [#vercel-ai-sdk-integration]
Some models emit structured reasoning parts in the AI SDK response stream. In practice, models like **DeepSeek R1** and **Claude** can return reasoning content that you can render with `Reasoning`.
Use `Reasoning` with [Vercel AI SDK](https://sdk.vercel.ai) by mapping assistant `reasoning` parts to:
* `isStreaming`: true while reasoning parts are still streaming
* `ReasoningContent` children: merged reasoning text
Render assistant reasoning parts with
```tsx
"use client";
import { useChat } from "@ai-sdk/react";
import { DefaultChatTransport, isReasoningUIPart, type UIMessage } from "ai";
import {
Reasoning,
ReasoningContent,
ReasoningTrigger,
} from "@/components/nexus-ui/reasoning";
function reasoningPartsFromMessage(message: UIMessage) {
return message.parts.filter(isReasoningUIPart);
}
function reasoningTextFromMessage(message: UIMessage) {
return reasoningPartsFromMessage(message).map((p) => p.text).join("");
}
function reasoningStreamingFromMessage(message: UIMessage) {
const parts = reasoningPartsFromMessage(message);
return parts.some((p) => p.state === "streaming");
}
export default function ReasoningWithUseChat() {
const { messages } = useChat({
transport: new DefaultChatTransport({ api: "/api/chat" }),
});
const assistant = [...messages].reverse().find((m) => m.role === "assistant");
if (!assistant) return null;
const reasoningText = reasoningTextFromMessage(assistant);
const isReasoningStreaming = reasoningStreamingFromMessage(assistant);
if (!reasoningText.trim()) return null;
return (
{reasoningText}
);
}
```
API Reference [#api-reference]
Reasoning [#reasoning]
Root component. Manages streaming timing, open state behavior, and label context for children. Wraps [Collapsible](https://www.radix-ui.com/primitives/docs/components/collapsible#root).
void",
description:
"Called when open state changes (manual toggle or internal stream-driven open/close).",
},
className: {
type: "string",
description: "Additional classes for the root collapsible wrapper.",
},
}}
/>
ReasoningTrigger [#reasoningtrigger]
Trigger row with built-in brain icon, label text, and rotating chevron. If `children` is provided, it replaces the default label text. Wraps [Collapsible Trigger](https://www.radix-ui.com/primitives/docs/components/collapsible#trigger). The shimmer label effect is powered by `tw-shimmer`; see [tw-shimmer docs](https://www.assistant-ui.com/tw-shimmer) for customization options.
Installation [#installation]
```bash
npx shadcn@latest add @nexus-ui/suggestions
```
```bash
pnpm dlx shadcn@latest add @nexus-ui/suggestions
```
```bash
yarn dlx shadcn@latest add @nexus-ui/suggestions
```
```bash
bunx shadcn@latest add @nexus-ui/suggestions
```
```bash
npx shadcn@latest add button && npm install @radix-ui/react-presence @radix-ui/react-slot class-variance-authority
```
```bash
pnpm dlx shadcn@latest add button && pnpm add @radix-ui/react-presence @radix-ui/react-slot class-variance-authority
```
```bash
yarn dlx shadcn@latest add button && yarn add @radix-ui/react-presence @radix-ui/react-slot class-variance-authority
```
```bash
bunx shadcn@latest add button && bun add @radix-ui/react-presence @radix-ui/react-slot class-variance-authority
```
Usage [#usage]
```tsx keepBackground
import {
Suggestions,
SuggestionList,
Suggestion,
} from "@/components/nexus-ui/suggestions";
```
```tsx keepBackground
handleSuggestion(value)}>
Tell me a joke
Explain quantum computing
```
Examples [#examples]
Variants [#variants]
The `Suggestion` component supports three variants: `filled` (filled background), `outline` (bordered), and `ghost` (transparent until hovered).
Vertical Layout [#vertical-layout]
Use `orientation="vertical"` on `SuggestionList` to stack suggestions in a column.
With Custom Value [#with-custom-value]
Use the `value` prop when the display text differs from the value passed to `onSelect`.
With Icons [#with-icons]
Since `Suggestion` renders a shadcn `Button`, you can add icons alongside text.
With Prompt Input [#with-prompt-input]
Clicking a suggestion populates the `PromptInput` textarea, combining both components.
With Panel [#with-panel]
Category chips that open a panel with related suggestions. Uses the `highlight` prop to style matching terms.
Vercel AI SDK Integration [#vercel-ai-sdk-integration]
Combine Suggestions with [Prompt Input](/docs/components/prompt-input) and the [Vercel AI SDK](https://sdk.vercel.ai) for a chat interface with quick-start prompts.
setInput(value)}>
What is AI?
Teach me Engineering from scratch
How to learn React?
Design a weekly workout plan
Places to visit in France
);
}
```
For one-click submission (suggestion sends immediately without editing), call `sendMessage` in `onSelect`:
```tsx
{
if (value.trim()) {
sendMessage({ text: value });
setInput("");
}
}}
>
```
API Reference [#api-reference]
Suggestions [#suggestions]
The root container that provides `onSelect` context to all child `Suggestion` components. Extends `React.HTMLAttributes`.
void",
description:
"Callback fired when any Suggestion is clicked. Receives the suggestion's value or text content.",
},
className: {
type: "string",
description: "Additional CSS classes to apply to the root container.",
},
}}
/>
SuggestionList [#suggestionlist]
Layout wrapper for arranging suggestions horizontally or vertically. Extends `React.HTMLAttributes`.
",
description: "Optional click handler. Called before onSelect.",
},
className: {
type: "string",
description: "Additional CSS classes to apply to the button.",
},
}}
/>
SuggestionPanel [#suggestionpanel]
Full-width panel that displays below the input, covering the category pills. Uses `Presence` for enter/exit animations. Closes on Escape via `onOpenChange`. Use with `SuggestionPanelHeader`, `SuggestionPanelTitle`, `SuggestionPanelClose`, and `SuggestionPanelContent`.
void",
description:
"Callback fired when the panel open state changes (e.g. Escape key, SuggestionPanelClose click).",
},
onClose: {
type: "() => void",
description:
"Callback fired when the panel's exit animation completes. Use for cleanup (e.g. focus management).",
},
className: {
type: "string",
description: "Additional CSS classes to apply to the panel container.",
},
ref: {
type: "React.Ref",
description: "Forwarded ref to the panel div element.",
},
}}
/>
SuggestionPanelHeader [#suggestionpanelheader]
Header row for the panel. Typically contains `SuggestionPanelTitle` and `SuggestionPanelClose`. Extends `React.HTMLAttributes`.
`.
`.
",
description: "Optional click handler. Called after the panel close is triggered.",
},
className: {
type: "string",
description: "Additional CSS classes to apply to the close button.",
},
}}
/>
SuggestionPanelContent [#suggestionpanelcontent]
Content wrapper for the panel's suggestion list. Use with `Suggestions` and `SuggestionList` inside. Use `asChild` to merge props onto a child element. Extends `React.HTMLAttributes`.
Installation [#installation]
```bash
npx shadcn@latest add @nexus-ui/text-shimmer
```
```bash
pnpm dlx shadcn@latest add @nexus-ui/text-shimmer
```
```bash
yarn dlx shadcn@latest add @nexus-ui/text-shimmer
```
```bash
bunx shadcn@latest add @nexus-ui/text-shimmer
```
Usage [#usage]
```tsx keepBackground noLineNumbers
import { TextShimmer } from "@/components/nexus-ui/text-shimmer";
```
```tsx keepBackground noLineNumbers
Running tool calls...
```
Examples [#examples]
With Repeat Delay [#with-repeat-delay]
Use `repeatDelay` to create a pause between shimmer passes:
Angled Shimmer [#angled-shimmer]
Tune beam geometry with `spread` and `angle`:
Inverted Contrast [#inverted-contrast]
Use `invert` for lower-luminance emphasis (often better on lighter text):
As Custom Element [#as-custom-element]
Render another element type with `as`:
Custom Highlight Color [#custom-highlight-color]
Use `color` to override the highlight beam for accent-driven states:
Slow Sweep [#slow-sweep]
Increase `duration` for a calmer motion profile:
{/* ### Tight Beam
Lower `spread` for a narrower, sharper highlight pass:
*/}
API Reference [#api-reference]
TextShimmer [#textshimmer]
Animated text wrapper component. Uses a generated keyframe name per instance to avoid collisions and applies shimmer via a gradient background clipped to text.
Installation [#installation]
```bash
npx shadcn@latest add @nexus-ui/thread
```
```bash
pnpm dlx shadcn@latest add @nexus-ui/thread
```
```bash
yarn dlx shadcn@latest add @nexus-ui/thread
```
```bash
bunx shadcn@latest add @nexus-ui/thread
```
```bash
npm install @radix-ui/react-slot @hugeicons/react @hugeicons/core-free-icons use-stick-to-bottom
```
```bash
pnpm add @radix-ui/react-slot @hugeicons/react @hugeicons/core-free-icons use-stick-to-bottom
```
```bash
yarn add @radix-ui/react-slot @hugeicons/react @hugeicons/core-free-icons use-stick-to-bottom
```
```bash
bun add @radix-ui/react-slot @hugeicons/react @hugeicons/core-free-icons use-stick-to-bottom
```
Usage [#usage]
```tsx keepBackground
import {
Thread,
ThreadContent,
ThreadScrollToBottom,
} from "@/components/nexus-ui/thread";
```
```tsx keepBackground
{/* messages */}
```
**`ThreadScrollToBottom`** must be rendered **inside** **`Thread`** so it can read **`useStickToBottomContext`**.
Vercel AI SDK Integration [#vercel-ai-sdk-integration]
Render [`useChat`](https://ai-sdk.dev/docs/reference/ai-sdk-ui/use-chat) messages inside **Thread** by mapping the same **`messages`** array you would render with **[Message](/docs/components/message)** alone. Read each **[`UIMessage`](https://ai-sdk.dev/docs/reference/ai-sdk-core/ui-message)** **`parts`** array and join **`text`** parts for **MessageMarkdown** (streaming updates apply as the SDK appends or grows **`TextUIPart`** content).
See [Prompt Input](/docs/components/prompt-input#vercel-ai-sdk-integration) for a minimal **`POST /api/chat`** route with **`streamText`** and **`toUIMessageStreamResponse`**.
{messages
.filter((m) => m.role !== "system")
.map((m) => (
{textFromMessage(m)}
))}
);
}
```
API Reference [#api-reference]
Thread [#thread]
Root scroll container wrapping [**`StickToBottom`**](https://github.com/stackblitz/use-stick-to-bottom). **`ThreadContent`** and **`ThreadScrollToBottom`** must live under **`Thread`** so the scrollable list and jump control share the same stick-to-bottom context.
number",
description: "Optional override to compute scroll top from layout.",
},
contextRef: {
type: "Ref",
description: "Optional ref to the library context object.",
},
instance: {
type: "StickToBottomInstance",
description: "Optional external instance from useStickToBottom.",
},
className: {
type: "string",
description: "Additional CSS classes to apply to the thread root.",
},
children: {
type: "ReactNode | ((context) => ReactNode)",
description:
"Typically ThreadContent plus ThreadScrollToBottom; render props receive the library context if needed.",
},
}}
/>
ThreadContent [#threadcontent]
Wraps the transcript—usually **`Message`** rows—so **`Thread`** can keep the viewport following the bottom as new content arrives (**`StickToBottom.Content`**).
ReactNode)",
description: "Message list or other thread body.",
},
}}
/>
ThreadScrollToBottom [#threadscrolltobottom]
Optional control that appears when the user has scrolled away from the bottom, so they can jump back to the latest messages. Supports polymorphism via **`asChild`**.
Installation [#installation]
Run the following command:
```bash
npx shadcn@latest add @nexus-ui/toaster
```
Add the
`Toaster`
component
```tsx title="app/layout.tsx"
import { Toaster } from "@/components/nexus-ui/toaster"
export default function RootLayout({ children }) {
return (
{children}
Install the following dependencies:
```bash
npx shadcn@latest add button && npm install @hugeicons/core-free-icons @hugeicons/react next-themes sonner
```
Copy and paste the following code into your project.
Add the
`Toaster`
component
```tsx title="app/layout.tsx"
import { Toaster } from "@/components/nexus-ui/toaster"
export default function RootLayout({ children }) {
return (
{children}
)
}
```
Usage [#usage]
```tsx keepBackground noLineNumbers
import { toast } from "@/components/nexus-ui/toaster";
```
```tsx keepBackground noLineNumbers
toast.default("Event has been created.");
```
Examples [#examples]
With Description [#with-description]
Add supporting copy with the `description` option.
With Action [#with-action]
Add an inline CTA using the `action` option.
Variants [#variants]
Change the variant on each toast call to control the feedback type and visual style.
Position [#position]
Show toasts in different corners and center positions using per-toast `position`.
API Reference [#api-reference]
toast [#toast]
Custom headless toast helper built on `sonnerToast.custom`. It renders the `Toast` UI while forwarding supported Sonner toast options for behavior and lifecycle.
void }",
description:
"Optional custom action button rendered inside the toast card.",
},
cancel: {
type: "{ label: React.ReactNode; onClick?: () => void }",
description:
"Optional secondary cancel button rendered inside the toast card.",
},
duration: {
type: "number",
default: "4000",
description:
"Auto-dismiss duration in milliseconds. Use `Infinity` to keep toast open.",
},
id: {
type: "string | number",
description: "Custom toast id for updates/deduping.",
},
position: {
type: '"top-left" | "top-center" | "top-right" | "bottom-left" | "bottom-center" | "bottom-right"',
description: "Override destination stack position for this toast.",
},
toasterId: {
type: "string",
description: "Route toast to a specific mounted toaster.",
},
dismissible: {
type: "boolean",
default: "true",
description: "Whether the toast can be dismissed by interaction.",
},
onDismiss: {
type: "() => void",
description: "Called when toast is dismissed.",
},
onAutoClose: {
type: "() => void",
description: "Called when toast closes from timeout.",
},
invert: {
type: "boolean",
default: "false",
description: "Use Sonner inverted styling mode where applicable.",
},
closeButton: {
type: "boolean",
default: "true",
description:
"Show/hide the custom toast close button for this toast instance.",
},
testId: {
type: "string",
description: "Testing identifier attached to toast node.",
},
}}
/>
Toaster [#toaster]
Custom wrapper that mounts Sonner and syncs `theme` from `next-themes`, with `toastOptions={{ unstyled: true }}` by default.
Installation [#installation]
```bash
npx shadcn@latest add @nexus-ui/tool
```
```bash
pnpm dlx shadcn@latest add @nexus-ui/tool
```
```bash
yarn dlx shadcn@latest add @nexus-ui/tool
```
```bash
bunx shadcn@latest add @nexus-ui/tool
```
```bash
npx shadcn@latest add badge collapsible && npm install @hugeicons/react @hugeicons/core-free-icons @react-symbols/icons shiki
```
```bash
pnpm dlx shadcn@latest add badge collapsible && pnpm add @hugeicons/react @hugeicons/core-free-icons @react-symbols/icons shiki
```
```bash
yarn dlx shadcn@latest add badge collapsible && yarn add @hugeicons/react @hugeicons/core-free-icons @react-symbols/icons shiki
```
```bash
bunx shadcn@latest add badge collapsible && bun add @hugeicons/react @hugeicons/core-free-icons @react-symbols/icons shiki
```
Usage [#usage]
```tsx keepBackground
import {
Tool,
ToolTrigger,
ToolContent,
ToolInput,
ToolOutput,
type ToolStatus,
} from "@/components/nexus-ui/tool";
```
```tsx keepBackground noCollapse
```
Examples [#examples]
Pending [#pending]
Set `status="pending"` and render only `ToolTrigger` + `ToolContent` while arguments are still streaming.
Ready [#ready]
Set `status="ready"`, render `ToolInput` with parsed arguments, and omit `ToolOutput` until execution starts.
Running [#running]
Set `status="running"` and keep only `ToolInput` visible while the tool call is in progress.
Error State [#error-state]
Set `status="error"`, keep `ToolInput` visible, and render `ToolOutput` with `errorText` (and `showWhen={["error"]}`) to show a destructive error message.
Vercel AI SDK Integration [#vercel-ai-sdk-integration]
`Tool` maps cleanly to AI SDK tool parts by converting streamed tool part state into `ToolStatus` and passing `input` / `output` payloads directly.
Use it with [Vercel AI SDK](https://sdk.vercel.ai) by:
* mapping AI SDK tool part states (`input-streaming`, `input-available`, `output-available`, `output-error`) into your UI states (`pending`, `ready`, `running`, `completed`, `error`)
* rendering `part.input` in `ToolInput`
* rendering `part.output` in `ToolOutput` when available
* passing `errorText` to `ToolOutput` for `error` state
`ready` is an app-level state in this mapping (for example, waiting on user approval before execution). AI SDK does not emit `ready` as a native tool part state.
`pending` via `input-streaming` is only available in streaming flows (for example, `streamText` / streamed UI messages).
Map assistant tool parts into
```tsx
"use client";
import { useChat } from "@ai-sdk/react";
import { DefaultChatTransport, type UIMessage } from "ai";
import {
Tool,
ToolTrigger,
ToolContent,
ToolInput,
ToolOutput,
type ToolStatus,
} from "@/components/nexus-ui/tool";
type ToolPartLike = {
type: string;
state?: string;
input?: unknown;
output?: unknown;
errorText?: string;
error?: unknown;
};
function mapToolStatus(
part: ToolPartLike,
isAwaitingApproval: boolean,
): ToolStatus | null {
switch (part.state) {
case "input-streaming":
// Streaming-only: arguments are still being generated.
return "pending";
case "input-available":
// App-level mapping: use "ready" while waiting for approval/user action.
return isAwaitingApproval ? "ready" : "running";
case "output-available":
return "completed";
case "output-error":
return "error";
default:
return null;
}
}
function toolNameFromPartType(type: string): string {
return type.startsWith("tool-") ? type.slice(5) : type;
}
export default function ToolCallsFromUseChat() {
const { messages } = useChat({
transport: new DefaultChatTransport({ api: "/api/chat" }),
});
const assistant = [...messages].reverse().find((m) => m.role === "assistant");
if (!assistant) return null;
const toolParts = assistant.parts.filter(
(part): part is ToolPartLike => part.type.startsWith("tool-"),
);
if (toolParts.length === 0) return null;
return (
API Reference [#api-reference]
Tool [#tool]
Root wrapper for a single tool call. Provides status context and status color tokens for child components. Wraps [Collapsible Root](https://www.radix-ui.com/primitives/docs/components/collapsible#root).
void",
description: "Called when open state changes.",
},
className: {
type: "string",
description: "Additional classes merged with the root container styles.",
},
}}
/>
ToolTrigger [#tooltrigger]
Header row for tool name, status icon, status badge, and expand/collapse chevron. Wraps [Collapsible Trigger](https://www.radix-ui.com/primitives/docs/components/collapsible#trigger).
',
default: '["completed"]',
description:
"Controls which tool states render the output section.",
},
errorText: {
type: "string",
description:
"Error message shown as a destructive text block when tool state is error.",
},
}}
/>
Install the following dependencies:
Copy and paste the following code into your project.
Update import paths to match your project setup.
Install the AI SDK
```bash npm install ai @ai-sdk/react @ai-sdk/openai ```Create your chat API route
```ts title="app/api/chat/route.ts" import { convertToModelMessages, streamText, UIMessage } from "ai"; import { openai } from "@ai-sdk/openai"; export async function POST(req: Request) { const { messages }: { messages: UIMessage[] } = await req.json(); const result = streamText({ model: openai("gpt-4o-mini"), system: "You are a helpful assistant.", messages: await convertToModelMessages(messages), }); return result.toUIMessageStreamResponse(); } ```Wire Prompt Input to `useChat`
Use `onSubmit` for Enter-to-submit. Shift+Enter inserts a new line. ```tsx "use client"; import { useState, useCallback } from "react"; import { useChat } from "@ai-sdk/react"; import { DefaultChatTransport } from "ai"; import { Button } from "@/components/ui/button"; import { PromptInput, PromptInputActions, PromptInputAction, PromptInputActionGroup, PromptInputTextarea, } from "@/components/nexus-ui/prompt-input"; import { ArrowUp02Icon, SquareIcon } from "@hugeicons/core-free-icons"; import { HugeiconsIcon } from "@hugeicons/react"; export default function ChatWithPromptInput() { const { sendMessage, status } = useChat({ transport: new DefaultChatTransport({ api: "/api/chat" }), }); const [input, setInput] = useState(""); const isLoading = status !== "ready"; const handleSubmit = useCallback( (value?: string) => { const trimmed = (value ?? input).trim(); if (trimmed) { sendMessage({ text: trimmed }); setInput(""); } }, [input, sendMessage], ); return ( ); } ```Install the following dependencies:
Copy and paste the following code into your project.
Update import paths to match your project setup.
Install the AI SDK
```bash npm install ai @ai-sdk/react zod ```Expose a clarification tool on your chat route
Define a tool with a Zod schema that matches **`QuestionInput`**. Omit **`execute`** so the client must supply the result. ```ts title="app/api/chat/route.ts" import { convertToModelMessages, streamText, tool, type UIMessage } from "ai"; import { z } from "zod"; const questionSchema = z.object({ id: z.string(), type: z.enum(["single", "multiple"]), prompt: z.string(), required: z.boolean().optional(), options: z.array( z.object({ value: z.string(), label: z.string(), }), ), }); export async function POST(req: Request) { const { messages }: { messages: UIMessage[] } = await req.json(); const result = streamText({ model: "anthropic/claude-sonnet-4.5", system: "When the user's request is ambiguous, call askClarifyingQuestions before answering.", messages: await convertToModelMessages(messages), tools: { askClarifyingQuestions: tool({ description: "Ask the user one or more clarifying questions before continuing.", inputSchema: z.object({ questions: z.array(questionSchema).min(1), }), }), }, }); return result.toUIMessageStreamResponse(); } ```
Render tool input as Questions and return answers with
addToolOutput
Find the latest assistant message with an **`askClarifyingQuestions`** tool part in **`input-available`** state, map **`part.input.questions`** to **`items`**, and wire **`onSubmit`** to **`addToolOutput`**. Use **`sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithToolCalls`** (or your own predicate) so the model continues after answers are submitted.
```tsx title="app/clarification-chat/page.tsx"
"use client";
import { useChat } from "@ai-sdk/react";
import {
DefaultChatTransport,
lastAssistantMessageIsCompleteWithToolCalls,
type UIMessage,
} from "ai";
import {
Question,
QuestionOption,
QuestionOptions,
QuestionOther,
Questions,
QuestionsCarousel,
QuestionsCarouselContent,
QuestionsCarouselIndex,
QuestionsCarouselItem,
QuestionsCarouselNext,
QuestionsCarouselPagination,
QuestionsCarouselPrev,
QuestionsFooter,
QuestionsHeader,
QuestionsSkip,
QuestionsSubmit,
QuestionsTitle,
type QuestionInput,
type QuestionsSubmission,
} from "@/components/nexus-ui/questions";
type ClarifyingQuestionsInput = {
questions: QuestionInput[];
};
type ClarifyingQuestionsToolPart = {
type: "tool-askClarifyingQuestions";
toolCallId: string;
state: "input-available" | "output-available" | "output-error";
input?: ClarifyingQuestionsInput;
};
function findPendingClarification(messages: UIMessage[]) {
const assistant = [...messages].reverse().find((m) => m.role === "assistant");
if (!assistant) return null;
return assistant.parts.find(
(part): part is ClarifyingQuestionsToolPart =>
part.type === "tool-askClarifyingQuestions" &&
part.state === "input-available" &&
Boolean((part as ClarifyingQuestionsToolPart).input?.questions?.length),
);
}
export default function ClarificationChatPage() {
const { messages, addToolOutput, status } = useChat({
transport: new DefaultChatTransport({ api: "/api/chat" }),
sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithToolCalls,
});
const pending = findPendingClarification(messages);
if (!pending?.input?.questions) return null;
const items = pending.input.questions;
function handleSubmit(submission: QuestionsSubmission) {
void addToolOutput({
tool: "askClarifyingQuestions",
toolCallId: pending.toolCallId,
output: { answers: submission },
});
}
return (
Alternative: send answers as a user message
If you are not using tools, format **`QuestionsSubmission`** and call **`sendMessage`** directly—useful for lightweight clarification UIs that do not participate in the tool loop. ```tsx import type { QuestionsSubmission } from "@/components/nexus-ui/questions"; function formatAnswers(submission: QuestionsSubmission) { return submission .map((entry) => { if (entry.type === "single") { return `- ${entry.prompt}: ${entry.answer.label}`; } const labels = entry.answer.map((item) => item.label).join(", "); return `- ${entry.prompt}: ${labels}`; }) .join("\n"); } // onSubmit={(submission) => sendMessage({ text: formatAnswers(submission) })} ```Install the following dependencies:
Copy and paste the following code into your project.
Update import paths to match your project setup.
Install the AI SDK
```bash npm install ai @ai-sdk/react ```Create your chat API route
This mirrors the docs demo route: use Claude via the AI Gateway id and enable Anthropic thinking so reasoning parts are returned. ```ts title="app/api/chat/route.ts" import { streamText, smoothStream, UIMessage, convertToModelMessages } from "ai"; export async function POST(req: Request) { const { messages, model, }: { messages: UIMessage[]; model?: string } = await req.json(); const result = streamText({ model: "anthropic/claude-sonnet-4.5", messages: await convertToModelMessages(messages), experimental_transform: smoothStream({ chunking: "word", delayInMs: 18, }), providerOptions: { anthropic: { thinking: { type: "enabled", budgetTokens: 1024 }, }, }, }); return result.toUIMessageStreamResponse({ sendReasoning: true, }); } ```
Render assistant reasoning parts with
Reasoning
```tsx
"use client";
import { useChat } from "@ai-sdk/react";
import { DefaultChatTransport, isReasoningUIPart, type UIMessage } from "ai";
import {
Reasoning,
ReasoningContent,
ReasoningTrigger,
} from "@/components/nexus-ui/reasoning";
function reasoningPartsFromMessage(message: UIMessage) {
return message.parts.filter(isReasoningUIPart);
}
function reasoningTextFromMessage(message: UIMessage) {
return reasoningPartsFromMessage(message).map((p) => p.text).join("");
}
function reasoningStreamingFromMessage(message: UIMessage) {
const parts = reasoningPartsFromMessage(message);
return parts.some((p) => p.state === "streaming");
}
export default function ReasoningWithUseChat() {
const { messages } = useChat({
transport: new DefaultChatTransport({ api: "/api/chat" }),
});
const assistant = [...messages].reverse().find((m) => m.role === "assistant");
if (!assistant) return null;
const reasoningText = reasoningTextFromMessage(assistant);
const isReasoningStreaming = reasoningStreamingFromMessage(assistant);
if (!reasoningText.trim()) return null;
return (
Install the following dependencies:
Copy and paste the following code into your project.
Update import paths to match your project setup.
Install the AI SDK
```bash npm install ai @ai-sdk/react @ai-sdk/openai ```Create your chat API route
See [Prompt Input docs](/docs/components/prompt-input#vercel-ai-sdk-integration) for the route implementation.Wire Suggestions + Prompt Input to `useChat`
```tsx "use client"; import { useState } from "react"; import { useChat } from "@ai-sdk/react"; import { DefaultChatTransport } from "ai"; import { Button } from "@/components/ui/button"; import { PromptInput, PromptInputActions, PromptInputAction, PromptInputActionGroup, PromptInputTextarea, } from "@/components/nexus-ui/prompt-input"; import { Suggestions, SuggestionList, Suggestion, } from "@/components/nexus-ui/suggestions"; import { ArrowUp02Icon, PlusSignIcon, SquareIcon, } from "@hugeicons/core-free-icons"; import { HugeiconsIcon } from "@hugeicons/react"; export default function ChatWithSuggestions() { const { sendMessage, status } = useChat({ transport: new DefaultChatTransport({ api: "/api/chat" }), }); const [input, setInput] = useState(""); const isLoading = status !== "ready"; const handleSubmit = (e?: React.FormEvent) => { e?.preventDefault(); if (input.trim()) { sendMessage({ text: input }); setInput(""); } }; return (Copy and paste the following code into your project.
Update import paths to match your project setup.
Install the following dependencies:
Copy and paste the following code into your project.
Update import paths to match your project setup.
Install the AI SDK
```bash npm install ai @ai-sdk/react @ai-sdk/openai ```Create your chat API route
Use the same handler as in the Prompt Input docs: **`messages: await convertToModelMessages(messages)`** and **`return result.toUIMessageStreamResponse()`**.Map `messages` to Message inside Thread
Use **`isTextUIPart`** from **`ai`** so you only aggregate **`type: "text"`** segments. Skip **`system`** turns unless you surface them deliberately. Assistant messages can also include **reasoning**, **tool**, **source**, and other part types—extend this loop when you need those in the UI. ```tsx "use client"; import { useChat } from "@ai-sdk/react"; import { DefaultChatTransport, isTextUIPart, type UIMessage } from "ai"; import { Message, MessageStack, MessageContent, MessageMarkdown, } from "@/components/nexus-ui/message"; import { Thread, ThreadContent, ThreadScrollToBottom, } from "@/components/nexus-ui/thread"; function textFromMessage(message: UIMessage) { return message.parts.filter(isTextUIPart).map((p) => p.text).join(""); } export default function ChatThread() { const { messages } = useChat({ transport: new DefaultChatTransport({ api: "/api/chat" }), }); return (Install the following dependencies:
Copy the following files into your project.
Ensure your Shiki CSS is loaded.
`CodeblockShiki` expects `.shiki` styles. Import `app/shiki.css` once at your app root (for example in `app/layout.tsx`): ```tsx import "./global.css"; import "./shiki.css"; ```Update import paths to match your project setup.
Install the AI SDK
```bash npm install ai @ai-sdk/react ```Stream messages from your chat API route
```ts title="app/api/chat/route.ts" import { streamText, convertToModelMessages, tool, type UIMessage } from "ai"; import { z } from "zod"; export async function POST(req: Request) { const { messages }: { messages: UIMessage[] } = await req.json(); const result = streamText({ model: "anthropic/claude-sonnet-4.5", messages: await convertToModelMessages(messages), tools: { displayWeather: tool({ description: "Get weather for a city", inputSchema: z.object({ city: z.string(), unit: z.enum(["celsius", "fahrenheit"]), }), execute: async ({ city, unit }) => ({ city, unit, temperature: 22, condition: "sunny", }), }), }, }); return result.toUIMessageStreamResponse(); } ```
Map assistant tool parts into
Tool
```tsx
"use client";
import { useChat } from "@ai-sdk/react";
import { DefaultChatTransport, type UIMessage } from "ai";
import {
Tool,
ToolTrigger,
ToolContent,
ToolInput,
ToolOutput,
type ToolStatus,
} from "@/components/nexus-ui/tool";
type ToolPartLike = {
type: string;
state?: string;
input?: unknown;
output?: unknown;
errorText?: string;
error?: unknown;
};
function mapToolStatus(
part: ToolPartLike,
isAwaitingApproval: boolean,
): ToolStatus | null {
switch (part.state) {
case "input-streaming":
// Streaming-only: arguments are still being generated.
return "pending";
case "input-available":
// App-level mapping: use "ready" while waiting for approval/user action.
return isAwaitingApproval ? "ready" : "running";
case "output-available":
return "completed";
case "output-error":
return "error";
default:
return null;
}
}
function toolNameFromPartType(type: string): string {
return type.startsWith("tool-") ? type.slice(5) : type;
}
export default function ToolCallsFromUseChat() {
const { messages } = useChat({
transport: new DefaultChatTransport({ api: "/api/chat" }),
});
const assistant = [...messages].reverse().find((m) => m.role === "assistant");
if (!assistant) return null;
const toolParts = assistant.parts.filter(
(part): part is ToolPartLike => part.type.startsWith("tool-"),
);
if (toolParts.length === 0) return null;
return (
{toolParts.map((part, index) => {
const status = mapToolStatus(part, false);
if (!status) return null;
return (
);
})}
);
}
```