AI Reasoning

Streamed reasoning steps that collapse into an accordion once Avi finishes working

Demo: Default - Continuous Updates

Mirrors the AAA-to-A2UI contract's success sequence step by step: click Next phase repeatedly to seed the header, stream the description, append steps, complete rows, and finish in the accordion. Styling follows semantic Skylab tokens, so it tracks the docsite's own light/dark theme toggle.

Demo: Error With Recovery

Starts in the terminal error accordion. Click Try again inside the alert to dispatch the step's s-recovery-action event, then click Next phase to resume and complete. Dismiss hides the alert but keeps the failed row visible, per the error contract.

API

Tag

Name	Description
`<s-ai-reasoning>`	Streamed AI reasoning progress with a linear in-progress phase and a collapsible completed phase

Attributes

Name	Value	Description
`inprogressheader`	string	Header shown during the linear in-progress phase, commonly `"Thinking..."` or `"Finding return recommendations..."`. Empty or omitted hides the header.
`description`	string	Supporting sentence shown under the in-progress header. Empty or omitted hides the description.
`completedheader`	string	Accordion heading shown once every step leaves `in-progress`. Empty or omitted keeps the linear phase rendered, even with no in-progress steps.
`stepsbyid`	string	Step dictionary keyed by stable step id, as a JSON object string. Each step carries an explicit `order`, so the host can append discovered steps and patch statuses without a separate ordering array. See Step shape.
`i18n`	string	A stringified JSON object which defines a list of localized strings. The keys must be one of the string IDs defined below.

Properties

Name	Type	Default	Description
`inProgressHeader`	`string`	`""`	Header shown during the linear in-progress phase.
`description`	`string`	`""`	Supporting sentence shown under the in-progress header.
`completedHeader`	`string`	`""`	Accordion heading shown once every step leaves `in-progress`.
`stepsById`	`Record<string, AiReasoningStep>`	`{}`	Step dictionary keyed by stable step id.
`i18n`	object		A JSON object which defines a list of localized strings. The keys must be one of the string IDs defined below.

Step shape

Field	Type	Description
`order`	`number`	Zero-based display order. The renderer sorts by this value, so a new step can be added with a single `stepsById` patch without a separate ordering array. Ties fall back to the step id.
`text`	`string`	Visible step text shown in the reasoning timeline. Use concise present-tense copy, e.g. "Reviewing your account information".
`status`	`'in-progress' \| 'done' \| 'error'`	`in-progress` renders the animated dots; `done` renders a check icon; `error` renders an alert-triangle icon and can surface `error` details. Only one step should usually be `in-progress` at a time.
`error`	`{ errorText: string; actions?: { text: string; action: unknown }[] }`	Optional. Provide only when `status` is `error`. Renders an error alert below the step list with up to two recovery buttons, shown regardless of whether the accordion is expanded. Omit to keep a step marked `error` without showing the alert.

Events

Name	Detail	Description
`s-recovery-action`	`{ stepId: string; action: unknown }`	Fired when a step's error recovery button is clicked. Hosts own action execution and receive the raw `action` payload in the event detail.

Demo: Default - Continuous Updates

Demo: Error With Recovery

API

Tag

Name
`<SAiReasoning>`

Props

Name	Type	Default	Description
`inProgressHeader`	`string`	`""`	Header shown during the linear in-progress phase.
`description`	`string`	`""`	Supporting sentence shown under the in-progress header.
`completedHeader`	`string`	`""`	Accordion heading shown once every step leaves `in-progress`.
`stepsById`	`Record<string, AiReasoningStep>`	`{}`	Step dictionary keyed by stable step id.
`i18n`	object		A JSON object which defines a list of localized strings. The keys must be one of the string IDs defined below.
`onS-recovery-action`	`(event: CustomEvent<{ stepId: string; action: unknown }>) => void`		Called when a step's error recovery button is clicked with the raw `action` payload.

Skylab React links

General information about using our React package

i18n Strings

ID	Description	Default value
`"aiReasoning.ariaLabel.inProgress"`	The `aria-label` on the linear in-progress phase.	Avi is reasoning
`"aiReasoning.ariaLabel.completed"`	The `aria-label` on the completed accordion phase.	Avi finished reasoning
`"aiReasoning.ariaLabel.expand"`	The `aria-label` on the accordion header when collapsed.	Show reasoning steps
`"aiReasoning.ariaLabel.collapse"`	The `aria-label` on the accordion header when expanded.	Hide reasoning steps
`"aiReasoning.status.inProgress"`	Visually-hidden status text announced for an in-progress step.	In progress
`"aiReasoning.status.done"`	Visually-hidden status text announced for a completed step.	Completed
`"aiReasoning.status.error"`	Visually-hidden status text announced for a failed step.	Failed

Guidelines

Phases

The component has two phases, computed from stepsById and completedHeader:

Linear - Shown while any step is in-progress, while there are no steps yet, or while completedHeader is empty. Renders the header, description, and step list top to bottom.
Accordion - Shown once every step is terminal (done or error) and completedHeader is set. Collapses the run behind a clickable header with a chevron. If any step errored, an error alert with recovery actions renders below the header regardless of whether it is expanded.

Keep one mounted s-ai-reasoning per reasoning run and patch its stepsById as the agent makes progress - for example replacing one record at stepsById.check-account - rather than mounting a new component for every update.

Accessibility

Each phase includes an off-screen role="status" live region so screen reader users get the same progress information as sighted users. Step icons are aria-hidden; each step also carries a visually-hidden status label (In progress, Completed, Failed). The accordion header exposes role="button", aria-expanded, and responds to Enter/Space in addition to click.

The animated dots and shimmering in-progress text respect prefers-reduced-motion.

Design

Design resources can be found on the Skylab design documentation site: skylab.avalara.com