Terminal

Installation#

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

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

Usage#

The parts paint; the loop is yours. A working shell is a list of lines, the text being typed, and a key handler that turns Enter into output.

import * as React from "react"
import {
  Terminal,
  TerminalField,
  TerminalInputLine,
  TerminalLine,
  TerminalPrompt,
  TerminalScreen,
  type TerminalTone,
} from "@/components/ui/terminal"

type Line = { id: number; text: string; tone: TerminalTone }

export function Example() {
  const [lines, setLines] = React.useState<Line[]>([])
  const [input, setInput] = React.useState("")

  const run = (command: string) => {
    if (command === "clear") return setLines([])
    setLines((l) => [
      ...l,
      { id: l.length, text: command, tone: "in" },
      { id: l.length + 1, text: `you said: ${command}`, tone: "out" },
    ])
  }

  return (
    <Terminal className="h-80">
      <TerminalScreen>
        {lines.map((line) => (
          <TerminalLine key={line.id} tone={line.tone}>
            {line.tone === "in" && <TerminalPrompt prefix="app" />}
            {line.text}
          </TerminalLine>
        ))}
        <TerminalInputLine>
          <TerminalPrompt prefix="app" />
          <TerminalField
            aria-label="Command"
            value={input}
            onChange={(e) => setInput(e.target.value)}
            onKeyDown={(e) => {
              if (e.key !== "Enter") return
              run(input.trim())
              setInput("")
            }}
          />
        </TerminalInputLine>
      </TerminalScreen>
    </Terminal>
  )
}

Anatomy#

import {
  Terminal,
  TerminalBar,
  TerminalControls,
  TerminalField,
  TerminalIndicator,
  TerminalInputLine,
  TerminalLine,
  TerminalPrompt,
  TerminalScreen,
  TerminalTitle,
  TerminalTitleTag,
  TerminalTray,
  TerminalWatermark,
} from "@/components/ui/terminal"

<Terminal>
  {/* A faint stamp behind the scrollback */}
  <TerminalWatermark />
  {/* The title bar, and the drag handle */}
  <TerminalBar>
    <TerminalIndicator />
    <TerminalTitle>
      <TerminalTitleTag />
    </TerminalTitle>
    <TerminalControls />
  </TerminalBar>
  {/* The scrollback, a ScrollArea */}
  <TerminalScreen>
    <TerminalLine />
    <TerminalInputLine>
      <TerminalPrompt />
      <TerminalField />
    </TerminalInputLine>
  </TerminalScreen>
  {/* Live results, suggestions, a status line */}
  <TerminalTray />
</Terminal>

Line tones#

tone sets a line's ink. in is a command that was run, in the foreground ink; out (the default) and raw are output in the reading ink; dim is a comment in the meta grey; err and ok take the status hues' text step, which still reads on the light themes.

Clickable lines#

Give a line onClick and it becomes a button: focusable, run by a click, Enter or Space, with a highlight that keeps the text on its column. For search results, a file listing, or a #N the user would otherwise have to type.

Prompt, completion and cursor#

TerminalPrompt takes a prefix and a mark ("> " by default). TerminalField paints what is typed and a block cursor at the caret: it follows the arrow keys and sits over the character it is on. ghost is the grey completion after it; accepting it is your key handler's job (Tab or → here, at the end of the line). The cursor is a solid block while the field has focus and a hollow cell when it doesn't; drive cursorVisible from a timer to make it blink.

A blink that restarts lit on every keystroke, and holds still under reduced motion:

function BlinkingField(props: Omit<TerminalFieldProps, "cursorVisible">) {
  const [beat, setBeat] = React.useState({ value: props.value, lit: true })
  if (beat.value !== props.value) setBeat({ value: props.value, lit: true })
  React.useEffect(() => {
    if (window.matchMedia("(prefers-reduced-motion: reduce)").matches) return
    const timer = setInterval(() => setBeat((b) => ({ ...b, lit: !b.lit })), 530)
    return () => clearInterval(timer)
  }, [props.value])
  return <TerminalField cursorVisible={beat.lit} {...props} />
}

Tray#

TerminalTray is the band under the scrollback, on a quieter tint: live results while the user types, suggestions, a status line. It holds Koala components (a Badge, a Kbd, a Command list) or clickable TerminalLines, as here.

Window chrome#

TerminalBar carries the TerminalIndicator, a TerminalTitle (with an optional TerminalTitleTag) and TerminalControls, where buttons default to the 32px tier that fits the bar. What the controls do is yours: here they minimize and widen the window, and a double-click on the bar widens it too. movable gives the bar a grab cursor and dragging holds the grabbing one while your pointer handlers move the window. TerminalWatermark lays a faint stamp behind the scrollback.

PreviewCode

Buildproduction

ci $ npm run build

▲ Next.js 16.3.6

Creating an optimized production build…

✓ Compiled successfully in 14.2s

Collecting page data and generating 412 static pages

✓ Done in 41.8s

API reference#

FAQ#