Workflow Components

Workflow Components

Components for displaying job queues, tool execution, approval workflows, and reasoning displays.

Table of Contents

• Queue Components
• Tool Components
• Confirmation Components
• Reasoning Components
• Loading Components

Queue Components

Components for displaying task lists, job queues, and progress tracking.

Queue

Main container for queue items and sections.

type QueueProps = ComponentProps<"div">;

Usage:

<Queue>
  <QueueSection>
    {/* Queue items */}
  </QueueSection>
</Queue>

Default Styling:

• Bordered container with rounded corners
• Background with shadow
• Flexbox column layout with gap

QueueSection

Collapsible section for organizing queue items.

type QueueSectionProps = ComponentProps<typeof Collapsible>;

Props:

• defaultOpen?: boolean - Initial open state (default: true)

Usage:

<QueueSection defaultOpen={true}>
  <QueueSectionTrigger>
    <QueueSectionLabel count={5} label="pending tasks" />
  </QueueSectionTrigger>
  <QueueSectionContent>
    <QueueList>
      {/* Queue items */}
    </QueueList>
  </QueueSectionContent>
</QueueSection>

QueueSectionTrigger

Clickable header to toggle section visibility.

type QueueSectionTriggerProps = ComponentProps<"button">;

Default Styling:

• Full width button
• Muted background with hover effect
• Flexbox layout for content alignment

QueueSectionLabel

Label with icon, text, and count display.

type QueueSectionLabelProps = ComponentProps<"span"> & {
  count?: number;
  label: string;
  icon?: React.ReactNode;
};

Props:

• count?: number - Item count to display
• label: string - Section label (required)
• icon?: React.ReactNode - Optional icon

Usage:

<QueueSectionLabel
  count={todos.length}
  label="todos"
  icon={<CheckSquareIcon className="size-4" />}
/>

Display: Shows "{count} {label}" with chevron icon that rotates when expanded.

QueueSectionContent

Collapsible content area for queue items.

type QueueSectionContentProps = ComponentProps<typeof CollapsibleContent>;

QueueList

Scrollable container for queue items.

type QueueListProps = ComponentProps<typeof ScrollArea>;

Default Styling:

• Max height of 40 (10rem)
• Scrollable when content overflows
• Padding for scroll area

Usage:

<QueueList>
  {items.map(item => (
    <QueueItem key={item.id}>
      {/* Item content */}
    </QueueItem>
  ))}
</QueueList>

QueueItem

Individual queue item container.

type QueueItemProps = ComponentProps<"li">;

Usage:

<QueueItem>
  <QueueItemIndicator completed={todo.status === 'completed'} />
  <QueueItemContent completed={todo.status === 'completed'}>
    {todo.title}
  </QueueItemContent>
  {todo.description && (
    <QueueItemDescription completed={todo.status === 'completed'}>
      {todo.description}
    </QueueItemDescription>
  )}
  <QueueItemActions>
    <QueueItemAction
      <EditIcon />
    </QueueItemAction>
  </QueueItemActions>
</QueueItem>

Default Styling:

• Flexbox column layout
• Hover background effect
• Grouped item styling

QueueItemIndicator

Status indicator dot.

type QueueItemIndicatorProps = ComponentProps<"span"> & {
  completed?: boolean;
};

Props:

• completed?: boolean - Whether item is completed (default: false)

Styling:

• Pending: Solid border
• Completed: Muted border and background

QueueItemContent

Main content text for queue item.

type QueueItemContentProps = ComponentProps<"span"> & {
  completed?: boolean;
};

Props:

• completed?: boolean - Whether item is completed (default: false)

Styling:

• Pending: Normal text
• Completed: Muted text with line-through

QueueItemDescription

Secondary description text.

type QueueItemDescriptionProps = ComponentProps<"div"> & {
  completed?: boolean;
};

Props:

• completed?: boolean - Whether item is completed (default: false)

Styling:

• Smaller text size
• Indented under main content
• Muted color (more muted if completed)

QueueItemActions

Container for action buttons.

type QueueItemActionsProps = ComponentProps<"div">;

Usage:

<QueueItemActions>
  <QueueItemAction
    <EditIcon />
  </QueueItemAction>
  <QueueItemAction
    <TrashIcon />
  </QueueItemAction>
