| title | Tool |
|---|---|
| description | A collapsible component for displaying tool invocation details in AI chatbot interfaces. |
| path | elements/components/tool |
The Tool component displays a collapsible interface for showing/hiding tool details. It is designed to take the ToolUIPart type from the AI SDK and display it in a collapsible interface.
Build a simple stateful weather app that renders the last message in a tool using useChat.
Add the following component to your frontend:
"use client";
import { useChat } from "@ai-sdk/react";
import { DefaultChatTransport, type ToolUIPart } from "ai";
import { Button } from "@/components/ui/button";
import { MessageResponse } from "@/components/ai-elements/message";
import {
Tool,
ToolContent,
ToolHeader,
ToolInput,
ToolOutput,
} from "@/components/ai-elements/tool";
type WeatherToolInput = {
location: string;
units: "celsius" | "fahrenheit";
};
type WeatherToolOutput = {
location: string;
temperature: string;
conditions: string;
humidity: string;
windSpeed: string;
lastUpdated: string;
};
type WeatherToolUIPart = ToolUIPart<{
fetch_weather_data: {
input: WeatherToolInput;
output: WeatherToolOutput;
};
}>;
const Example = () => {
const { messages, sendMessage, status } = useChat({
transport: new DefaultChatTransport({
api: "/api/weather",
}),
});
const handleWeatherClick = () => {
sendMessage({ text: "Get weather data for San Francisco in fahrenheit" });
};
const latestMessage = messages[messages.length - 1];
const weatherTool = latestMessage?.parts?.find(
(part) => part.type === "tool-fetch_weather_data"
) as WeatherToolUIPart | undefined;
return (
<div className="max-w-4xl mx-auto p-6 relative size-full rounded-lg border h-[600px]">
<div className="flex flex-col h-full">
<div className="space-y-4">
<Button onClick={handleWeatherClick} disabled={status !== "ready"}>
Get Weather for San Francisco
</Button>
{weatherTool && (
<Tool defaultOpen={true}>
<ToolHeader
type="tool-fetch_weather_data"
state={weatherTool.state}
/>
<ToolContent>
<ToolInput input={weatherTool.input} />
<ToolOutput
output={
<MessageResponse>
{formatWeatherResult(weatherTool.output)}
</MessageResponse>
}
errorText={weatherTool.errorText}
/>
</ToolContent>
</Tool>
)}
</div>
</div>
</div>
);
};
function formatWeatherResult(result: WeatherToolOutput): string {
return `**Weather for ${result.location}**
**Temperature:** ${result.temperature}
**Conditions:** ${result.conditions}
**Humidity:** ${result.humidity}
**Wind Speed:** ${result.windSpeed}
*Last updated: ${result.lastUpdated}*`;
}
export default Example;Add the following route to your backend:
import { streamText, UIMessage, convertToModelMessages } from "ai";
import { z } from "zod";
// Allow streaming responses up to 30 seconds
export const maxDuration = 30;
export async function POST(req: Request) {
const { messages }: { messages: UIMessage[] } = await req.json();
const result = streamText({
model: "openai/gpt-4o",
messages: await convertToModelMessages(messages),
tools: {
fetch_weather_data: {
description: "Fetch weather information for a specific location",
parameters: z.object({
location: z
.string()
.describe("The city or location to get weather for"),
units: z
.enum(["celsius", "fahrenheit"])
.default("celsius")
.describe("Temperature units"),
}),
inputSchema: z.object({
location: z.string(),
units: z.enum(["celsius", "fahrenheit"]).default("celsius"),
}),
execute: async ({ location, units }) => {
await new Promise((resolve) => setTimeout(resolve, 1500));
const temp =
units === "celsius"
? Math.floor(Math.random() * 35) + 5
: Math.floor(Math.random() * 63) + 41;
return {
location,
temperature: `${temp}°${units === "celsius" ? "C" : "F"}`,
conditions: "Sunny",
humidity: `12%`,
windSpeed: `35 ${units === "celsius" ? "km/h" : "mph"}`,
lastUpdated: new Date().toLocaleString(),
};
},
},
},
});
return result.toUIMessageStreamResponse();
}- Collapsible interface for showing/hiding tool details
- Customizable tool icons, with support for mapping icons by tool name
- Visual status indicators with icons and badges
- Support for multiple tool execution states (pending, running, completed, error)
- Formatted parameter display with JSON syntax highlighting
- Result and error handling with appropriate styling
- Composable structure for flexible layouts
- Accessible keyboard navigation and screen reader support
- Consistent styling that matches your design system
- Auto-opens completed tools by default for better UX
Shows a tool in its initial state while parameters are being processed.
Shows a tool that's actively executing with its parameters.
Shows a completed tool with successful results. Opens by default to show the results. In this instance, the output is a JSON object, so we can use the CodeBlock component to display it.
Shows a tool that encountered an error during execution. Opens by default to display the error.
Pass a function to the icon prop to render a custom icon. The function receives an object with:
type: the tool part typestate: the current execution statetoolName: the derived tool nameclassName: default sizing and color styles
Use toolName to map different icons by tool type. When the function returns null, the default wrench icon is used.
<TypeTable type={{ "...props": { description: "Any other props are spread to the root Collapsible component.", type: "React.ComponentProps", }, }} />
<TypeTable type={{ icon: { description: "Custom icon for the tool header. Pass a ReactNode for a static icon, or a function that receives a ToolIconProps object and returns a ReactNode.", type: "ReactNode | ((props: ToolIconProps) => ReactNode)", }, title: { description: "Custom title to display instead of the derived tool name.", type: "string", }, type: { description: "The type/name of the tool.", type: 'ToolUIPart["type"] | DynamicToolUIPart["type"]', required: true, }, state: { description: "The current state of the tool (input-streaming, input-available, output-available, or output-error).", type: 'ToolUIPart["state"] | DynamicToolUIPart["state"]', required: true, }, toolName: { description: 'Required when type is "dynamic-tool" to specify the tool name.', type: "string", }, className: { description: "Additional CSS classes to apply to the header.", type: "string", }, "...props": { description: "Any other props are spread to the CollapsibleTrigger.", type: "React.ComponentProps", }, }} />
<TypeTable type={{ "...props": { description: "Any other props are spread to the CollapsibleContent.", type: "React.ComponentProps", }, }} />
<TypeTable type={{ input: { description: "The input parameters passed to the tool, displayed as formatted JSON.", type: 'ToolUIPart["input"]', }, "...props": { description: "Any other props are spread to the underlying div.", type: 'React.ComponentProps<"div">', }, }} />
<TypeTable type={{ output: { description: "The output/result of the tool execution.", type: "React.ReactNode", }, errorText: { description: "An error message if the tool execution failed.", type: 'ToolUIPart["errorText"]', }, "...props": { description: "Any other props are spread to the underlying div.", type: 'React.ComponentProps<"div">', }, }} />
Union type representing both static and dynamic tool UI parts.
type ToolPart = ToolUIPart | DynamicToolUIPart;Returns a Badge component with icon and label based on tool state.
import { getStatusBadge } from "@/components/ai-elements/tool";
// Returns a Badge with appropriate icon and label
const badge = getStatusBadge("output-available");Supported states:
input-streaming- "Pending"input-available- "Running"approval-requested- "Awaiting Approval"approval-responded- "Responded"output-available- "Completed"output-error- "Error"output-denied- "Denied"