Search trace

Preview

Install

First time? Get started sets up the registry and theme. Or with shadcn directly: npx shadcn@latest add @candor/search-trace

Brings in: bidi, chat, citation, collapsible, locale, locked, motion, status, step-list, streaming-text, tokens, utils · npm: lucide-react@^1.67.0

Usage

"use client"

import { SearchTrace } from "@/components/candor/search-trace"

export default function Example() {
  return (
    <div className="flex max-w-lg flex-col gap-1">
      {/* Sources show their title and domain as text, never a link; "more" says how many it read beyond those listed. */}
      <SearchTrace
        defaultOpen
        call={{ id: "s1", tool: "web.search", title: "Searched the web", status: "succeeded", duration: "3.1s" }}
        queries={[
          {
            id: "q1",
            query: "card network chargeback time limit 2026",
            sources: [
              { id: "a", title: "Dispute time limits for merchants", address: "https://www.example.com/merchants/disputes" },
              { id: "b", title: "Chargeback reason codes, explained", address: "https://docs.example.org/chargebacks/codes" },
            ],
            more: 4,
          },
          {
            id: "q2",
            query: "refund policy settled orders",
            sources: [{ id: "c", title: "Refunds and returns", origin: "Help centre · Policies", kind: "knowledge" }],
          },
        ]}
      />
      {/* While it runs, nothing is said about a search that has read nothing yet. */}
      <SearchTrace
        call={{ id: "s2", tool: "web.search", title: "Searching the web", status: "running" }}
        queries={[{ id: "q3", query: "carrier delivery exceptions Rotterdam", sources: [] }]}
      />
    </div>
  )
}

<SearchTrace>

Functions

Strings

Motion

Set with --cd-motion-search-trace-<moment>-* in your brand file; the families are in the design reference.

Types

SearchSource

One source the agent read: the page or document's title as the tool reported it, and where it lives, as text.

{ id: string; /** The page's title or the document's name, as the tool reported it. Shown as text. */ title: string; /** * The source's address as the tool reported it. Only its domain is shown ("example.com", without "www."), read by * the browser's own URL parser, so an address that hides its host in a user name shows the real host and an * internationalised one shows its xn-- form. It is never a link. */ address?: string | undefined; /** Where it lives in the app's words, for a source with no web address ("Docs · Refund policy"). Shown when `address` has no domain. */ origin?: string | undefined; /** What kind of source it is, for its icon. Defaults to "web". */ kind?: SourceKind | undefined; }

SearchQuery

One query the agent ran and what it read for it.

{ id: string; /** The query exactly as the agent ran it. Model output: shown as text. */ query: string; /** The sources the agent read for this query, in the order it read them. */ sources: SearchSource[]; /** How many more sources the tool says the agent read for this query than `sources` lists. Left out, nothing is said about more. */ more?: number | undefined; }

Types from other items

The props above take these. Each is defined by another item; import it from the path shown.

ToolCallData from @/lib/candor/chat

{ id: string; /** The tool's name, for people who want it: "metadata.describe". */ tool: string; /** What it did, in plain words: "Read Account's fields". */ title: string; status: RunStatus; /** Shown when expanded. Text only; long values scroll. */ input?: string | undefined; output?: string | undefined; outputLanguage?: PayloadLanguage | undefined; /** e.g. "1.2s". Absent while running; never estimated. */ duration?: string | undefined; /** Required when status is "failed": what went wrong, in a sentence. */ error?: string | undefined; /** * The lines it changed, when it edited files and the tool counted them: shown as "+12 −3". Left out when the tool * doesn't say; never estimated. New in 4.4. */ lines?: { added: number; removed: number; } | undefined; /** * Who let it run, when it needed a go-ahead: a person, or something automatic (a policy, a classifier, a rule). * `note` is why, in the source's words. Left out when it needed none or the source doesn't say. */ approval?: { by: "person" | "automatic"; note?: string | undefined; /** The input as the agent proposed it, when a person edited it before it ran; `input` is then what ran. */ originalInput?: string | undefined; } | undefined; }

SourceKind from @/lib/candor/chat

"document", "web", "query", "code", "data", "workflow", "knowledge", or the app's own; unknown kinds read as "Source".

string

RunStatus from @/lib/candor/status

The status vocabulary every Candor agent component shares. Components take plain data in these shapes rather than an SDK's message objects, so they work with your own LLM drivers, the Vercel AI SDK or anything else; adapters map an SDK's parts onto them.

"idle" // not started | "queued" // accepted, waiting for a worker | "running" // an agent is working on it now | "waiting" // stopped to ask a person (approval, question) | "blocked" // can't start: something it depends on failed or is waiting | "succeeded" | "failed" | "cancelled" | "skipped"

PayloadLanguage from @/lib/candor/chat

The block's language, e.g. "json", "sql", "python", "text". Shown as a label; never executed or highlighted as HTML.

string