</QueueItemActions>

QueueItemAction

Individual action button.

type QueueItemActionProps = Omit<ComponentProps<typeof Button>, "variant" | "size">;

Behavior:

• Hidden by default
• Visible on item hover
• Ghost variant
• Icon size

QueueItemAttachment

Container for attached files/images.

type QueueItemAttachmentProps = ComponentProps<"div">;

QueueItemImage

Image preview thumbnail.

type QueueItemImageProps = ComponentProps<"img">;

Default Size: 32x32px

QueueItemFile

File attachment display with icon.

type QueueItemFileProps = ComponentProps<"span">;

Features:

• Paperclip icon
• Truncated filename (max 100px)
• Border and background styling

Tool Components

Components for displaying tool execution with states, parameters, and results.

Tool

Main container for tool execution display.

type ToolProps = ComponentProps<typeof Collapsible>;

Usage:

<Tool>
  <ToolHeader
    title="search"
    type="tool-call-search"
    state="output-available"
  />
  <ToolContent>
    <ToolInput input={{ query: "AI tools" }} />
    <ToolOutput output={results} errorText={undefined} />
  </ToolContent>
</Tool>

Default Styling:

• Bordered container
• Rounded corners
• Not prose (for content formatting)

ToolHeader

Collapsible trigger showing tool name and status.

type ToolHeaderProps = {
  title?: string;
  type: ToolUIPart["type"];
  state: ToolUIPart["state"];
  className?: string;
};

Props:

• title?: string - Display name (defaults to type without "tool-call-" prefix)
• type: string - Tool type identifier
• state: ToolState - Current execution state (required)

Tool States:

• input-streaming - Parameters being received (Pending badge)
• input-available - Ready to execute (Running badge, pulsing)
• approval-requested - Awaiting approval (Awaiting Approval badge, yellow)
• approval-responded - User responded (Responded badge, blue)
• output-available - Completed (Completed badge, green)
• output-error - Failed (Error badge, red)
• output-denied - Approval denied (Denied badge, orange)

Features:

• Wrench icon
• Color-coded status badge
• Chevron that rotates when expanded

ToolContent

Collapsible content area for parameters and results.

type ToolContentProps = ComponentProps<typeof CollapsibleContent>;

Animation:

• Slide in/out from top
• Fade transition

ToolInput

Displays tool parameters/arguments.

type ToolInputProps = ComponentProps<"div"> & {
  input: ToolUIPart["input"];
};

Props:

• input: unknown - Tool parameters (any JSON-serializable value)

Usage:

<ToolInput
  input={{
    query: "AI tools",
    limit: 10,
    filters: ["type:library"]
  }}
/>

Features:

• "PARAMETERS" heading
• JSON syntax highlighting via CodeBlock
• Automatic JSON.stringify with formatting

ToolOutput

Displays tool results or errors.

type ToolOutputProps = ComponentProps<"div"> & {
  output: ToolUIPart["output"];
  errorText: ToolUIPart["errorText"];
};

Props:

• output: unknown - Tool result (any value, React element, or JSON)
• errorText?: string - Error message if execution failed

Usage:

<ToolOutput
  output={{
    results: [...],
    count: 42
  }}
  errorText={undefined}
/>

Behavior:

• Shows "RESULT" heading for success
• Shows "ERROR" heading for errors
• Renders React elements directly
• JSON stringifies objects
• CodeBlock for strings
• Destructive styling for errors

Confirmation Components

Components for approval workflows requiring user confirmation.

Confirmation

Container for confirmation UI with conditional rendering based on state.

type ConfirmationProps = ComponentProps<typeof Alert> & {
  approval?: ToolUIPartApproval;
  state: ToolUIPart["state"];
};

type ToolUIPartApproval =
  | { id: string; approved?: never; reason?: never }
  | { id: string; approved: boolean; reason?: string }
  | undefined;

Props:

• approval?: ToolUIPartApproval - Approval data
• state: ToolState - Current state

Usage:

