Terminal

Terminal UI component that allows users to interact with the terminal-like interface.

Import

import {Terminal} from '@kaiverse/k/ui'

Usage

Try command hello and then clear in the terminal below:

Playground
Source code

Terminal

T
E  __      __        __                    
R /  \    /  \ ____ |  |   ____  ____   _____   ____  
M \   \/\/   // __ \|  | _/ ___\/  _ \ /     \_/ __ \ 
I  \        /\  ___/|  |_\  \__(  <_> )  Y Y  \  ___/ 
N   \__/\  /  \___  >____/\___  >____/|__|_|  /\___  >
A        \/       \/          \/            \/     \/
L

Try command hello and then clear:

import {Terminal} from '@kaiverse/k/ui'

export default function TerminalUsageDemo() {
  return (
    <Terminal
      className="max-h-[30dvh]"
      windowTitle="Terminal"
      greeting={
        <p>
          {`T
E  __      __        __
R /  \\    /  \\ ____ |  |   ____  ____   _____   ____
M \\   \\/\\/   // __ \\|  | _/ ___\\/  _ \\ /     \\_/ __ \\
I  \\        /\\  ___/|  |_\\  \\__(  <_> )  Y Y  \\  ___/
N   \\__/\\  /  \\___  >____/\\___  >____/|__|_|  /\\___  >
A        \\/       \\/          \\/            \\/     \\/
L\n\n`}
          Try command <code className="text-blue-400">hello</code> and then{' '}
          <code className="text-rose-400">clear</code>:
        </p>
      }
      commandHandler={(command, {println}) => {
        if (command === 'hello') {
          println('Hello world👋!')
          return 'skip_default'
        }
      }}
    />
  )
}

Handle Command

You can provide your custom handler by using commandHandler prop.
Your function should returns "skip_default" if the command is manually handled and/or you wanna skip the default handler.
Otherwise, commands will be executed by it.

Default Commands

clear or cls - clear the terminal
Others - println: “command not found”.

Helpers

commandHandler prop also has a collection of built-in helpers (2nd argument), you can call it to manipulate the terminal’s history (log) section.

Helpers that ship with the commandHandler prop:
printNode - prints a React node
println - prints a string with a newline
clearHistory - clears the terminal history
Try command print or p to log messages, and then clear.

You can also access these helpers via ref as well.

<Terminal
  commandHandler={(rawCommand, {printNode, println}) => {
    const command = rawCommand.trim()

    if (command === 'print' || command === 'p') {
      const currentTime = new Date().toLocaleTimeString()

      printNode(
        <>
          <span className="text-green-400">{currentTime}</span>
          [<code className="text-blue-400">printNode</code>] <img src="..." /> Command: {command}
        </>,
      )
      println(`\n${currentTime} [println] Command: ${command}`)
      return 'skip_default' // skip the default handler
    }

    // let the default handler handle all other commands
  }}
/>

import {Terminal, type TerminalRef} from '@kaiverse/k/ui'

const terminalRef = useRef<TerminalRef>(null)

<Terminal ref={terminalRef} />

<button
  type="button"
  onClick={() =>
    terminalRef.current?.println(`${new Date().toLocaleTimeString()} [println]: Trigger println via TerminalRef`)
  }
>
  Println
</button>

`printNode`

Prints a ReactNode to Terminal history section.

`println`

Prints a string with a newline.

`clearHistory`

Clears the terminal history. Same as the default clear or cls command.

Customization

Title & greatings

The greeting prop accept a ReactNode.

¯\_(ツ)_/¯

<Terminal
  windowTitle="¯\_(ツ)_/¯"
  greeting={<img width="120" height="120" src="https://i.redd.it/fktuppkre7p51.gif" />}
/>

Theme

Switch between 2 themes: macos (default) and window by using the theme prop.

Terminal (window) | Lorem ipsum dolor, sit amet consectetur adipisicing elit. Excepturi eum ab deleniti, non praesentium aliquid voluptas eos illo corrupti corporis minus

This is window theme

<Terminal theme="window" />

Hide window controls

You can also hide the window controls by setting hideWindowCtrls to true.

Styling Elements

classNames and styles are 2 more available options for styling the Terminal component.
See TerminalStylingSelectors in the Special Types section below for available selectors.

Terminal Title ✨

🎨 You can use classNames prop to style <Terminal /> component like this:
<Terminal
  classNames={{
    windowHeader: '...',
    historySection: '...',
    commandForm: '...',
  }}
/>

<Terminal
  className="bg-black dark:bg-slate-600"
  classNames={{
    windowHeader:
      'bg-[radial-gradient(circle,rgba(34,193,195,0.4)_0%,rgba(253,187,45,0.2)_100%)] dark:bg-slate-700',
    commandForm: '[&>span]:text-yellow-600',
  }}
/>

Special Types

Name	Type	Description
`PrintlnFn`	`(text: string) => void`	Print the inputted string.
`PrintNodeFn`	`(node: ReactNode) => void`	Print the inputted ReactNode.
`TerminalHelpers`	`{println: PrintlnFn; printNode: PrintNodeFn; clearHistory: () => void}`	A collection of helper functions.
`TerminalRef`	`TerminalProps & TerminalHelpers`	All accepted props and helper functions.
`TerminalStylingSelectors`	`'windowHeader'` \| `'historySection'` \| `'commandForm'`	Available selectors of special styles APIs: `classNames`, `styles`.

`<Terminal>` Props

Name	Type	Default	Description
`classNames`	`Partial<Record<TerminalStylingSelectors, string>>`	—	Applies className to related selector element.
`styles`	`Partial<Record<TerminalStylingSelectors, CSSProperties>>`	—	Applies inline styles to related selector element.
`windowTitle`	`string`	—	Terminal window title.
`greeting`	`ReactNode`	—	Greating section. It will be printed on top of terminal’s history section.
`theme`	`'macos'` \| `'window'`	`'macos'`
`commandPrefix`	`string`	`'$'` (`'>'` if `theme` is `'window'`)
`commandHandler`	`(command: string, helper: TerminalHelpers) => 'skip_default' \| void`	—	Provide custom command handler. Returns `"skip_default"` if the command is manually handled and/or you wanna skip the default handler. Otherwise, commands will be executed by default handler.
`hideWindowCtrls`	`boolean`	`false`	Hide window controls.
`...htmlAttributes`	`Omit<HTMLAttributes<HTMLDivElement>, 'onClick'>`	—	Others HTML attributes. Note: `onClick` event handler is not supported.

Terminal

Import

Usage

Handle Command

Default Commands

Helpers

printNode

println

clearHistory

Customization

Title & greatings

Theme

Hide window controls

Styling Elements

Special Types

<Terminal> Props

`printNode`

`println`

`clearHistory`

`<Terminal>` Props