# Trace The building block for reasoning, tool calls, sources and more. ```twig
Why does pnpm install fail in CI? Thought for 5s CI installs with a frozen lockfile, so the install stops when package.json and pnpm-lock.yaml disagree. I should check what the last commit changed, then reproduce the install. Ran pnpm --version 10.18.0 Ran git diff --stat HEAD~1 -- package.json pnpm-lock.yaml package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) Failed to run pnpm install --frozen-lockfile ERR_PNPM_OUTDATED_LOCKFILE Cannot install with "frozen-lockfile" because pnpm-lock.yaml is not up to date with package.json Used 2 sources {% for source in [ {title: 'pnpm install | pnpm.io', url: 'https://pnpm.io/cli/install#--frozen-lockfile'}, {title: 'Continuous Integration | pnpm.io', url: 'https://pnpm.io/continuous-integration'}, ] %} {{ source.title }} (opens in a new tab) {% endfor %}

The last commit bumped a version in package.json without updating pnpm-lock.yaml, so the frozen install fails. Run pnpm install locally and commit the lockfile.
``` ## Installation > [!NOTE] > Available since UX Toolkit 3.7. ```shell php bin/console ux:install trace --kit shadcn ``` ## Usage Use a `Trace:Line` for a single step: ```twig Searched for minimumReleaseAge ``` Wrap the line in a `Trace:Collapsible` to show more detail when it expands: ```twig Ran node --version v24.18.0 ``` ## Examples ### Trace Line Use a `Trace:Line` on its own for a step with no detail to show. It reads as plain text. ```twig Created branch fix/frozen-lockfile ``` ### Status Set `status` on `Trace:Line` when a step is running, has failed or hasn't started yet. ```twig Ran pnpm install Failed to run pnpm lint Running pnpm build Run pnpm test ``` ### Description Put secondary text such as a diff stat, a duration or a count in a `Trace:Description` after the `Trace:Title`. It does not truncate. ```twig Edited components/settings/notification-preferences-form.tsx +48 −12 Ran pnpm test 14s Searched for useChat 8 results ``` ### Collapsible Wrap the line in a `Trace:Collapsible` to show more detail when it expands. Put the `Trace:Line` inside `Trace:Collapsible:Trigger` and the detail in `Trace:Collapsible:Content`. ```twig
Ran node --version $ node --version v24.18.0
``` ### Open State Rows start closed. Set `open` on `Trace:Collapsible` to start open. To toggle a row from another button inside it, wrap that button in `Collapsible:Trigger` and spread `collapsible_trigger_attrs` on it. That button then also reflects the open state, through its `aria-expanded` and `data-state` attributes. ```twig
Ran node --version $ node --version v24.18.0 Ran pnpm --version $ pnpm --version 10.33.4 Show the pnpm output
``` ### Link Wrap the `Trace:Line` in an anchor. For a new tab, use an arrow-up-right icon and sr-only "(opens in a new tab)". ```twig Read apps/v4/lib/docs.ts Install Astro | docs.astro.build (opens in a new tab) ``` ### Dialog Wrap the `Trace:Line` in the dialog's trigger. The dialog owns its open state, Escape and focus return. ```twig
Searched the web for cache keys Three results were used in the response. {% for result in [ {title: 'Caching build outputs', url: 'https://nextjs.org/docs/app/guides/caching'}, {title: 'Image optimization reference', url: 'https://nextjs.org/docs/app/api-reference/components/image'}, {title: 'Deploy hooks and cache keys', url: 'https://vercel.com/docs/deploy-hooks'}, ] %} {{ result.title }} (opens in a new tab) {% endfor %}
``` ### Sheet The same shape as the dialog. Drawer and Popover work the same way. ```twig
Explored 4 files Files read while preparing the response.
  • apps/v4/lib/docs.ts
  • apps/v4/lib/components.ts
  • apps/v4/next.config.mjs
  • apps/v4/package.json
``` ### Group Put rows that sit next to each other in a `Trace`. It also styles any trigger or link that wraps a `Trace:Line`. ```twig Searched for minimumReleaseAge Read pnpm-workspace.yaml Ran pnpm install ``` ### Sources A collapsible row whose detail is a `Trace` of link rows. ```twig
Used 3 sources {% for source in [ {title: 'Install Astro | docs.astro.build', href: 'https://docs.astro.build/en/install-and-setup/'}, {title: 'create-astro | npmjs.com', href: 'https://www.npmjs.com/package/create-astro'}, {title: 'Settings: minimumReleaseAge | pnpm.io', href: 'https://pnpm.io/settings#minimumreleaseage'}, ] %} {{ source.title }} (opens in a new tab) {% endfor %}
``` ### Chain of Thought A chain of thought is a collapsible row with step rows inside. Set the parent's status and title from its children. ```twig
Looking into the slow deploy Searched for the checkout build log vercel.com github.com Read the last twelve deploys Searching for the cache key cache key image optimization
``` ### Commit A commit is a collapsible row with a line for each changed file. Say what changed in the title, Added, Edited or Deleted, and put the line counts in the description. Each file opens its diff in a [Sheet](#sheet). ```twig
Committed a1b2c3: Fix the login redirect {% for file in [ { id: 'login-page', path: 'app/login/page.tsx', added: false, additions: 2, deletions: 2, lines: [ {variant: 'hunk', text: '@@ -14,7 +14,7 @@ export default async function LoginPage({'}, {variant: 'default', text: ' searchParams,'}, {variant: 'default', text: '}) {'}, {variant: 'default', text: ' const { next } = await searchParams'}, {variant: 'removed', text: ' const redirectTo ='}, {variant: 'removed', text: ' next && next.startsWith("/") ? next : "/"'}, {variant: 'added', text: ' const redirectTo = safeRedirect(next)'}, {variant: 'added', text: ''}, {variant: 'default', text: ' return '}, {variant: 'default', text: '}'}, ], }, { id: 'auth-redirect', path: 'lib/auth/redirect.ts', added: true, additions: 7, deletions: 0, lines: [ {variant: 'hunk', text: '@@ -0,0 +1,7 @@'}, {variant: 'added', text: 'export function safeRedirect(next: string | undefined) {'}, {variant: 'added', text: ' if (!next || !next.startsWith("/") || next.startsWith("//")) {'}, {variant: 'added', text: ' return "/"'}, {variant: 'added', text: ' }'}, {variant: 'added', text: ''}, {variant: 'added', text: ' return next'}, {variant: 'added', text: '}'}, ], }, ] %} {{ file.path }} {{ file.additions }} additions, {{ file.deletions }} deletions {%- for line in file.lines -%} {{ line.text }} {%- endfor -%} {% endfor %}
``` ### Whole Turn Three levels: the turn, a summary, and the rows. Text between steps sits between two `Trace` lists. ```twig
Worked for 2m 4s, 1 command failed Thought 12s I should check which package managers are installed before I scaffold anything. Ran 2 commands, 1 failed Ran node --version Failed to run pnpm --version command not found: pnpm

