easy-terminal-cli

A customizable React terminal package component with theme support, perfect for building terminal-like interfaces in your React applications.

Features

• Multiple built-in themes (dark, light, matrix, retro)
• Custom theme support with full TypeScript definitions
• Lightweight and performant - no external dependencies
• Responsive design with customizable dimensions
• Customizable prompt and cursor
• Line history support with different line types
• TypeScript first with full type safety
• Universal compatibility - works with CJS, ESM, and TypeScript

Live DEMO

Check out Live terminal web Demo

Installation

npm install easy-terminal-cli

yarn add easy-terminal-cli

pnpm add easy-terminal-cli

Quick Start

Minimal Example

import React from 'react';
import { Terminal } from 'easy-terminal-cli';

const App: React.FC = () => {
  return (
    <div style={{ padding: 20, background: '#000', minHeight: '100vh', color: '#0f0' }}>
      <h2 style={{ color: '#0f0', textAlign: 'center' }}>Minimal Terminal Demo</h2>

      <Terminal
        prompt="user@mini:~$"
        theme="matrix"
        height={300}
        width="100%"
        showCursor
        cursorBlink
        commands={{
          help: () =>
            [
              'Available commands:',
              '  help         Show this message',
              '  hello        Print a greeting',
              '  clear        Clear the terminal',
            ].join('\n'),

          hello: () => 'Hello there! Welcome to this minimal terminal.',
        }}
      />
    </div>
  );
};

export default App;

API Reference

Terminal Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | theme | 'dark' \| 'light' \| 'matrix' \| 'retro' \| TerminalTheme | 'dark' | Terminal color theme | | prompt | string | '$' | Command prompt symbol | | height | string \| number | '400px' | Terminal height | | width | string \| number | '100%' | Terminal width | | lines | TerminalLine[] | [] | Array of terminal lines to display | | showCursor | boolean | true | Whether to show the cursor | | cursorBlink | boolean | true | Whether the cursor should blink | | className | string | '' | Additional CSS class name | | style | React.CSSProperties | {} | Additional inline styles |

TerminalLine Interface

interface TerminalLine {
  type: 'command' | 'output' | 'error';
  content: string;
  timestamp?: Date;
}

TerminalTheme Interface

interface TerminalTheme {
  backgroundColor: string;
  textColor: string;
  promptColor: string;
  cursorColor: string;
  fontFamily: string;
  fontSize: string;
  lineHeight: string;
}

Themes

Built-in Themes

Dark Theme (default)

<Terminal theme="dark" />

Light Theme

<Terminal theme="light" />

Matrix Theme

<Terminal theme="matrix" />

Retro Theme

<Terminal theme="retro" />

Custom Themes

You can create custom themes by passing a theme object:

const customTheme = {
  backgroundColor: '#2d3748',
  textColor: '#e2e8f0',
  promptColor: '#68d391',
  cursorColor: '#ed8936',
  fontFamily: 'Monaco, Consolas, monospace',
  fontSize: '16px',
  lineHeight: '1.5',
};

<Terminal theme={customTheme} />

Advanced Usage

Interactive Terminal with all examples

import React from 'react';
import { Terminal } from 'easy-terminal-cli';

/**
 * Demo application showcasing the full power of easy-terminal-cli.
 * Includes an extensive set of custom commands, async behaviour,
 * themed UI, and side‑effect examples (navigation, timers, logging).
 */

const jokes = [
  "Why do Java developers wear glasses? Because they don't C#.",
  "A SQL query walks into a bar, walks up to two tables and asks: 'Can I join you?'",
  "There are 10 kinds of people: those who understand binary and those who don't.",
];

const quotes = [
  'Code is like humor. When you have to explain it, it’s bad. – Cory House',
  'First, solve the problem. Then, write the code. – John Johnson',
  'Programs must be written for people to read, and only incidentally for machines to execute. – Harold Abelson',
];