<Confirmation approval={tool.approval} state={tool.state}>
  <ConfirmationTitle>
    Delete {count} files?
  </ConfirmationTitle>

  <ConfirmationRequest>
    <ConfirmationActions>
      <ConfirmationAction variant="default">
        Approve
      </ConfirmationAction>
      <ConfirmationAction variant="outline">
        Reject
      </ConfirmationAction>
    </ConfirmationActions>
  </ConfirmationRequest>

  <ConfirmationAccepted>
    Action approved and executed.
  </ConfirmationAccepted>

  <ConfirmationRejected>
    Action rejected.
  </ConfirmationRejected>
</Confirmation>

Context: Provides { approval, state } to child components.

ConfirmationTitle

Title/description of the confirmation request.

type ConfirmationTitleProps = ComponentProps<typeof AlertDescription>;

ConfirmationRequest

Container shown during approval-requested state.

type ConfirmationRequestProps = { children?: ReactNode };

Visibility: Only shown when state === "approval-requested"

ConfirmationActions

Container for approve/reject buttons.

type ConfirmationActionsProps = ComponentProps<"div">;

Visibility: Only shown when state === "approval-requested"

ConfirmationAction

Individual action button.

type ConfirmationActionProps = ComponentProps<typeof Button>;

Default Styling:

• Small height (h-8)
• Compact padding

ConfirmationAccepted

Content shown when approval is accepted.

type ConfirmationAcceptedProps = { children?: ReactNode };

Visibility: Only shown when approval.approved === true and state is response/output state.

ConfirmationRejected

Content shown when approval is rejected.

type ConfirmationRejectedProps = { children?: ReactNode };

Visibility: Only shown when approval.approved === false and state is response/output state.

useConfirmation

Hook to access confirmation context.

const useConfirmation = () => {
  const { approval, state } = useConfirmation();
  // ...
};

Reasoning Components

Components for displaying AI thinking/reasoning with auto-collapse behavior.

Reasoning

Collapsible container for reasoning content with auto-collapse.

type ReasoningProps = ComponentProps<typeof Collapsible> & {
  isStreaming?: boolean;
  open?: boolean;
  defaultOpen?: boolean;
  onOpenChange?: (open: boolean) => void;
  duration?: number;
};

Props:

• isStreaming?: boolean - Whether content is actively streaming (default: false)
• open?: boolean - Controlled open state
• defaultOpen?: boolean - Initial open state (default: true)
• onOpenChange?: (open: boolean) => void - Callback when open state changes
• duration?: number - Thinking duration in seconds

Usage:

<Reasoning isStreaming={isStreaming} defaultOpen={true}>
  <ReasoningTrigger />
  <ReasoningContent>
    {reasoningText}
  </ReasoningContent>
</Reasoning>

Auto-Collapse Behavior:

1. Opens automatically when streaming starts
2. Tracks duration from start to end of streaming
3. Closes 1 second after streaming ends
4. Auto-close only happens once per component lifecycle

Context: Provides { isStreaming, isOpen, setIsOpen, duration } to children.

ReasoningTrigger

Trigger button with status message and icon.

type ReasoningTriggerProps = ComponentProps<typeof CollapsibleTrigger> & {
  getThinkingMessage?: (isStreaming: boolean, duration?: number) => ReactNode;
};

Props:

• getThinkingMessage?: (isStreaming, duration) => ReactNode - Custom message generator

Default Messages:

• Streaming: "Thinking..." with shimmer effect
• Duration 0 or undefined: "Thought for a few seconds"
• Duration N: "Thought for N seconds"

Usage:

<ReasoningTrigger />

// Custom message
<ReasoningTrigger
  getThinkingMessage={(streaming, duration) =>
    streaming ? <Shimmer>Processing...</Shimmer> : `Done in ${duration}s`
  }
/>

Icons:

• Brain icon
• Rotating chevron (down when closed, up when open)

ReasoningContent

Collapsible content area with markdown rendering.

type ReasoningContentProps = ComponentProps<typeof CollapsibleContent> & {
  children: string;
};

Props:

• children: string - Reasoning text (required, string only)

Features:

• Uses Streamdown for markdown rendering
• Slide and fade animations
• Muted text color

useReasoning

Hook to access reasoning context.

const useReasoning = () => {
  const { isStreaming, isOpen, setIsOpen, duration } = useReasoning();
  // ...
};

Loading Components

Shimmer

Animated shimmer effect for loading text.

