Trace
The steps of a running task as quiet lines, with a status per step and steps that open to show details.
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.
// 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#
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.Trace: one step.Line status: none (done),running(the title shimmers, and stands still under reduced motion),errororpending(dimmed).Trace,Icon TraceandTitle Trace.Description TracewithCollapsible TraceandCollapsible Trigger Trace: a step that opens to show details. Controlled, it needs bothCollapsible Content openandon.Open Change
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#
Import from @workspace/
Props
- Type
"error""pending""running"
The status of the step: none when done, running (the title shimmers), error or pending (a dimmed icon).
Other props, such as the standard attributes of the underlying element, className and ref, are passed through.
Other parts#
TraceCollapsible
Props marked Base UI are behaviour of the Base UI part this component is built on.
Props
- Type
boolean
Whether the step is open, when controlled; then with on.
- Type
boolean- Default
false
Whether the collapsible panel is initially open.
To render a controlled collapsible, use the open prop instead.
- Type
boolean- Default
false
Whether the component should ignore user interaction.
- Type
ComponentRender Fn<…> ReactElement<…>
Allows you to replace the component's HTML element with a different tag, or compose it with another component.
Accepts a React or a function that returns the element to render.
Events
Called by the component when something happens.
- Type
(open, eventDetails) => void
Event handler called when the panel is opened or closed.
Other props, such as the standard attributes of the underlying element, className and ref, are passed through.
TraceCollapsibleTrigger
All props come from the Base UI part this component is built on.
Props
- Type
ComponentRender Fn<…> ReactElement<…>
Allows you to replace the component's HTML element with a different tag, or compose it with another component.
Accepts a React or a function that returns the element to render.
Other props, such as the standard attributes of the underlying element, className and ref, are passed through.
TraceCollapsibleContent
All props come from the Base UI part this component is built on.
Props
- Type
boolean- Default
false
Whether to keep the element in the DOM while the panel is hidden. This prop is ignored when hidden is used.
- Type
ComponentRender Fn<…> ReactElement<…>
Allows you to replace the component's HTML element with a different tag, or compose it with another component.
Accepts a React or a function that returns the element to render.
Other props, such as the standard attributes of the underlying element, className and ref, are passed through.
Parts that take only their element’s attributes
Trace: the attributes of a<div>, with className and ref.Trace: the attributes of aIcon <span>, with className and ref.Trace: the attributes of aTitle <span>, with className and ref.Trace: the attributes of aDescription <span>, with className and ref.