agent-elements（Agent 元素）

Agent Elements skill

Project-aware context for building chat and agent UIs with Agent Elements — an open-source shadcn registry at https://agent-elements.21st.dev.

What this skill gives you

When this skill loads, you know:

1. The registry is shadcn-compatible. Every component is installed with npx shadcn@latest add https://agent-elements.21st.dev/r/<component>.json. Files land under components/agent-elements/ (the library's internal components/ prefix is stripped — see Paths below).
2. The API is typed around the Vercel AI SDK. Messages are UIMessage[] from ai, status is ChatStatus. useChat() plugs in directly.
3. The full component catalog with API shapes and composition rules (see sections below).
4. Theming guardrails — the Tailwind tokens Agent Elements depends on.

Detection

Consider this project "Agent Elements-ready" if any of these are true:

• components/agent-elements/ exists on disk
• components.json includes an alias or registry reference to Agent Elements
• package.json dependencies include ai + @tabler/icons-react and the user mentions Agent Elements

If the folder does not exist yet, install on demand with:

npx shadcn@latest add https://agent-elements.21st.dev/r/agent-chat.json

agent-chat transitively pulls every other component it needs via registryDependencies (MessageList, InputBar, tool renderers, shared utils).

Paths (post-install layout)

After shadcn add, files sit under @/components/agent-elements/ with this shape:

components/agent-elements/
  agent-chat.tsx
  message-list.tsx
  input-bar.tsx
  markdown.tsx
  user-message.tsx
  error-message.tsx
  text-shimmer.tsx
  spiral-loader.tsx
  input/
    attachment-button.tsx
    send-button.tsx
    file-attachment.tsx
    suggestions.tsx
    model-picker.tsx
    mode-selector.tsx
  tools/
    bash-tool.tsx
    edit-tool.tsx
    search-tool.tsx
    todo-tool.tsx
    plan-tool.tsx
    tool-group.tsx
    subagent-tool.tsx
    mcp-tool.tsx
    thinking-tool.tsx
    generic-tool.tsx
  question/
    question-tool.tsx
  hooks/use-tool-complete.ts
  utils/cn.ts
  types.ts

Import rule: always import from the exact file, never from a barrel.

// ✅
import { AgentChat } from "@/components/agent-elements/agent-chat";
import { BashTool } from "@/components/agent-elements/tools/bash-tool";

// ❌ — no barrel exists
import { AgentChat } from "@/components/agent-elements";

Component catalog

Chat surface

• AgentChat — the full chat shell. Renders MessageList + InputBar, handles tool invocations via toolRenderers, shows an empty state with optional suggestions. Props: messages, status, onSend, onStop, toolRenderers?, suggestions?, attachments?, classNames?, slots?.
• MessageList — transcript only. Use when you need the input bar somewhere else. Accepts toolRenderers and showCopyToolbar.
• UserMessage / ErrorMessage / Markdown — low-level message pieces. Markdown streams safely (external links get rel="noreferrer" by default).

Input

• InputBar — composer. Props: status, onSend({content}), onStop, value? + onChange? (controlled), attachedImages/attachedFiles with their remove handlers, leftActions/rightActions slots, suggestions?, questionBar?, infoBar?.
• Suggestions — quick-prompt chips for the empty state or inline.
• ModelPicker / ModeSelector — designed to drop into leftActions. Both accept a simple {id, name, version?} / {id, label, icon?, description?} shape. Do not import CLAUDE_MODELS — it was removed; supply your own array.
• SendButton / AttachmentButton / FileAttachment — usable standalone if you're building a custom composer.

Tool cards

All tool cards accept a part prop of type Extract<UIMessage["parts"][number], {type: \tool-}>from the AI SDK. Register them viatoolRenderersonAgentChat/MessageList:

<AgentChat
  toolRenderers={{
    Bash: BashTool,
    Edit: EditTool,
    Write: EditTool,      // Write reuses EditTool
    Search: SearchTool,
    WebSearch: SearchTool,
    TodoWrite: TodoTool,
    PlanWrite: PlanTool,
    Task: SubagentTool,
    Thinking: ThinkingTool,
  }}
/>

Cards available:

