---
id: "packages/active-ui/trace"
title: "Trace"
description: "The steps of a running task as quiet lines, with a status per step and steps that open to show details."
url: "/packages/active-ui/trace"
locale: "en"
revision: "fc79437aba284b40"
---

# Trace

A trace shows the steps of a task while it runs: files read, records checked, a calculation in
progress, a step that failed. Each step is a quiet line with an optional icon and description, and
can open to show its details. The trace runs nothing and tracks nothing: your application hands it
the steps and their status. For steps the reader takes, use a stepper.

**Example: The steps of a running task**

Client: Runs entirely in your browser. Source: `examples/ui/trace.tsx`.

```tsx
// apps/docs/examples/ui/trace.tsx
'use client';

import {
  CheckIcon,
  CircleAlertIcon,
  CircleDashedIcon,
  FileTextIcon,
  LoaderIcon,
} from 'lucide-react';

import {
  Trace,
  TraceCollapsible,
  TraceCollapsibleContent,
  TraceCollapsibleTrigger,
  TraceDescription,
  TraceIcon,
  TraceLine,
  TraceTitle,
} from '@workspace/active-ui/components/primitives/trace';

/**
 * The steps of a task as it runs, handed in by the application: done,
 * running, failed and pending, and a step that opens to show its details.
 * The trace runs nothing itself; the statuses here are fixed.
 */
export default function TraceExample() {
  return (
    <Trace className="w-full max-w-md">
      <TraceCollapsible defaultOpen>
        <TraceCollapsibleTrigger>
          <TraceLine>
            <TraceIcon>
              <FileTextIcon />
            </TraceIcon>
            <TraceTitle>Read 3 source files</TraceTitle>
          </TraceLine>
        </TraceCollapsibleTrigger>
        <TraceCollapsibleContent>
          participants.csv, schemes.csv, rates.csv
        </TraceCollapsibleContent>
      </TraceCollapsible>
      <TraceLine>
        <TraceIcon>
          <CheckIcon />
        </TraceIcon>
        <TraceTitle>Checked 214 addresses</TraceTitle>
        <TraceDescription>2 without a postal code</TraceDescription>
      </TraceLine>
      <TraceLine status="running">
        <TraceIcon>
          <LoaderIcon />
        </TraceIcon>
        <TraceTitle>Calculating the contributions</TraceTitle>
      </TraceLine>
      <TraceLine status="error">
        <TraceIcon>
          <CircleAlertIcon />
        </TraceIcon>
        <TraceTitle>Reading rates.csv failed</TraceTitle>
        <TraceDescription>Column “rate” is missing.</TraceDescription>
      </TraceLine>
      <TraceLine status="pending">
        <TraceIcon>
          <CircleDashedIcon />
        </TraceIcon>
        <TraceTitle>Sending the statements</TraceTitle>
      </TraceLine>
    </Trace>
  );
}
```

## Usage

```tsx
import {
  Trace,
  TraceIcon,
  TraceLine,
  TraceTitle,
} from '@workspace/active-ui/components/primitives/trace';

<Trace>
  <TraceLine status="running">
    <TraceIcon>
      <LoaderIcon />
    </TraceIcon>
    <TraceTitle>Calculating the contributions</TraceTitle>
  </TraceLine>
</Trace>;
```

## Anatomy

- `Trace`: the column of steps.
- `TraceLine`: one step. `status`: none (done), `running` (the title shimmers, and stands still under reduced
  motion), `error` or `pending` (dimmed).
- `TraceIcon`, `TraceTitle` and `TraceDescription`.
- `TraceCollapsible` with `TraceCollapsibleTrigger` and `TraceCollapsibleContent`: a step that opens
  to show details. Controlled, it needs both `open` and `onOpenChange`.

## What your application provides

- The steps, their order and their status, updated as the task advances.
- The meaning of a status in words where it matters: an error says what failed.
- An announcement of the outcome when the trace is the only sign of progress, for example with a
  live region or a toast.

## Accessibility

Steps are read as text in order. A collapsible step is a button that opens its details. The trace
is not a live region: changes are not announced by themselves.

## API

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | `"error" \| "pending" \| "running"` | no | The status of the step: none when done, `running` (the title shimmers), `error` or `pending` (a dimmed icon). |

### Other parts

**Trace**

| Prop | Type | Required | Description |
| --- | --- | --- | --- |

Trace has no props of its own.

**TraceIcon**

| Prop | Type | Required | Description |
| --- | --- | --- | --- |

TraceIcon has no props of its own.

**TraceTitle**

| Prop | Type | Required | Description |
| --- | --- | --- | --- |

TraceTitle has no props of its own.

**TraceDescription**

| Prop | Type | Required | Description |
| --- | --- | --- | --- |

TraceDescription has no props of its own.

**TraceCollapsible**

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `onOpenChange` | `((open: boolean, eventDetails: CollapsibleRootChangeEventDetails) => void)` | no | Event handler called when the panel is opened or closed. |
| `open` | `boolean` | no | Whether the step is open, when controlled; then with `onOpenChange`. |
| `defaultOpen` | `boolean` | no | Whether the collapsible panel is initially open.  To render a controlled collapsible, use the `open` prop instead. |
| `disabled` | `boolean` | no | Whether the component should ignore user interaction. |
| `render` | `ComponentRenderFn<HTMLProps, CollapsibleRootState> \| ReactElement<unknown, string \| JSXElementConstructor<any>>` | no | Allows you to replace the component's HTML element with a different tag, or compose it with another component.  Accepts a `ReactElement` or a function that returns the element to render. |

**TraceCollapsibleTrigger**

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `nativeButton` | `boolean` | no | Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `false` if the rendered element is not a button (for example, `<div>`). |
| `render` | `ComponentRenderFn<HTMLProps, CollapsibleTriggerState> \| ReactElement<unknown, string \| JSXElementConstructor<any>>` | no | Allows you to replace the component's HTML element with a different tag, or compose it with another component.  Accepts a `ReactElement` or a function that returns the element to render. |

**TraceCollapsibleContent**

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `hiddenUntilFound` | `boolean` | no | Allows the browser's built-in page search to find and expand the panel contents.  Overrides the `keepMounted` prop and uses `hidden="until-found"` to hide the element without removing it from the DOM. |
| `keepMounted` | `boolean` | no | Whether to keep the element in the DOM while the panel is hidden. This prop is ignored when `hiddenUntilFound` is used. |
| `render` | `ComponentRenderFn<HTMLProps, CollapsiblePanelState> \| ReactElement<unknown, string \| JSXElementConstructor<any>>` | no | Allows you to replace the component's HTML element with a different tag, or compose it with another component.  Accepts a `ReactElement` or a function that returns the element to render. |