React Terminal Kit

---

Overview

The React Terminal Kit package provides a terminal-like user interface for React applications. It allows you to integrate a fully functional terminal component into your React project, enabling users to interact with the application through a command-line interface.

Installation

To install the React Terminal Kit package, use npm or yarn:

npm install react-terminal-kit --save
# or
yarn add react-terminal-kit

Usage

1. Import the Terminal component into your React component.

   import React from "react";
   import Terminal, {
     TerminalCommands,
     TerminalUtils,
   } from "react-terminal-kit";

2. Add the Terminal component to your JSX, providing the necessary props.

   const commands: TerminalCommands = {
     echo: {
       description: "Print the provided text",
       callback: (utils: TerminalUtils, args: string[]) => {
         utils.displayOutput(args.join(" "));
       },
     },
   };
   
   const MyComponent = () => {
     return (
       <div style={{ width: "500px", height: "300px" }}>
         {/* Your other components */}
         <Terminal
           prefix="root"
           prompt="$"
           cursor="block"
           theme="dark"
           commands={commands}
         />
       </div>
     );
   };

Note: The Terminal component, by default, takes 100% width and height. To control the dimensions, wrap it inside a div element with a specified width and height.

This ensures that the terminal is displayed within the specified dimensions and fits seamlessly into your application layout. If you have specific layout instructions or considerations, you can further customize this section based on your needs.

Try it on CodeSandbox

Terminal Props

Property	Type	Default Value	Description
prefix	string	""	A string representing the prefix displayed before the prompt. Defaults to an empty string.
prompt	string	$	A string representing the prompt displayed at the beginning of each command line. Defaults to $.
cursor	string	'block'	A string representing the cursor type. Options include 'block', 'underline', and 'bar'. Defaults to 'block'.
theme	string	'dark'	A string representing the color theme. Options include 'light' and 'dark'. Defaults to 'dark'.
welcomeMessage	ReactNode or string	undefined	Content to be displayed at the top whenever the component is mounted. Can be a string or a ReactNode. Defaults to undefined.
commands	object	(Required)	An object where keys are command triggers and values are objects containing description and callback properties.

commands Object Properties

• description: A short description of the command.
• callback: A function to be executed when the command is entered. It receives two parameters: utils and args.

Default Commands

In addition to customizing commands using the commands prop, React Terminal Kit comes with a set of default commands that serve fundamental purposes. These default commands are included out of the box and should not be overwritten in your custom configurations.

Command	Description	Callback Function
help	List all available commands.	Displays a list of available commands in the terminal.
clear	Clear the terminal.	Clears the terminal screen.

These default commands provide essential functionalities and are designed to work seamlessly with the React Terminal Kit package. Avoid overwriting these commands to ensure proper operation of the terminal component.

---

Utility Functions

The utils parameter passed to the command callbacks contains the following utility functions:

1. displayOutput(args: DisplayOutputArgs): Displays text in the terminal output.

2. clearScreen(): Clears the terminal screen.

3. input(prompt: string, options: InputOptions): Promise<string>: Awaits user input.

4. password(prompt: string, options: PasswordOptions): Promise<string>: Awaits user input with masking (password).

5. confirm(prompt: string, options: BooleanOptions): Promise<boolean>: Awaits user choice (Yes/No).

6. select(prompt: string, options: SelectOptions): Promise<number>: Awaits user choice from a list of options and returns the index of chosen option.

7. openFullScreen(path: string): Opens a full-screen output with a specified path.

8. closeFullScreen(): Closes the currently open full-screen output.

9. startLoading(options?: LoadingProps): Promise<void>: Initiates a loading indicator with an optional text and type.

10. stopLoading(args?: StopLoadingArgs): Stops the ongoing loading indicator. The args parameter is optional and can include additional options for stopping the loading indicator.

DisplayOutputArgs | InputOptions | PasswordOptions | BooleanOptions | SelectOptions | FullScreenOutput | Text | LoadingProps | StopLoadingArgs

DisplayOutputArgs

Represents the arguments for the displayOutput function, allowing developers to customize the content and styling of a single line in the terminal window.

• Each displayOutput() call will only print 1 line to the terminal window:

  • Ensures that each call focuses on presenting a distinct piece of information.

• The array of DisplayOutputArgs is used to style different sections of a single line:

  • Allows for granular control over the appearance of each part of the displayed content.

• The dev can pass in a ReactNode as an input as well, and that will be displayed as-is on the window:

  • Provides flexibility to pass a ReactNode as content, seamlessly integrating with React components. A <Text/> component is available for this use case to match terminal styles seamlessly.

• If a normal string is passed, it'll be displayed with default styling:

  • Enables quick display of plain text without specifying additional styling options.

InputOptions

Represents the options for the input function, allowing developers to customize the behavior of the input function.

Property	Type	Default	Description
allowEmpty	boolean (optional)	true	Allow empty input. If set to true, the user can submit an empty input.
maxRetries	number (optional)	3	Maximum number of retries allowed. If set to 0, retries are infinite, and allowEmpty must be false.
retryMessage	string (optional)	NA	Message displayed on retry.
errorMessage	string (optional)	NA	Message displayed on error.
validator	(input: string) => boolean (optional)	NA	Validator function to check the validity of the input. Should return true if valid, false otherwise.

PasswordOptions

Represents the options for the password function, allowing developers to customize the behavior of the password function.

Property	Type	Default	Description
mask	boolean (optional)	true	Mask the user's input with asterisks (*) to keep it private.
Inherits from InputOptions

BooleanOptions

Represents the options for the choice function, allowing developers to customize the behavior of the choice function.

Property	Type	Default	Description
true	string	Yes	Text to display for a true confirmation.
false	string	No	Text to display for a false confirmation.
default	boolean (optional)	Not specified	Default selection