• BashTool — command + stdout, collapsible.
• EditTool — diff card. Supports input.old_string/input.new_string or output.structuredPatch, plus an approval footer via input.approval.
• SearchTool — grouped search results. Pass results or use output.results.
• TodoTool — diffed todo list from input.todos vs output.oldTodos.
• PlanTool — plan title + summary with approve/reject footer.
• ToolGroup — collapses consecutive tool calls into one row.
• SubagentTool — sub-agent task with nested tools.
• McpTool — generic MCP tool output; use parseMcpToolType from @/components/agent-elements/tools/tool-registry to get mcpInfo.
• ThinkingTool — collapsible reasoning row.
• GenericTool — fallback for unknown tools.
• QuestionTool — clarifying question with single/multi/text answer kinds.

Streaming states

• TextShimmer — shimmering status label.
• SpiralLoader — Lottie spiral; use for multi-second loading states.

Composition patterns

Full chat with tool rendering (most common)

"use client";

import { AgentChat } from "@/components/agent-elements/agent-chat";
import { BashTool } from "@/components/agent-elements/tools/bash-tool";
import { EditTool } from "@/components/agent-elements/tools/edit-tool";
import { SearchTool } from "@/components/agent-elements/tools/search-tool";
import { useChat } from "@ai-sdk/react";

export default function Chat() {
  const { messages, status, sendMessage, stop } = useChat();
  return (
    <AgentChat
      messages={messages}
      status={status}
      onSend={({ content }) => sendMessage({ text: content })}
      onStop={stop}
      toolRenderers={{
        Bash: BashTool,
        Edit: EditTool,
        Write: EditTool,
        Search: SearchTool,
      }}
    />
  );
}

Composer with mode + model pickers

import { InputBar } from "@/components/agent-elements/input-bar";
import { ModeSelector } from "@/components/agent-elements/input/mode-selector";
import { ModelPicker } from "@/components/agent-elements/input/model-picker";
import { IconBulb, IconCursor } from "@tabler/icons-react";

const modes = [
  { id: "agent", label: "Agent", icon: IconCursor },
  { id: "plan", label: "Plan", icon: IconBulb },
];
const models = [
  { id: "sonnet", name: "Sonnet", version: "4.6" },
  { id: "opus", name: "Opus", version: "4.7" },
];

<InputBar
  status="ready"
  onSend={handleSend}
  onStop={handleStop}
  leftActions={
    <>
      <ModeSelector modes={modes} defaultValue="agent" />
      <ModelPicker models={models} defaultValue="sonnet" />
    </>
  }
/>

Custom tool renderer

toolRenderers values are React components that receive {part, chatStatus}. Return whatever UI you want; reuse GenericTool as a fallback shell.

Theming

Agent Elements reads these Tailwind CSS vars (shadcn-style). Do not remove or rename them in the consumer theme:

• --an-foreground, --an-background, --an-primary-color
• Standard shadcn tokens: --background, --foreground, --border, --muted, --muted-foreground, --accent, --primary, etc.

Customising a component is just editing the installed file. Prefer that over wrapping — the code is yours now.

When NOT to use Agent Elements

• Projects using assistant-ui, ai-elements, copilotkit, or another kit — don't mix.
• Pure chat UIs that never render tool calls or plans — InputBar + your own message rendering may be enough; skip AgentChat.
• React < 19 or Tailwind < v4 — the components depend on both.

Quick answers for common asks

• "Add Agent Elements to this project" → run npx shadcn@latest init if components.json is missing, then npx shadcn@latest add https://agent-elements.21st.dev/r/agent-chat.json.
• "Switch the default SendButton look" → edit components/agent-elements/input/send-button.tsx directly. Tokens live on --an-* CSS vars.
• "Render a custom tool" → map its type in toolRenderers; fall back to GenericTool for unknown tools.
• "Use with useChat" → pass messages and status straight through, translate sendMessage/stop to onSend({content})/onStop.

Registry reference

• Index: https://agent-elements.21st.dev/r/index.json
• Per-component: https://agent-elements.21st.dev/r/<id>.json
• Full docs in one file: https://agent-elements.21st.dev/llms-full.txt