ValyrianJS Terminal

Build terminal interfaces with Valyrian components. Render deterministic plain text for snapshots and command output, mount interactive sessions with focus and keyboard handling, or run imperative prompts with the same terminal runtime.

Use it when you want a terminal UI layer that stays close to your app code: primitives for layout and controls, session lifecycle for real terminals, and prompt helpers for setup flows, CLIs, and scripted interactions. Your app keeps routing, commands, data loading, persistence, and state transitions.

Install

npm install @valyrianjs/terminal valyrian.js

JSX config

For TSX, use Valyrian's automatic JSX runtime:

{
  "compilerOptions": {
    "jsx": "react-jsx",
    "jsxImportSource": "valyrian.js"
  }
}

Smallest useful example

Full example: examples/docs/interactive-note.tsx

import { Input, Screen, Text, mountTerminal } from "@valyrianjs/terminal";

const state = { value: "" };

function App() {
  return (
    <Screen>
      <Text>Quick note</Text>
      <Text>Type a note. Ctrl+C: exit.</Text>
      <Input
        id="note"
        value={state.value}
        placeholder="Write a note"
        onchange={(event) => {
          state.value = event.value;
        }}
      />
      <Text>{state.value ? `Draft: ${state.value}` : "Draft: empty"}</Text>
    </Screen>
  );
}

if (import.meta.main) {
  const session = mountTerminal(<App />);
  session.focus("note");
}

Choose the entry point by workflow:

• renderTerminal() for deterministic static output, snapshots, and command output.
• mountTerminal() for interactive sessions with focus, keyboard input, lifecycle, and repeated renders.
• createPromptRunner() for imperative prompt flows with static prompts, text entry, masked input, numbers, money amounts, editors, file picking, forms, single and multi-selection, search, progress, spinners, and confirmation.

Use Session Runtime when streams, resize events, clipboard adapters, mouse input, terminal title, or enhanced keyboard handling are part of the host integration.

Docs

• Getting Started - build a first working terminal UI with main.tsx, renderTerminal(), and mountTerminal().
• Core Concepts - mental model for primitives, state, ids, focus, output, and cleanup.
• Cookbook - practical recipes for input, lists, state, Valyrian.js modules, overlays, logs, and full-terminal layout.
• Primitive Gallery - choose and compose Screen, layout, input, collection, activity, and overlay primitives with complete mini apps.
• Prompt Examples - real interactive createPromptRunner() examples for every helper, plus a secondary headless pattern for tests.
• Interaction Model - keyboard, focus, event payloads, mouse, and composed interaction behavior.
• Session Runtime - common runtime usage and advanced host integration details.
• Valyrian Modules - terminal app patterns for Valyrian.js state, request, query, tasks, forms, persistence, formatting, and utilities.
• API Reference - public functions, props, payloads, and session methods.

Primitive Gallery maps every public terminal primitive to practical use and complete demos. Try these next:

• Operations Workspace: bun examples/docs/primitive-layout-shell.tsx
• Ticket Intake: bun examples/docs/primitive-input-workbench.tsx
• Service Explorer: bun examples/docs/primitive-data-explorer.tsx
• Activity Console: bun examples/docs/primitive-activity-console.tsx
• Command Panel: bun examples/docs/primitive-command-panel.tsx

Each example exits with Ctrl+C.

Valyrian.js modules can power complete terminal apps for state, forms, API calls, async work, formatting, i18n, persistence, and utilities while @valyrianjs/terminal renders the interface. See Valyrian.js modules in terminal apps, then run Operations Workbench with bun examples/docs/module-state-workbench.tsx, API Operations Dashboard with bun examples/docs/module-api-dashboard.tsx, or Billing/Settings Wizard with bun examples/docs/module-form-workflow.tsx; each exits with Ctrl+C.

Core controls use app-like visual defaults from the bundled theme, so buttons, inputs, and lists do not need per-example ASCII chrome. Style examples: examples/docs/style-system.tsx shows theme.styles, style, styles, and state in a runnable ANSI terminal app. Run it with bun examples/docs/style-system.tsx, use Tab, Enter, and W to change state, and quit with Ctrl+C. Layout examples: examples/docs/responsive-split.tsx shows context-aware Split sizing, percent, fr, and local split breakpoints. For a full-screen pizza builder with responsive Split fractions and simulated checkout, run bun examples/docs/pizza-builder.tsx, try Up/Down, Space, Enter, R, and C, and quit with Ctrl+C; or open examples/docs/pizza-builder.tsx.

Run the docs examples

