Notebook cell

A Jupyter style cell a data agent runs: execution count, highlighted code, a live timer, and nbformat outputs (streams, results, DataFrames, charts and tracebacks), with code and output that collapse on their own and a Notebook layout that stacks cells.

Markdown

On this page

The agent writes the cell, it queues, runs with a live timer, prints line by line and lands with a DataFrame.

Installation

$ pnpm dlx shadcn@latest add https://chatcn.dev/r/notebook-cell.json

Usage

tsx

import { NotebookCell } from "@/components/ui/chatcn/notebook-cell"

<NotebookCell
  code={cell.source}
  status="done"
  executionCount={3}
  durationMs={184}
  outputs={[
    { type: "stream", name: "stdout", text: "18,442 subscriptions, 611 churned in March\n" },
  ]}
  onRun={() => rerun(cell.id)}
/>

Outputs mirror nbformat, flattened to plain props: stream (stdout or stderr), text for an execute_result, table for a DataFrame, image for a chart, and error with the traceback the kernel sent. ANSI colors in streams and tracebacks map onto the kit hues. An output type the cell does not know is shown as text, never as a crash.

tsx

// A pandas DataFrame, head and tail of 611 rows
{
  type: "table",
  columns: ["account", "plan", "seats", "mrr"],
  index: [1042, 1187, 17733, 18391],
  rows: [...],
  headRows: 2,       // ellipsis row after the first two
  totalRows: 611,    // shows "611 rows x 4 columns"
}

Wrap several cells in Notebook and their counters move into one aligned gutter, with an optional file name, kernel line and actions such as Run all.

tsx

import { Notebook, NotebookCell } from "@/components/ui/chatcn/notebook-cell"

<Notebook title="churn-march-2026.ipynb" kernel="Python 3.12" kernelStatus="idle">
  {cells.map((cell) => (
    <NotebookCell key={cell.id} {...cell} />
  ))}
</Notebook>

Examples

Outputs

A DataFrame with its index, NULL and NaN badges and the size footer, a chart image that reserves its space before it loads, a pandas warning on stderr in an amber tint, and a plain result. Each long output scrolls inside its own area.

A DataFrame head and tail with NULL and NaN, a chart, a warning on stderr and a plain result.

Error and re-run

The exception name and value lead, then the traceback with the kernel's colors. The output label switches to Error and the header says Failed next to the run time.

A KeyError with its traceback in the kernel's colors. Re-run runs the cell again.

States

Never run, queued, running, no output, collapsed code, collapsed output and long output.

Notebook

Four cells from one analysis with the counters in one gutter. Run all queues them in order.

Status

Status	Counter	Header
`idle`	`[ ]` or the last count	Code glyph, Not run, Run
`queued`	`[*]`	Dashed circle, Queued, Remove from queue
`running`	`[*]` in blue	Spinner, Running, then a live counter in whole seconds
`done`	`[3]`	Green check and the run time, Re-run
`error`	`[3]`	Red cross, Failed and the run time, Re-run

Props

Prop	Type	Notes
`code`	`string`	Cell source
`language`	`string`	Defaults to `python`. Highlighted with the shared lazy Shiki
`status`	`"idle" \| "queued" \| "running" \| "done" \| "error"`	Defaults to `idle`
`executionCount`	`number \| null`	The `[3]` counter
`outputs`	`NotebookOutput[]`	Consecutive stream chunks of one name are joined
`streaming`	`boolean`	The agent is writing the code: caret on, Run hidden
`startedAt`, `durationMs`	`number`	Timing. Measured for you when omitted
`onRun`	`() => void`	Run or Re-run, and Shift Enter
`onInterrupt`	`() => void`	Stop a running cell or take it out of the queue
`codeCollapsed`, `defaultCodeCollapsed`, `onCodeCollapsedChange`	`boolean`	Controlled or uncontrolled
`outputCollapsed`, `defaultOutputCollapsed`, `onOutputCollapsedChange`	`boolean`	Controlled or uncontrolled
`maxOutputHeight`	`number \| string`	Each output scrolls past this. Default 320
`actions`	`ReactNode`	Extra header controls before Copy
`variant`	`"card" \| "plain"`	`plain` sits inside a surface you already have

Notebook

Prop	Type	Notes
`title`	`ReactNode`	File name, set in mono
`kernel`	`ReactNode`	For example `Python 3.12`
`kernelStatus`	`"idle" \| "busy" \| "disconnected"`	A static dot plus the word
`actions`	`ReactNode`	Run all, Restart and the like

Keyboard

Key	Action
`Tab`	Header actions, the code, each output and the output toggle in order
`Shift` `Enter`	Run the focused cell, like Jupyter. Ignored while it is busy
`Enter`, `Space`	On the output label: show or hide the output
Arrow keys	Scroll code, tables and long output once focused

Accessibility

Each cell is a labelled group, for example Cell 3, Python. The counter is decorative; the label carries it.
Finished and failed runs are announced once through a polite live region, for example Cell 3 finished in 1.3 s. The timer is never announced per tick.
Status never rides on color: a glyph and a word come with every hue. Standard error is labelled for screen readers.
Tables keep real headers, the index as row headers, and NULL or NaN spoken as null or not a number.
Chart images take the alt you pass. Write what the chart shows, not that it is a chart.
Code and output stay left to right inside a right-to-left page; the header follows the page.

Motion

The status glyph swaps with the kit's 150 ms blur crossfade as the cell queues, runs and lands.
The output panel opens and closes over 200 ms; collapsing code is instant, because it is a frequent action.
Output appends with no effects. While a cell runs, its output follows the newest line until you scroll up.
A chart fades in over 200 ms once it loads, into space that was reserved for it, so nothing below moves.
Under reduced motion the crossfade and panel height are removed; the image fade stays short.