---
title: "Trace"
description: "Follow reasoning, tool results and sources with compact, expandable activity traces."
---

# Trace

Follow reasoning, tool results and sources with compact, expandable activity traces.

## Installation

Install the shared package once in your Exact app. This version is a beta.

```sh
bun add --exact @rightui/ui@0.4.0-beta.4
```

Or choose another package manager:

```sh
npm install --save-exact @rightui/ui@0.4.0-beta.4
pnpm add --save-exact @rightui/ui@0.4.0-beta.4
yarn add --exact @rightui/ui@0.4.0-beta.4
```

Exact compilation uses Bun 1.4.2. Register Geist and Newsreader, declare the font marker and add the root provider using [Installation](/docs/installation).

### Manual source setup

Install an editable copy of the complete package:

```sh
mkdir -p vendor/rightui vendor/rightui-ui
npm pack @rightui/ui@0.4.0-beta.4 --pack-destination vendor/rightui
tar -xzf ./vendor/rightui/rightui-ui-0.4.0-beta.4.tgz -C vendor/rightui-ui --strip-components=1
bun add file:./vendor/rightui-ui
```

Keep package.json, the Contract files, ui.tamber, assets and licenses together.

### Import

```contract
use Trace, TraceFrame, TraceLine, TraceTitle, TraceDescription, TraceDisclosure, TraceCollapsible, TraceSource, TraceIcon from "@rightui/ui"
```

## Usage

Use Trace for a simple list of steps. Compose TraceFrame, TraceLine, TraceDisclosure and TraceSource for rich activity with controlled disclosure, per-step icons and running, pending or error states. Pass the reduced-motion preference to the composable primitives. The preview uses a local scripted clock: Replay demonstrates the UI and does not execute commands or contact an AI service. Its source includes the injected clock used by the demo.

## Example

```contract
use uiFontFamily, ButtonAI, BubbleFrame, TraceFrame, TraceLine, TraceDisclosure, TraceSource, CodeBlockContent from "@rightui/ui"

component Demo
  props
    width: number
    reduced: bool
  inject
    uiFont: string
    rightuiDemoTime: number
    rightuiRunDemo: action
  state started = -1
  state thinkingChoice: option<bool> = none
  state statusOpen = false
  state diffOpen = true
  state errorOpen = false
  state sourcesOpen = false
  derive elapsed = started < 0 ? 9000 : max(0, rightuiDemoTime - started)
  derive thinking = elapsed < 2000
  derive busy = elapsed < 8500
  derive thinkingOpen = match thinkingChoice { case some(value) => value, case none => thinking }
  derive reasoning = "The CI job installs dependencies with a frozen lockfile. I will compare the dependency changes with the committed lockfile, then check the install output."
  derive answer = "package.json changed, but pnpm-lock.yaml did not. Run pnpm install locally and commit the updated lockfile so CI can install the same dependency versions."
  action replay
    started = rightuiDemoTime
    thinkingChoice = none
    statusOpen = false
    diffOpen = true
    errorOpen = false
    sourcesOpen = false
    rightuiRunDemo(8600)
  action toggleThinking
    thinkingChoice = some(not thinkingOpen)
  action toggleStatus
    statusOpen = not statusOpen
  action toggleDiff
    diffOpen = not diffOpen
  action toggleError
    errorOpen = not errorOpen
  action toggleSources
    sourcesOpen = not sourcesOpen
  view
    column id="content-trace" testId="content-trace" aria-busy=busy gap="ui.space-16" min-width=0 max-width="24rem" width="100%" min-height=288 padding="ui.space-24 ui.space-0" font-size="ui.text-sm" line-height="ui.leading-normal"
      BubbleFrame(id="content-trace-question", align="end", variant="muted")
        text "Why does this install fail in CI?" font-family=uiFontFamily(uiFont) data-rightui-font="body"
      column testId=(thinking ? "content-trace-thinking" : busy ? "content-trace-working" : "content-trace-complete") min-width=0
        TraceFrame()
          TraceDisclosure(id="content-trace-step-0", title=(thinking ? "Thinking" : "Thought for 2s"), icon="check", status=(thinking ? "running" : ""), open=thinkingOpen, reduced=reduced, toggle=toggleThinking)
            if thinkingOpen
              text (thinking and not reduced ? reasoning.slice(0, floor(elapsed / 2000 * reasoning.length)) : reasoning) id="content-trace-detail-0" testId="content-trace-detail-0" line-height="ui.leading-relaxed" font-family=uiFontFamily(uiFont) data-rightui-font="body"
          if elapsed >= 2000
            if elapsed < 2800
              TraceLine(title="Running git status --short", icon="check", status="running", reduced=reduced)
            else
              TraceDisclosure(id="content-trace-step-1", title="Ran git status --short", icon="check", status="", open=statusOpen, reduced=reduced, toggle=toggleStatus)
                CodeBlockContent(id="content-trace-status-output", code=" M package.json")
          if elapsed >= 2800
            if elapsed < 3800
              TraceLine(title="Running git diff --stat", icon="check", status="running", reduced=reduced)
            else
              TraceDisclosure(id="content-trace-step-2", title="Ran git diff --stat -- package.json pnpm-lock.yaml", icon="check", status="", open=diffOpen, reduced=reduced, toggle=toggleDiff)
                CodeBlockContent(id="content-trace-diff-output", code=" package.json | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)")
          if elapsed >= 3800
            if elapsed < 5000
              TraceLine(title="Running pnpm install --frozen-lockfile", icon="check", status="running", reduced=reduced)
            else
              TraceDisclosure(id="content-trace-step-3", title="Failed to run pnpm install --frozen-lockfile", icon="check", status="error", open=errorOpen, reduced=reduced, toggle=toggleError)
                column min-width=0 padding="ui.space-12" border-radius="ui.ai-radius-control" background-color="ui.code-destructive-background" border-width="ui.border-width" border-style="solid" border-color="ui.border"
                  text "ERR_PNPM_OUTDATED_LOCKFILE" testId="content-trace-error-code" color="ui.danger" font-family="ui.font-code" font-size="ui.text-xs" line-height="ui.leading-relaxed" overflow-wrap="anywhere"
                  text "Cannot install with frozen-lockfile because pnpm-lock.yaml is not up to date with package.json." testId="content-trace-error-output" color="ui.danger" font-family="ui.font-code" font-size="ui.text-xs" line-height="ui.leading-relaxed" overflow-wrap="anywhere"
          if elapsed >= 5000
            TraceDisclosure(id="content-trace-sources", title="Used 2 sources", icon="globe", status="", open=sourcesOpen, reduced=reduced, toggle=toggleSources)
              TraceFrame()
                TraceSource(title="pnpm install", href="https://pnpm.io/cli/install#--frozen-lockfile", reduced=reduced)
                TraceSource(title="Continuous Integration", href="https://pnpm.io/continuous-integration", reduced=reduced)
      if elapsed >= 5500
        text (started < 0 or reduced ? answer : answer.slice(0, floor((elapsed - 5500) / 3000 * answer.length))) testId="content-trace-answer" line-height="ui.leading-normal" font-family=uiFontFamily(uiFont) data-rightui-font="body"
      if not busy
        row margin-top="auto"
          ButtonAI(id="content-trace-replay", label="Replay", variant="outline", size="sm", disabled=false, press=replay)
            text "Replay" font-family=uiFontFamily(uiFont) data-rightui-font="body"

```