SelectOptions

Represents the options for the select function, allowing developers to customize the behavior of the select function.

Property	Type	Default	Description
options	string[]	Not specified	Array of options to choose from.
default	number (optional)	Not specified	Default selection index

LoadingProps

Represents the options for the startLoading function, allowing developers to customize the behavior of the loading indicator.

Property	Type	Default Value	Description
text	string	"Loading..."	The text to be displayed alongside the loading indicator.
type	LoadingType	"bar"	The type of loading indicator to be displayed.

LoadingType

Type	Symbols
bar	["|", "/", "-", "\"]
bubbles	["⣾", "⣽", "⣻", "⢿", "⡿", "⣟", "⣯", "⣷"]
breathe	[" () ", " ( ) ", "( )", " ( ) "]
metro	["[ ]", "[= ]", "[== ]", "[=== ]", "[ ===]", "[ ==]", "[ =]"]
modern-metro	["[▱▱▱▱▱▱▱]", "[▰▱▱▱▱▱▱]", "[▰▰▱▱▱▱▱]", "[▰▰▰▱▱▱▱]", "[▰▰▰▰▱▱▱]", "[▰▰▰▰▰▱▱]", "[▰▰▰▰▰▰▱]", "[▰▰▰▰▰▰▰]", "[▱▰▰▰▰▰▰]", "[▱▱▰▰▰▰▰]", "[▱▱▱▰▰▰▰]", "[▱▱▱▱▰▰▰]", "[▱▱▱▱▱▰▰]", "[▱▱▱▱▱▱▰]"]
vertical	["▁", "▃", "▄", "▅", "▆", "▇", "▆", "▅", "▄", "▃"]
horizontal	["▏", "▎", "▍", "▌", "▋", "▊", "▉", "▊", "▋", "▌", "▍"]
semi-circle	["◐", "◓", "◑", "◒"]
arrow	["▹▹▹▹▹", "▸▹▹▹▹", "▹▸▹▹▹", "▹▹▸▹▹", "▹▹▹▸▹", "▹▹▹▹▸"]
clock	["🕛", "🕐", "🕑", "🕒", "🕓", "🕔", "🕕", "🕖", "🕗", "🕘", "🕙", "🕚"]
bounce	["(● )", "( ● )", "( ● )", "( ● )", "( ● )", "( ●)", "( ● )", "( ● )", "( ● )", "( ● )"]
firework	["⢀", "⠠", "⠐", "⠈", "*", "*", " "]

For a more extensive collection of loading animations, you can explore the bash_loading_animations repository on GitHub.

StopLoadingArgs

Represents the options for the stopLoading function, allowing developers to customize the output after stopping the loading indicator.

Property	Type	Default Value	Description
message	string	<text> succeeded | failed	The message to be displayed after stopping the loading.
status	string	NA	The exit status of the loading indicator.

---

Available Components

FullScreenOutput

The FullScreenOutput component is designed to display full-screen content within the terminal. It provides a way to present extensive information or interactive content in a dedicated full-screen view.

FullScreenOutput Props

Property	Type	Default	Description
unmountOnExit	boolean	false	If set to true, the component will unmount when exiting full-screen.
path(required)	string	Not specified	A string representing the path or identifier for the full-screen content.
children	React.ReactNode	Not specified	The content to be displayed within the full-screen output.

Note: Ensure that you use the FullScreenOutput component directly inside the Terminal component and pass any custom components as children to it. The Terminal component will only render the FullScreenOutput component if it is a direct child.

Example:

import Terminal, { FullScreenOutput } from "react-terminal-kit";

<Terminal prefix="root" prompt="$" cursor="block" theme="dark">
  <FullScreenOutput path="example-path" unmountOnExit>
    {/* Your custom content here */}
  </FullScreenOutput>
</Terminal>;

Text

The Text component allows you to display plain text within the terminal. It is useful for rendering simple textual content with terminal styling.

Text Props

Property	Type	Default	Description
variant	OutputVariant	Not specified	The text variant, defining the styling of the text.
color	OutputColor	Not specified	The color variant, defining the color of the text.
children	React.ReactNode	Not specified	The content to be displayed within the Text component.
id	string (optional)	Not specified	The HTML id attribute for additional styling or targeting.
className	string (optional)	Not specified	Additional CSS classes to apply to the Text component.
href	string (optional)	Not specified	If provided, the Text component will render as an anchor (<a>).
style	React.CSSProperties (optional)	Not specified	Inline styles to apply to the Text component.

Example:

import Terminal, {
  Text,
  TerminalCommands,
  TerminalUtils,
} from "react-terminal-kit";

const commands: TerminalCommands = {
  echo: {
    description: "Print the provided text",
    callback: (utils: TerminalUtils, args: string[]) => {
      utils.displayOutput(<Text>{args.join(" ")}</Text>);
    },
  },
};

const MyComponent = () => {
  return (
    <div style={{ width: "500px", height: "300px" }}>
      {/* Your other components */}
      <Terminal
        prefix="root"
        prompt="$"
        cursor="block"
        theme="dark"
        commands={commands}
      />
    </div>
  );
};

Issues

If you encounter any issues or have feature requests, please open an issue on the GitHub repository:

• GitHub Issues

License

The React Terminal Kit package is released under the MIT License. See the full license text here:

• MIT License

Author

Thank you for using React Terminal Kit! This package is maintained by Siddharth Mittal.

Contact

• GitHub: sm2101
• Email: hello@webxsid.com

If you have any questions, feedback, or if you encounter issues, feel free to reach out. Your input is valuable, and we appreciate your interest in React Terminal Kit.

Happy coding!