# Log Stream

A run's log with an All or Errors filter and auto-scroll.

- Category: AI & Agents
- Page: https://wunderui.com/components/log-stream
- Tier: Core and Pro

## Install

Log Stream ships with WunderUI Core and Pro in the @wunderui/react package.

## Import

```tsx
import { LogStream } from "@wunderui/react"
```

## Minimal usage

Then use it:

```tsx
import { LogStream } from "@wunderui/react"

const LINES = [
  { id: "1", time: "0:01.4", level: "info", message: "Read 214 variables from Figma" },
  { id: "2", time: "0:05.2", level: "warn", message: "Figma API busy, retrying in 2 s" },
  { id: "3", time: "0:12.0", level: "error", message: "Push to docs-preview timed out" },
] as const

export function RunLog() {
  return <LogStream lines={[...LINES]} />
}
```

Expected result: You see a card titled Run log with All and Errors on the right, three lines with times, a Warn and an Error word, and Auto-scroll at the bottom. Press Errors and only the last line stays.

## When to use

### Use Log Stream for

- The timestamped lines a run writes while it works, newest at the bottom
- A log that keeps growing while the reader follows it, or reads back
- Finding the failure in a long run with the Errors filter

### Use something else

- [Terminal Output](https://wunderui.com/components/terminal-output) for one command with its exit code and its output streams
- [Run Timeline](https://wunderui.com/components/run-timeline) for the steps of a run with their duration and result
- [Activity Item](https://wunderui.com/components/activity-item) for one line per action, with a status, a tool and a time

## Keyboard

The filter and Auto-scroll are native buttons. The log is a focusable scroll region, so the usual scroll keys work.

| Key | Action |
|---|---|
| `Tab` or `Shift+Tab` | Moves focus through All, Errors, the log and Auto-scroll, in that order. Focus shows as an indigo ring. |
| `Enter` or `Space` | On All or Errors: shows that set of lines. On Auto-scroll: turns it on or off. `aria-pressed` follows. |
| `ArrowDown` or `ArrowUp` | In the focused log: scrolls it by a line. |
| `PageDown` or `PageUp` | In the focused log: scrolls it by a page. |
| `Home` or `End` | In the focused log: jumps to the oldest or the newest line. |

## Behavior

What the log does with its lines, the filter, scrolling, assistive technology and motion.

- **Lines:** Every line you pass is rendered in order, newest last. The array is the whole log, and each line needs an id so rows keep their identity.
- **Limits:** There is no cap and no virtualisation: each line is a DOM node. Keep the newest 200 to 500 lines in your own buffer; the log still scrolls to the newest one.
- **Filter:** All shows every line, Errors only error lines (a warning does not pass). The filter never changes your lines, and there is no search, so filter first.
- **Auto-scroll:** While on, each new array of lines and each filter change scrolls to the bottom. It does not notice the reader, so scrolling up gets pulled back by the next line unless you turn it off.
- **Live region:** The log is a polite live region, so added lines are read after the current speech: time, level word and message. Removed lines are not read.
- **Empty:** With no lines, or none that pass the filter, the log says Nothing logged yet or No errors so far. An empty label prop replaces both.
- **Failure:** The log has no state for a failed, stopped or dropped stream. Add a final error or warn line and say it in text next to the log.
- **States:** Filter buttons tint on hover and when pressed, and Auto-scroll darkens its text on hover. Buttons and the log show an indigo ring on keyboard focus.
- **Motion:** The component has no animation. Lines appear at once and the view jumps to the bottom; buttons change colour quickly.
- **Reduced motion:** Nothing moves, so there is nothing to reduce. With reduced motion only the colour changes remain, and they carry no meaning by themselves.

## Anatomy

- `LogStream`: A section named by its title with a 1 px border and 16 px radius: title and filter in a row, the log, and the Auto-scroll toggle.
- `Title`: The title (Run log by default) in one line of 15 px semibold text. It names the section and the log.
- `Level filter`: A group named Show with two toggle buttons, All and Errors. Control the level yourself or let the component keep it.
- `Log`: The scrolling region: a live log named by the title that a keyboard can scroll. It stops growing at the maximum height, 240 px by default.
- `Log line`: One row with the time, a level dot, the level word and the message. Give each line an id; without one, rows are keyed by position.
- `Time`: The time of the line, already formatted, in 11 px tabular numbers in a 46 px column.
- `Level`: A 6 px dot and the level word. Debug, warn and error show the word, info hides it visually, and screen readers read it for every level.
- `Message`: The message in 13 px text, using the free width. It wraps and breaks long words.
- `Auto-scroll toggle`: A button with a pin icon, on by default. Control it yourself or let the component keep the state.

## Best practices

### When to use

- Use Log Stream for timestamped lines a run writes as it works. One command with an exit code is Terminal Output, run steps are Run Timeline, one line per action is Activity Item.

### Do

- Pass the time already formatted and short, such as 0:02.9 or 14:02:11, and give every line a stable id. The time column is 46 px wide.
- Cap the array to the newest 200 to 500 lines and create a new array only when a line arrives. The log renders every line and does not virtualise.
- Mark failed lines with the error level. The Errors filter shows only those, and an empty result reads No errors so far.
- Say how the stream ended, in a line and in text next to the log: failure, stop or dropped connection. A stalled log looks like a quiet one.
- Give every Log Stream on a page its own title. Two landmarks with the same name cannot be told apart.
- Control auto-scroll when readers should be left alone while reading back. The log never turns it off by itself.

### Don't

- Don't append lines faster than a person can read. A polite live region queues announcements, so batch one second of lines into one.
- Don't pass HTML strings or untrusted markup as a message. Log lines come from tools and files, so render them as text.
- Don't expect search, copy or a line cap from the component. They belong to the page around it, as the Examples tab shows.

## API reference

### LogStream

| Prop | Type | Default | Description |
|---|---|---|---|
| lines* | LogLine[] |  | The lines, oldest first. Each has a `time` (already formatted), a `message` (text or parts), an optional `level` (`debug`, `info`, `warn`, `error`; default `info`) and an optional `id` used as the row key. |
| autoScroll | boolean |  | Controlled Auto-scroll. Pass it with `onAutoScrollChange`, for example to turn it off when the reader scrolls up. |
| className | string |  | Extra classes for the card, for example a width. |
| defaultAutoScroll | boolean | true | Whether Auto-scroll starts on when it is not controlled. Default `true`. |
| defaultLevel | "all" \| "errors" | "all" | The filter the log starts with when it is not controlled. Default `all`. |
| emptyLabel | React.ReactNode |  | Shown when no line passes the filter, in place of `Nothing logged yet.` and `No errors so far.` |
| level | "all" \| "errors" |  | Controlled filter, `all` or `errors`. Pass it with `onLevelChange`; without it the filter keeps its own state. |
| maxHeight | number | 240 | The height in px after which the log scrolls. Default `240`. |
| onAutoScrollChange | (autoScroll: boolean) => void |  | Called with the new value when the Auto-scroll button is pressed, controlled or not. It is not called when the log scrolls. |
| onLevelChange | (level: LogLevelFilter) => void |  | Called with `all` or `errors` when a filter button is pressed, controlled or not. |
| title | React.ReactNode | "Run log" | The heading of the card and the name of the log region. Default `Run log`. |

## Examples

### Level: info, debug, warn and error

### Filter: all lines, errors only, errors on a clean log

### Auto-scroll: on follows the newest line, off stays put

### Empty: nothing logged, no errors, your own text

### Line: run time, clock time, a long message, a message with code

## In context

### Live run: pause when the reader scrolls up

Scroll up while lines arrive and Auto-scroll turns off, with a button counting the missed lines. Press Jump to latest to follow again; the buffer keeps the newest 200 lines.

### Search and copy: filter before you pass the lines

The log has no search or copy of its own. The page filters the lines by level and text, passes only those, and copies the same lines, with a status line saying what the copy did.

### State: running, failed, stopped, connection lost

The log has no state of its own. The last lines and a text line under it say how the stream ended: a failure, a stop, or a dropped connection with a way to reconnect.

## For AI agents

`get_component("log-stream")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