Each docs example runs directly as a small terminal app. Use the command shown, try the listed keys, and quit with Ctrl+C unless the row describes a completing prompt flow. The prompt runner example finishes after you answer its prompts and calls runner.destroy() during cleanup.

| Example | Run | Try | | --- | --- | --- | | examples/docs/hello.tsx | bun examples/docs/hello.tsx | Enter, Ctrl+C | | examples/docs/interactive-note.tsx | bun examples/docs/interactive-note.tsx | type a note, Enter, Ctrl+C | | examples/docs/component-composition.tsx | bun examples/docs/component-composition.tsx | N/P, Ctrl+C | | examples/docs/employees-list.tsx | bun examples/docs/employees-list.tsx | J/K or arrows, Ctrl+C | | examples/docs/theme-colors.tsx | bun examples/docs/theme-colors.tsx | Tab, Ctrl+C | | examples/docs/style-system.tsx | bun examples/docs/style-system.tsx | Tab, Enter, W, Ctrl+C | | examples/docs/responsive-split.tsx | bun examples/docs/responsive-split.tsx | resize terminal, Ctrl+C | | examples/docs/pizza-builder.tsx | bun examples/docs/pizza-builder.tsx | Up/Down, Space, Enter, R, C, Ctrl+C | | examples/docs/background-fill.tsx | bun examples/docs/background-fill.tsx | B, Ctrl+C | | examples/docs/cursor.tsx | bun examples/docs/cursor.tsx | type text, C, Ctrl+C | | examples/docs/prompt-runner.ts | bun examples/docs/prompt-runner.ts | answer prompts | | Operations Workspace (examples/docs/primitive-layout-shell.tsx) | bun examples/docs/primitive-layout-shell.tsx | resize terminal, Ctrl+C | | Ticket Intake (examples/docs/primitive-input-workbench.tsx) | bun examples/docs/primitive-input-workbench.tsx | type summary, Tab, Enter, Ctrl+C | | Service Explorer (examples/docs/primitive-data-explorer.tsx) | bun examples/docs/primitive-data-explorer.tsx | J/K, Ctrl+C | | Activity Console (examples/docs/primitive-activity-console.tsx) | bun examples/docs/primitive-activity-console.tsx | Enter, Up/Down, Ctrl+C | | Command Panel (examples/docs/primitive-command-panel.tsx) | bun examples/docs/primitive-command-panel.tsx | type filter, Up/Down, Enter, Ctrl+C | | Terminal Command Palette (examples/docs/module-valyrian-core.tsx) | bun examples/docs/module-valyrian-core.tsx | J/K, Enter, R, Ctrl+C | | Live Shift/Ticket Counter (examples/docs/module-pulses.tsx) | bun examples/docs/module-pulses.tsx | A, D, P, R, Ctrl+C | | Operations Queue Manager (examples/docs/module-flux-store.tsx) | bun examples/docs/module-flux-store.tsx | J/K, S, D, B, R, Ctrl+C | | Service Status Client (examples/docs/module-request.tsx) | bun examples/docs/module-request.tsx | R, E, Ctrl+C | | Cached Inventory Browser (examples/docs/module-query.tsx) | bun examples/docs/module-query.tsx | F, I, J/K, Ctrl+C | | Background Maintenance Runner (examples/docs/module-tasks.tsx) | bun examples/docs/module-tasks.tsx | R, C, X, Z, Ctrl+C | | Profile Editor (examples/docs/module-forms.tsx) | bun examples/docs/module-forms.tsx | type fields, Enter, R, Ctrl+C | | Persistent Workspace Settings (examples/docs/module-native-store.tsx) | bun examples/docs/module-native-store.tsx | type workspace, Enter, R, Ctrl+C | | Bilingual Support Console (examples/docs/module-translate.tsx) | bun examples/docs/module-translate.tsx | L, J/K, F, Ctrl+C | | Invoice Calculator (examples/docs/module-money.tsx) | bun examples/docs/module-money.tsx | J/K, +/-, D, L, Ctrl+C | | Account Data Inspector (examples/docs/module-utils.tsx) | bun examples/docs/module-utils.tsx | J/K, F, R, Ctrl+C | | Operations Workbench (examples/docs/module-state-workbench.tsx) | bun examples/docs/module-state-workbench.tsx | J/K, Enter, D, B, R, Ctrl+C | | API Operations Dashboard (examples/docs/module-api-dashboard.tsx) | bun examples/docs/module-api-dashboard.tsx | R, E, I, T, C, Ctrl+C | | Billing/Settings Wizard (examples/docs/module-form-workflow.tsx) | bun examples/docs/module-form-workflow.tsx | N, L, S/Enter, R, X, Ctrl+C |