Terminal

A theme-aware terminal emulator component powered by xterm.js. Colors automatically adapt to light/dark themes using DaisyUI color tokens.

Installation

This component requires @xterm/xterm and @xterm/addon-fit as peer dependencies:

npm install @xterm/xterm @xterm/addon-fit

Import

import { Terminal } from 'asterui/terminal'

Examples

Readline Mode

Built-in line editing with arrow keys and command history.

</>

import { Terminal } from 'asterui/terminal'

function App() {
  const terminalRef = useRef<TerminalRef>(null)
  
  return (
      <Terminal
        ref={terminalRef}
        readline
        prompt={'\x1b[32m$ \x1b[0m'}
        onReady={(term) => {
          term.writeln('Welcome to AsterUI Terminal!')
          term.writeln('Type something and press Enter.')
          term.writeln('Use arrow keys for line editing and history.')
        }}
        style={{ height: '100%' }}
      />
    )
}

export default App

Command Handler

Use onLine callback to handle commands in readline mode.

</>

import { Terminal, type TerminalRef } from 'asterui/terminal'
import { useRef } from 'react'

function App() {
  const terminalRef = useRef<TerminalRef>(null)
  
  const handleLine = (line: string) => {
    const term = terminalRef.current
    if (!term) return
  
    const cmd = line.trim().toLowerCase()
    if (cmd === 'help') {
      term.writeln('Available commands: help, date, clear, hello')
    } else if (cmd === 'date') {
      term.writeln(new Date().toString())
    } else if (cmd === 'clear') {
      term.clear()
    } else if (cmd === 'hello') {
      term.writeln('\x1b[36mHello, World!\x1b[0m')
    } else if (cmd) {
      term.writeln(`\x1b[31mUnknown command: ${cmd}\x1b[0m`)
    }
  }
  
  return (
      <Terminal
        ref={terminalRef}
        readline
        prompt={'\x1b[33m>\x1b[0m '}
        onLine={handleLine}
        onReady={(term) => {
          term.writeln('Simple command shell. Type "help" for commands.')
        }}
        style={{ height: '100%' }}
      />
    )
}

export default App

Ref Methods

Control the terminal programmatically via ref.

</>

import { Terminal, type TerminalRef } from 'asterui/terminal'
import { useRef } from 'react'

function App() {
  const terminalRef = useRef<TerminalRef>(null)
  
  const handleWrite = () => {
    terminalRef.current?.writeln('Hello from button!')
  }
  
  const handleClear = () => {
    terminalRef.current?.clear()
  }
  
  return (
      <div className="flex flex-col gap-2 h-full">
        <div className="flex gap-2">
          <button className="d-btn d-btn-sm d-btn-primary" onClick={handleWrite}>
            Write Line
          </button>
          <button className="d-btn d-btn-sm d-btn-secondary" onClick={handleClear}>
            Clear
          </button>
        </div>
        <div className="flex-1">
          <Terminal ref={terminalRef} style={{ height: '100%' }} />
        </div>
      </div>
    )
}

export default App

Custom Options

Pass xterm.js options for customization.

</>

import { Terminal } from 'asterui/terminal'

function App() {
  return (
      <Terminal
        options={{
          fontSize: 16,
          fontFamily: '"Fira Code", monospace',
          cursorBlink: false,
          cursorStyle: 'block',
        }}
        onReady={(term) => {
          term.writeln('Custom terminal with Fira Code font')
          term.writeln('fontSize: 16, cursorStyle: block')
        }}
        style={{ height: '100%' }}
      />
    )
}

export default App

ANSI Colors

Terminal supports ANSI escape codes for colored output.

</>

import { Terminal } from 'asterui/terminal'

function App() {
  return (
      <Terminal
        onReady={(term) => {
          term.writeln('\x1b[1mBold text\x1b[0m')
          term.writeln('\x1b[31mRed text\x1b[0m')
          term.writeln('\x1b[32mGreen text\x1b[0m')
          term.writeln('\x1b[33mYellow text\x1b[0m')
          term.writeln('\x1b[34mBlue text\x1b[0m')
          term.writeln('\x1b[35mMagenta text\x1b[0m')
          term.writeln('\x1b[36mCyan text\x1b[0m')
          term.writeln('')
          term.writeln('\x1b[42m\x1b[30m Green background \x1b[0m')
          term.writeln('\x1b[44m\x1b[37m Blue background \x1b[0m')
        }}
        style={{ height: '100%' }}
      />
    )
}

export default App

API

Terminal

Property	Description	Type	Default
readline	Enable readline mode with line editing and history	boolean	false
prompt	Prompt string for readline mode (supports ANSI colors)	string	'$ '
onLine	Callback when user submits a line in readline mode	(line: string) => void	-
onData	Callback for raw input (not used in readline mode)	(data: string) => void	-
onReady	Callback when terminal is initialized	(terminal: XTerm) => void	-
options	xterm.js options (theme is auto-applied)	ITerminalOptions	-
className	Additional CSS classes	string	-
style	Container style	React.CSSProperties	-
data-testid	Test ID for testing	string	-

TerminalRef

Access via useRef<TerminalRef>():

Property	Description	Type
terminal	The underlying xterm.js Terminal instance	XTerm | null
write	Write data to the terminal	(data: string) => void
writeln	Write a line to the terminal (with newline)	(data: string) => void
clear	Clear the terminal	() => void
focus	Focus the terminal	() => void
fit	Fit the terminal to its container	() => void
history	Command history array (readline mode)	string[]
clearHistory	Clear command history	() => void

Readline Mode

When readline is enabled, the terminal provides:

• Left/Right arrows: Move cursor within the current line
• Up/Down arrows: Navigate command history
• Backspace: Delete character before cursor
• Ctrl+C: Cancel current input
• Enter: Submit line (triggers onLine callback)

Theme Integration

The Terminal component automatically uses DaisyUI theme colors:

• Background/Foreground: Uses base-100 and base-content
• Cursor: Uses primary color
• ANSI Colors: Maps to error, success, warning, info, secondary, accent

When the theme changes (light/dark), the terminal colors update automatically.

WebSocket Example

import { Terminal, type TerminalRef } from 'asterui/terminal'
import { useRef, useEffect } from 'react'

function WebSocketTerminal({ url }: { url: string }) {
  const terminalRef = useRef<TerminalRef>(null)
  const wsRef = useRef<WebSocket | null>(null)

  useEffect(() => {
    const ws = new WebSocket(url)
    wsRef.current = ws

    ws.onmessage = (event) => {
      terminalRef.current?.write(event.data)
    }

    return () => ws.close()
  }, [url])

  return (
    <Terminal
      ref={terminalRef}
      onData={(data) => wsRef.current?.send(data)}
      style={{ height: 400 }}
    />
  )
}

Accessibility

• Terminal is keyboard accessible and focusable
• Supports screen reader announcements for terminal output
• High contrast themes work automatically via DaisyUI theme integration