import {
ToolFallbackSample,
ToolFallbackCompletedSample,
ToolFallbackCancelledSample,
ToolFallbackStreamingSample,
} from "@/components/pages/docs/samples/tool-fallback";
import { PreviewCode } from "@/components/pages/docs/preview-code.server";
import { ToolFallbackApprovalSample } from "@/components/pages/docs/samples/tool-fallback/approval";
import { ToolFallbackErrorSample } from "@/components/pages/docs/samples/tool-fallback/failed-with-error";

Getting Started#

Add tool-fallback#

<InstallCommand shadcn={["tool-fallback"]} />

This adds a /components/assistant-ui/tool-fallback.tsx file to your project, which you can adjust as needed.

Use it in your application#

Pass the ToolFallback component to the MessagePrimitive.Parts component

import { ToolFallback } from "@/components/assistant-ui/tool-fallback";

const AssistantMessage = () => {
  return (
    <MessagePrimitive.Root>
      <MessagePrimitive.Parts>
        {({ part }) => {
          if (part.type === "tool-call") return <ToolFallback {...part} />;
          return null;
        }}
      </MessagePrimitive.Parts>
    </MessagePrimitive.Root>
  );
};

Examples#

Streaming Demo#

Interactive demo showing the full tool call lifecycle: running → complete.

Completed With Result#

Shows the arguments and the structured result for the completed call.

Failed With Error State#

Shows a service error above its arguments.

Cancelled State#

The "Cancelled tool" label has a line through it. The arguments are muted after you open the call.

Approval State#

Select Allow or Deny. The resume callback records the choice, removes the buttons, and shows the result. The block opens automatically for requires-action, so you can select a decision without an extra click. A tool call whose approval gate is decided shows no buttons. Edit your project's copy of tool-fallback.tsx to add trust escalation, edit-args, custom labels, or analytics hooks.

<PreviewCode
file="components/pages/docs/samples/tool-fallback/approval"
name="ToolWithApproval"

Composable API#

All sub-components are exported for custom layouts:

import {
  ToolFallback,
  ToolFallbackRoot,
  ToolFallbackTrigger,
  ToolFallbackContent,
  ToolFallbackArgs,
  ToolFallbackResult,
  ToolFallbackError,
  ToolFallbackApproval,
} from "@/components/assistant-ui/tool-fallback";

// Compound component syntax
<ToolFallback.Root>
  <ToolFallback.Trigger toolName="get_weather" status={status} />
  <ToolFallback.Content>
    <ToolFallback.Error status={status} />
    <ToolFallback.Args argsText={argsText} />
    <ToolFallback.Approval
      addResult={addResult}
      resume={resume}
      interrupt={interrupt}
      approval={approval}
      respondToApproval={respondToApproval}
      status={status}
    />
    <ToolFallback.Result result={result} />
  </ToolFallback.Content>
</ToolFallback.Root>

Related Components#

• ToolGroup - Group consecutive tool calls together