API Reference

Full props, types, and imperative API reference.

Terminal Props

Prop	Type	Default	Description
variant	"dropdown" \| "inline" \| "floating" \| "fullscreen"	"dropdown"	Display mode
filesystem	FsNode[] \| FileSystem	—	Virtual filesystem tree or adapter
commands	Command[]	[]	Custom commands
plugins	TerminalPlugin[]	[]	Plugins to load
theme	TerminalThemeConfig	—	Theme integration config
logo	string \| string[] \| (() => string) \| false	—	ASCII art logo for welcome screen
welcomeMessage	string	—	Message shown below logo
bootSequence	BootStep[] \| false	—	Boot animation steps
crt	boolean	false	CRT scanline/glow effects
animate	boolean	true	Line fade-in animations
sounds	boolean \| SoundConfig	false	Procedural typing sounds
hotkey	string \| false	"`"	Toggle keyboard shortcut
defaultOpen	boolean	false	Start terminal open
persistState	boolean	true	Persist state to localStorage
storageKey	string	"terminal"	localStorage key prefix
colorMap	Partial<Record<OutputColor, string>>	—	Semantic color overrides
panels	{ id: string; component: ComponentType }[]	[]	Panel components
statusBar	StatusBarConfig	—	Status bar configuration
bottomBar	BottomBarItem[]	—	TUI-style shortcut bar
screenshotKey	string \| false	"ctrl+shift+s"	Screenshot shortcut
onNavigate	(path: string) => void	—	Navigation callback
closeOnNavigate	boolean	true	Close after navigation
onReady	() => void	—	Fires after boot completes
onPopOut	() => void	—	Pop-out button clicked
onDock	() => void	—	Dock button clicked
onScreenshot	(blob: Blob) => void	—	Screenshot callback
className	string	—	Additional CSS class

TerminalHandle

Use a ref to access the imperative API.

handle.tsx

import { useRef } from "react"
import { Terminal, type TerminalHandle } from "@trents/terminal"

function App() {
  const ref = useRef<TerminalHandle>(null)

  return (
    <>
      <Terminal ref={ref} />
      <button onClick={() => ref.current?.execute("help")}>
        Run help
      </button>
    </>
  )
}

Method	Signature	Description
execute	(command: string) => Promise<void>	Execute a command string
open	() => void	Open the terminal
close	() => void	Close the terminal
toggle	() => void	Toggle open/closed
focus	() => void	Focus the input field
clear	() => void	Clear all history

TerminalProvider

Wrap multiple <Terminal> components in a provider to share history and filesystem state across instances.

provider.tsx

import { Terminal, TerminalProvider } from "@trents/terminal"

<TerminalProvider storageKey="app-terminal">
  <Terminal ref={ref1} variant="dropdown" />
  <Terminal ref={ref2} variant="inline" />
</TerminalProvider>

Types

All types are exported from the main entry point.

types.ts

// Core
import type { Command, CommandResult, CommandContext } from "@trents/terminal"

// Output
import type { OutputSegment, OutputColor } from "@trents/terminal"

// Filesystem
import type { FsNode, FileSystem, FsEntry, FsStat } from "@trents/terminal"

// Plugins
import type { TerminalPlugin, PluginContext, MiddlewareFn, PanelProps } from "@trents/terminal"

// UI
import type {
  TerminalHandle,
  TerminalThemeConfig,
  BottomBarItem,
  BootStep,
  SoundConfig,
  StatusBarConfig,
  SelectOption,
  HistoryEntry,
} from "@trents/terminal"