Node is installed and pnpm is not. Reading the docs config.

Read apps/v4/lib/docs.ts
``` ### Reasoning Render the reasoning of an assistant turn. The row is a `Trace:Line` until the first text arrives: give it `status="running"` and the title "Thinking" while it streams, then wrap it in a `Trace:Collapsible` with the reasoning as its content. ```twig
Why is the checkout deploy so slow? Thought The build log shows install and compile finish in under a minute. Image optimization takes almost four, and it reruns on every deploy because the cache key includes the commit hash.

Image optimization is the bottleneck. Key its cache on the lockfile and the image directory instead of the commit hash.
``` ### Tool Render the tool calls of an assistant turn. A finished call is a collapsible row with its output, a failed one has `status="error"`, and a running one is a `Trace:Line` with `status="running"`. ```twig
Which package managers are installed? {% for call in [ {command: 'node --version', output: 'v24.18.0', failed: false}, {command: 'npm --version', output: '11.6.2', failed: false}, {command: 'pnpm --version', output: 'command not found: pnpm', failed: true}, ] %} {{ call.failed ? 'Failed to run' : 'Ran' }} {{ call.command }} {{ call.output }} {% endfor %}

Node 24 and npm 11 are installed. pnpm is not.
``` ### RTL To enable RTL support, set the `dir="rtl"` attribute on the root element. ```twig
{# Arabic #} تم تشغيل node --version v24.18.0 فشل تشغيل pnpm lint تمت قراءة apps/v4/lib/docs.ts 12 ثانية {# Hebrew #} הורץ node --version v24.18.0 הרצת pnpm lint נכשלה נקרא apps/v4/lib/docs.ts 12 שניות
``` ## Accessibility - `Trace` adds no roles of its own. Each line gets its semantics from the element that wraps it. - A `Trace:Line` on its own is a `span`. It is read as text and is not a tab stop. - Wrap it in a `Trace:Collapsible:Trigger` and it becomes a button with `aria-expanded`. Wrap it in a link, or in the trigger for a dialog or sheet, and it takes the keyboard and focus behavior of that element. - `Trace:Icon` is hidden from assistive tech, so `Trace:Title` is the accessible name. Write it as a sentence that says what happened, like "Edited trace.html.twig", not just "trace.html.twig". - When a link opens a new tab, add "(opens in a new tab)" to the title with `sr-only`. - Status is shown with color and motion, so put it in the title too. Write "Running pnpm build" while it runs and "Failed to run pnpm build" when it errors. - The shimmer on a running title stops when the reader prefers reduced motion. The title still says what is happening. - `Trace:Collapsible:Content` mutes its text. If you put a block with a muted background inside it, give the block `text-foreground` so it keeps its contrast. ## API Reference ### `` | Block | Description | |:------|:------------| | `content` | The rows of the trace: `Trace:Line`, `Trace:Collapsible`, or a link or trigger wrapping a `Trace:Line`. | ### `` | Prop | Type | Default | Description | |:-----|:-----|:--------|:------------| | `open` | `boolean` | `false` | Whether the row is open on initial render. | | Block | Description | |:------|:------------| | `content` | The row, typically includes `Trace:Collapsible:Trigger` and `Trace:Collapsible:Content`. | ### `` | Block | Description | |:------|:------------| | `content` | The detail revealed when the row is open. | ### `` | Block | Description | |:------|:------------| | `content` | The `Trace:Line` that opens and closes the row. | ### `` | Block | Description | |:------|:------------| | `content` | Secondary text, such as a count or a duration. | ### `` | Block | Description | |:------|:------------| | `content` | The decorative icon. Before the title it names the action, after it is the indicator. | ### `` | Prop | Type | Default | Description | |:-----|:-----|:--------|:------------| | `status` | `'running'\|'error'\|'pending'\|null` | `null` | The state of the work the line reports. | | Block | Description | |:------|:------------| | `content` | The line content, typically includes `Trace:Icon`, `Trace:Title` and optionally `Trace:Description`. | ### `` | Block | Description | |:------|:------------| | `content` | One sentence that says what happened. |