const App: React.FC = () => {
  /** Simulated SPA navigation */
  const navigate = (route: string) => {
    console.log(`Navigating to /${route} ...`);
    window.history.pushState({}, '', `/${route}`);
  };

  return (
    <div style={styles.page}>
      <header style={styles.header}>
        <h1 style={styles.title}> Easy Terminal CLI – Mega Demo</h1>
        <p style={styles.subtitle}>
          Terminal component for React – with custom commands, async tasks & more.
        </p>
      </header>

      <main style={styles.main}>
        <Terminal
          prompt="dev@demo:~$"
          theme="matrix"
          height={420}
          width="100%"
          cursorBlink
          showCursor
          commands={{
            /** Make your OWN custom commands and functions **/
            /** Core help */
            help: () =>
              [
                ' Available commands:',
                '  help                Show this list',
                '  greet               Friendly greeting',
                '  echo <text>         Echo back text',
                '  math <expr>         Evaluate math expression',
                '  date                Show current date/time',
                '  joke                Random dev joke',
                '  quote               Random programming quote',
                '  ascii               Display cute ASCII cat',
                '  migrate             Simulate async migration',
                '  open <route>        Fake SPA navigation',
                '  theme <name>        Switch terminal theme',
                '  clear               Clear terminal',
              ].join('\n'),

            /** Simple static response */
            greet: () => 'Hello, Developer! Happy coding!',

            /** Echo user args */
            echo: (args) => args.join(' '),

            /** Math evaluator */
            math: (args) => {
              try {
                // eslint-disable-next-line no-eval
                const result = eval(args.join(' '));
                return `Result: ${result}`;
              } catch {
                return 'Invalid expression';
              }
            },

            /** Date/time */
            date: () => new Date().toString(),

            /** Random joke */
            joke: () => jokes[Math.floor(Math.random() * jokes.length)],

            /** Random quote */
            quote: () => quotes[Math.floor(Math.random() * quotes.length)],

            /** ASCII art */
            ascii: () => [' /\\_/\\', '( o.o )', ' > ^ <'].join('\n'),

            /** Async migration demo */
            migrate: () => {
              console.log(' Preparing migration…');
              setTimeout(() => console.log(' Migrating data…'), 800);
              setTimeout(() => console.log(' Migration complete.'), 2000);
            },

            /** Fake page navigation */
            open: (args) => {
              if (args[0]) {
                navigate(args[0]);
                return `Opening /${args[0]} ...`;
              }
              return 'Usage: open <route>';
            },
          }}
        />
      </main>
    </div>
  );
};


const styles: Record<string, React.CSSProperties> = {
  page: {
    background: 'linear-gradient(135deg, #0d0d0d 0%, #1a1a1a 100%)',
    color: '#fff',
    minHeight: '100vh',
    display: 'flex',
    flexDirection: 'column',
    alignItems: 'center',
    fontFamily: 'Inter, sans-serif',
  },
  header: {
    marginTop: 48,
    textAlign: 'center',
  },
  title: {
    fontSize: '2.8rem',
    lineHeight: 1.2,
    background: 'linear-gradient(90deg,#00c6ff,#0072ff)',
    WebkitBackgroundClip: 'text',
    color: 'transparent',
    margin: 0,
  },
  subtitle: {
    marginTop: 8,
    fontSize: '1.1rem',
    color: '#bbbbbb',
  },
  main: {
    marginTop: 40,
    width: '90%',
    maxWidth: 960,
  },
  footer: {
    marginTop: 'auto',
    padding: '32px 0',
    fontSize: '0.85rem',
    color: '#888',
  },
  link: {
    color: '#00c6ff',
    textDecoration: 'none',
  },
};

export default App;

Responsive Terminal

<Terminal
  theme="dark"
  height="50vh"
  width="90vw"
  style={{ 
    maxWidth: '800px',
    margin: '0 auto',
    border: '2px solid #333',
    borderRadius: '8px'
  }}
/>

TypeScript Support

This package is built with TypeScript and provides full type definitions. No additional @types packages are needed.

import { Terminal, TerminalProps, TerminalTheme, TerminalLine } from 'easy-terminal-cli';

const props: TerminalProps = {
  theme: 'dark',
  lines: [
    { type: 'command', content: 'ls -la' },
    { type: 'output', content: 'total 42' }
  ]
};

Configuration props

interface TerminalProps {
  theme?: 'dark' | 'light' | 'matrix' | 'retro' | TerminalTheme;
  prompt?: string;
  height?: string | number;
  width?: string | number;
  showCursor?: boolean;
  cursorBlink?: boolean;
  className?: string;
  style?: React.CSSProperties;
  commands?: Record<string, (args: string[]) => void | string | string[]>;
}

Compatibility

• React 16.8+ (Hooks support required)
• TypeScript 4.0+
• Next.js (SSR compatible)
• Create React App
• Vite
• Webpack
• Node.js (for SSR/testing)

Browser Support

• Chrome 88+
• Firefox 85+
• Safari 14+
• Edge 88+

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Development Setup

# Clone the repository
git clone https://github.com/officiallyutso/easy-terminal-cli.git
cd easy-terminal-cli

# Install dependencies
npm install

# Start development mode
npm run dev

# Run type checking
npm run type-check

# Build the package
npm run build

License

MIT © UTSO SARKAR

Changelog

v1.1.4

• Usage codes added to doc

v1.1.3

• Live Demo added

v1.1.2

• Fixed blinking cursor behaviour

v1.1.1

• Custom command system with support for side effects and console.log capture
• Built-in commands: clear, theme
• Dynamic theming (dark, light, matrix, retro)
• React + TypeScript support with full customization

v1.0.0

• Initial release
• Basic terminal component with theme support
• TypeScript definitions
• Built-in themes: dark, light, matrix, retro
• Customizable prompt and cursor

Made for the React community