type TextShimmerProps = {
  children: string;
  as?: ElementType;
  className?: string;
  duration?: number;
  spread?: number;
};

Props:

• children: string - Text to shimmer (required)
• as?: ElementType - HTML element type (default: "p")
• className?: string - Additional classes
• duration?: number - Animation duration in seconds (default: 2)
• spread?: number - Shimmer spread multiplier (default: 2)

Usage:

<Shimmer duration={1.5}>Thinking...</Shimmer>
<Shimmer as="span" spread={3}>Loading data...</Shimmer>

Features:

• Framer Motion animation
• Gradient sweep effect
• Dynamic spread based on text length
• Infinite loop

Loader

Spinning loader icon.

type LoaderProps = HTMLAttributes<HTMLDivElement> & {
  size?: number;
};

Props:

• size?: number - Icon size in pixels (default: 16)

Usage:

<Loader size={24} />
<Loader className="text-primary" />

Features:

• SVG-based spinner
• CSS animation (spin)
• Respects current color

Complete Example

import {
  Queue,
  QueueSection,
  QueueSectionTrigger,
  QueueSectionLabel,
  QueueSectionContent,
  QueueList,
  QueueItem,
  QueueItemIndicator,
  QueueItemContent,
  QueueItemDescription,
} from "@/components/ai-elements/queue";
import {
  Tool,
  ToolHeader,
  ToolContent,
  ToolInput,
  ToolOutput,
} from "@/components/ai-elements/tool";
import {
  Confirmation,
  ConfirmationTitle,
  ConfirmationRequest,
  ConfirmationActions,
  ConfirmationAction,
  ConfirmationAccepted,
  ConfirmationRejected,
} from "@/components/ai-elements/confirmation";
import {
  Reasoning,
  ReasoningTrigger,
  ReasoningContent,
} from "@/components/ai-elements/reasoning";

function WorkflowDisplay({ todos, tools, reasoning }) {
  return (
    <div className="space-y-4">
      {/* Queue */}
      <Queue>
        <QueueSection>
          <QueueSectionTrigger>
            <QueueSectionLabel count={todos.length} label="tasks" />
          </QueueSectionTrigger>
          <QueueSectionContent>
            <QueueList>
              {todos.map(todo => (
                <QueueItem key={todo.id}>
                  <QueueItemIndicator completed={todo.completed} />
                  <QueueItemContent completed={todo.completed}>
                    {todo.title}
                  </QueueItemContent>
                  {todo.description && (
                    <QueueItemDescription completed={todo.completed}>
                      {todo.description}
                    </QueueItemDescription>
                  )}
                </QueueItem>
              ))}
            </QueueList>
          </QueueSectionContent>
        </QueueSection>
      </Queue>

      {/* Reasoning */}
      {reasoning && (
        <Reasoning isStreaming={reasoning.isStreaming}>
          <ReasoningTrigger />
          <ReasoningContent>{reasoning.content}</ReasoningContent>
        </Reasoning>
      )}

      {/* Tools */}
      {tools.map(tool => (
        <div key={tool.id}>
          <Tool>
            <ToolHeader
              title={tool.name}
              type={tool.type}
              state={tool.state}
            />
            <ToolContent>
              <ToolInput input={tool.args} />
              <ToolOutput output={tool.result} errorText={tool.error} />
            </ToolContent>
          </Tool>

          {tool.requiresApproval && (
            <Confirmation approval={tool.approval} state={tool.state}>
              <ConfirmationTitle>
                Approve {tool.name}?
              </ConfirmationTitle>

              <ConfirmationRequest>
                <ConfirmationActions>
                  <ConfirmationAction
                    => approveTool(tool.id)}
                    variant="default"
                  >
                    Approve
                  </ConfirmationAction>
                  <ConfirmationAction
                    => rejectTool(tool.id)}
                    variant="outline"
                  >
                    Reject
                  </ConfirmationAction>
                </ConfirmationActions>
              </ConfirmationRequest>

              <ConfirmationAccepted>
                Tool approved and executed.
              </ConfirmationAccepted>

              <ConfirmationRejected>
                Tool execution rejected.
              </ConfirmationRejected>
            </Confirmation>
          )}
        </div>
      ))}
    </div>
  );
}