## Keyboard

Tab moves between disclosures, source links and Replay. Enter or Space toggles the focused disclosure. Closed content is hidden from keyboard navigation.

## API Reference

| Property | Type |
| --- | --- |
| TraceIcon.icon | string |
| TraceIcon.status | string |
| TraceIcon.reduced | bool |
| TraceTitle.title | string |
| TraceTitle.running | bool |
| TraceTitle.reduced | bool |
| TraceLine.title | string |
| TraceLine.icon | string |
| TraceLine.status | string |
| TraceLine.reduced | bool |
| TraceDescription.description | string |
| TraceDisclosure.id | string |
| TraceDisclosure.title | string |
| TraceDisclosure.icon | string |
| TraceDisclosure.status | string |
| TraceDisclosure.open | bool |
| TraceDisclosure.reduced | bool |
| TraceDisclosure.toggle | action |
| TraceCollapsible.id | string |
| TraceCollapsible.title | string |
| TraceCollapsible.icon | string |
| TraceCollapsible.status | string |
| TraceCollapsible.initiallyOpen | bool |
| TraceCollapsible.reduced | bool |
| TraceSource.title | string |
| TraceSource.href | string |
| TraceSource.reduced | bool |
| Trace.id | string |
| Trace.title | string |
| Trace.status | string |
| Trace.steps | string[] |
| Trace.details | string[] |

## Source

File: packages/ui/trace.contract

```contract
use FontWeights from "./typography-context.contract"
use uiFontFamily from "./typography-context.contract"
use TraceIcon, TraceDisclosure from "./trace-parts.contract"

component Trace
  props
    id: string
    title: string
    status: string
    steps: string[]
    details: string[]
  inject
    uiWeights: FontWeights
    uiFont: string
  state expanded = -1
  derive normalizedStatus = ["error", "failed", "erreur"].includes(status.toLowerCase()) ? "error" : ["running", "loading"].includes(status.toLowerCase()) ? "running" : status.toLowerCase() == "pending" ? "pending" : ""
  action toggle(i: number)
    expanded = expanded == i ? -1 : i
  view
    column id=id testId=id gap="ui.space-12" min-width="0px"
      row gap="ui.space-8" align-items="center" flex-wrap="wrap" color=(normalizedStatus == "error" ? "ui.danger" : "ui.muted-foreground")
        text title flex="1 1 10rem" min-width="0px" font-size="ui.text-sm" font-weight=uiWeights.medium color="ui.foreground" font-family=uiFontFamily(uiFont) data-rightui-font="body"
        row gap="ui.space-6" align-items="center"
          TraceIcon(icon="check", status=normalizedStatus, reduced=true)
          text status testId=(id + "-status") role="status" font-size="ui.text-xs" line-height="ui.leading-normal" font-family=uiFontFamily(uiFont) data-rightui-font="body"
      column gap="ui.space-8" min-width="0px"
        for step, i in steps key=step
          TraceDisclosure(id=id + "-step-" + i.toString(), title=step, icon="none", status="", open=(expanded == i), reduced=true, toggle=toggle(i))
            if expanded == i
              match details.at(i)
                case some(detail)
                  text detail id=(id + "-detail-" + i.toString()) testId=(id + "-detail-" + i.toString()) font-size="ui.text-sm" line-height="ui.leading-code" overflow-wrap="break-word" font-family=uiFontFamily(uiFont) data-rightui-font="body"
                case none
                  text "No details." font-size="ui.text-sm" line-height="ui.leading-code" font-family=uiFontFamily(uiFont) data-rightui-font="body"

```
