Terminal

Installation

pnpm dlx shadcn@latest add @paneui/terminal

Usage

import { Terminal, createLocalShell, createMemoryFs } from "@/components/ui/terminal"

const [shell] = React.useState(() =>
  createLocalShell({ fs: createMemoryFs({ "README.md": "# hi\n" }) })
)

<Terminal transport={shell} className="h-80" />

Examples

Custom commands

Shared files

Real shell

Use the WebSocket transport to drive a shell on your machine through the PTY bridge.

Transports

Terminal only draws and takes keys; a TerminalTransport is the byte stream behind it. createLocalShell runs a shell in the page on a ShellFs. createWebSocketTransport talks to the PTY bridge: text frames carry data both ways and {"type":"resize","cols":n,"rows":n} resizes. Output sent before the view attaches is kept and replayed. Create a transport once (useState initialiser) and dispose it yourself; the view never disposes it, so it survives remounts.

PTY bridge

Installing the item also adds terminal-server/pty-bridge.mjs and its README. Run npm install node-pty, then node terminal-server/pty-bridge.mjs; it prints the address and token. It binds to 127.0.0.1 and rejects connections without the token, which grants shell access as you.

Local shell

Builtins: ls -la, cd, pwd, cat, echo -ne, mkdir -p, touch, rm -rf, mv, cp -r, head, tail, wc, grep -invcrl, sort, uniq -c, tree, clear, history, env, export, unset, which, help, date, whoami, hostname, true, false. js <code> evaluates the rest of the line (or stdin) with fs and process in scope and prints the result; node -e, node -p and node <file> run code too. Syntax: |, >, >>, <, &&, ||, ;, $VAR / ${VAR} / $?, NAME=value prefixes, ~, * / ? globs and quotes. Unknown commands exit 127 with command not found. cwd is also $HOME.

Keyboard

← → Home End, Backspace and Delete, ⌥/Ctrl+← → by word, ↑ ↓ history, Tab completes commands and paths (a second Tab lists matches), Ctrl+A / E start and end, Ctrl+U / K / W cut, Ctrl+Y pastes the cut, Ctrl+L clears, Ctrl+C cancels the line or a running command. Keys typed while a command runs are replayed when it ends. Pasted text with newlines runs line by line.

Theme and size

Colours come from the theme tokens of the element (its background and text colour, ANSI colours from destructive, success, warning, primary and the chart colours) and update when the dark class or the accent on <html> changes. The view fits its container on every resize and reports columns and rows to the transport. The emulator loads in the browser only, so it is safe in server-rendered and static pages.

API Reference

Terminal

transport*: TerminalTransport; Byte stream to a shell.
fontSize= 12: number; Font size in px.
autoFocus: boolean; Focus the terminal once it loads.
onTitleChange: (title: string) => void; Called when the shell sets the window title; the local shell sets user@host: cwd.
ref: Ref<TerminalHandle>; focus(), clear(), fit() and write(data).
className: string; Size and surface; the background and text colour also theme the emulator.

Prop	Type	Default	Description
transport*	TerminalTransport	—	Byte stream to a shell.
fontSize	number	12	Font size in px.
autoFocus	boolean	—	Focus the terminal once it loads.
onTitleChange	(title: string) => void	—	Called when the shell sets the window title; the local shell sets `user@host: cwd`.
ref	Ref<TerminalHandle>	—	`focus()`, `clear()`, `fit()` and `write(data)`.
className	string	—	Size and surface; the background and text colour also theme the emulator.

createLocalShell

Returns a TerminalTransport.

fs*: ShellFs; File system the shell works on.
cwd= "/": string; Start directory and $HOME.
user= "user": string; Shown in the prompt and whoami.
host= "localhost": string; Shown in the prompt and hostname.
commands: Record<string, ShellCommand>; Extra commands; they win over builtins. Each gets { args, cwd, fs, print, env, stdin } and returns an exit code (sync or async).

Prop	Type	Default	Description
fs*	ShellFs	—	File system the shell works on.
cwd	string	"/"	Start directory and `$HOME`.
user	string	"user"	Shown in the prompt and `whoami`.
host	string	"localhost"	Shown in the prompt and `hostname`.
commands	Record<string, ShellCommand>	—	Extra commands; they win over builtins. Each gets `{ args, cwd, fs, print, env, stdin }` and returns an exit code (sync or async).

createWebSocketTransport

Returns a TerminalTransport; connects when the view attaches.

url*: string; Bridge address with ?token=.

Prop	Type	Default	Description
url*	string	—	Bridge address with `?token=`.

createMemoryFs

Returns a ShellFs with subscribe for change notifications.

seed: Record<string, string>; Path → content. Parent directories are implied; a key ending in / makes an empty directory.

Prop	Type	Default	Description
seed	Record<string, string>	—	Path → content. Parent directories are implied; a key ending in `/` makes an empty directory.