Research

Installation#

# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

# Add this component (its dependencies come along)
npx koalaui-cli@latest add research

Usage#

Anatomy#

Research is the long sibling of MessageReasoning: reasoning is a few seconds of thought folded into a turn, research is a run of several minutes with phases and a pile of sources that keeps growing. It borrows the Plan for the confirmation step and the reasoning's vocabulary for everything else: muted ink, one live line, a caret that turns.

import {
  Research,
  ResearchHeader,
  ResearchIcon,
  ResearchTitle,
  ResearchElapsed,
  ResearchStatus,
  ResearchPlan,
  ResearchPhases,
  ResearchPhase,
  ResearchActivity,
  ResearchActivityItem,
  ResearchFavicon,
  ResearchFooter,
  ResearchSources,
  ResearchActions,
  ResearchStage,
  ResearchSummary,
  ResearchSummaryTrigger,
  ResearchSummaryContent,
} from "@/components/ui/research"

<Research>
  <ResearchHeader>
    <ResearchIcon />
    <ResearchTitle />
    <ResearchElapsed />
    <ResearchStatus />
  </ResearchHeader>
  <ResearchPlan>{/* Plan parts */}</ResearchPlan>
  <ResearchPhases>
    <ResearchPhase />
  </ResearchPhases>
  <ResearchStage>
    <ResearchActivity>
      <ResearchActivityItem />
    </ResearchActivity>
    <ResearchSummary>
      <ResearchSummaryTrigger />
      <ResearchSummaryContent />
    </ResearchSummary>
  </ResearchStage>
  <ResearchFooter>
    <ResearchSources />
    <ResearchActions />
  </ResearchFooter>
</Research>

The card is the only container. Phases, activity and the footer share the header's left edge and are set apart by whitespace, never by boxes or rules. Every part is droppable: a run with no plan step, a compact chip of just the sources, or a finished run that is only the summary line all work without rewiring.

Plan confirmation#

Before a long run spends minutes and money, it shows its angles. ResearchPlan is a plain Plan, so editing, adding and removing angles work exactly as they do there. Start the run, then use Update plan to steer it back.

Phases#

Set phase on the root and each ResearchPhase works out its own state: earlier phases fill and settle in ink, the current one runs an indeterminate bar with its label swept, later ones wait on a faint track. Pass progress when you know how far a phase is, or status for phases of your own.

Activity and sources#

The activity keeps four lines in view. A new line rises in from below and the stack climbs to make room; the oldest fade out under a top mask, so the eye stays on the newest line, which is the only one at full ink. Keep the array you render short (the last eight or so) and keep the full history for the summary. Favicons are letter tiles by default, so nothing is fetched from a third party unless you pass favicon. The sources chip counts up as pages land and opens the full list.

Done#

A finished run collapses to one sentence: how many sources, how long. The phases stay filled as the record of what happened, and the summary opens to the whole activity log for anyone who wants to audit the trail.

Stopped and failed#

Stopping keeps what was found. The phase it stopped in holds its partial fill in a quieter ink and the summary says how far it got, so the next step is a choice between resuming and writing up what is there. A failure reads the same way in the destructive tone, with the reason as the last line of the log.

Inside a conversation#

With variant="plain" the run sits in an assistant turn as part of the answer. Put it beside MessageContent inside a MessageBody, not inside the bubble, so the bubble's prose styles never reach its lists.

Density#

The card reads the density context. Compact tightens the block gaps, the padding and the activity line from 28 to 24px; the type and the radius stay put.

API reference#

FAQ#