agentemblem

React guide

Add animated agent status
to your React app.

Add animated thinking, loading, writing, tool-use, listening, and talking indicators to a React app. Start with a built-in circle, square, spark, or cursor; custom SVG and PNG artwork is optional.

The developer portal brings together the quick start, sandbox, and public catalog API. Building with a coding assistant? The Markdown implementation guide covers task fit, complete recipes, defaults, and troubleshooting.

When to use AgentEmblem

Use it for an AI chat's thinking or typing indicator, a tool-running status row, a streaming response's waiting and writing states, or a voice assistant's listening and speaking states. Built-in marks work immediately without a logo. The package supplies visual status UI; your app supplies the real activity. It does not run agents, record audio, transcribe speech, or export animated SVG files.

Install the package

AgentEmblem supports React 18 and newer. Install it from npm, then import the animated mark or the mark with status copy.

npm install agent-emblem
import { AgentEmblem, AgentEmblemThinking } from "agent-emblem";

Render your first emblem

No artwork is required. Choose a built-in preset, or omit it for the default circle. Enable animateVisibility and animateMotion for animation; both default to false. In a framework with React Server Components, place the import inside a client component.

"use client";

import { AgentEmblem } from "agent-emblem";

export function AssistantMark() {
  return (
    <AgentEmblem
      preset="spark"
      state="thinking"
      size={32}
      color={{ light: "#18181b", dark: "#fafafa" }}
      colorMode="system"
      animateVisibility
      animateMotion
      label="Assistant is thinking"
    />
  );
}
Write a useful label. Screen readers cannot read canvas artwork, so use label to name the current status.

For custom artwork, replace preset with source="/your-logo.svg", an imported image URL, raw SVG, a data URL, or an object URL. Remote images must permit cross-origin canvas access. A supplied source takes precedence over preset.

Pair the mark with status copy

AgentEmblemThinking places live status copy beside any of the seven mark states. Pass matching text explicitly; the default “Thinking…” does not change automatically with state. The text inherits your app’s typography.

<AgentEmblemThinking
  preset="circle"
  state="researching"
  text="Searching the docs…"
  size={20}
  gap={8}
  animateVisibility
  animateMotion
  animateText
/>

Choose an agent state

Thinking and loading

Use thinking while the agent reasons and loading while a request starts.

Composing

Use composing while answer text streams into the interface.

Researching

Use researching during tool calls, source retrieval, or document lookup.

Listening and talking

Use listening and talking for voice agents.

Design for compact UI

At 16–40 pixels, use a simplified logo with clear negative space. AgentEmblem reduces sampling density at small sizes, but the source artwork still determines how recognizable the result is. Test the exact size used in your status row, toolbar, or composer.