xterm-for-react
    TypeScript icon, indicating that this package has built-in type declarations

    1.0.4 • Public • Published

    XTerm For React

    NPM

    XTerm For React is a React wrapper made for XTerm.js to allow you to easly integrate XTerm into any React project.

    Getting Started

    Installation

    You can install XTerm For React using the following commands:

    NPM:

    npm install xterm-for-react
    

    Yarn:

    yarn add xterm-for-react
    

    Running The Examples

    • Clone this repo git clone https://github.com/robert-harbison/xterm-for-react.git.
    • Open terminal and cd to the example directory in the repo you just cloned.
    • Run npm install
    • Run npm start to start the example.

    Basic Terminal

    The main component to this library is 'XTerm'. This will create a div and use it to open a XTerm.js terminal. The base terminal won't really do anything as it is just the terminal UI.

    You can create the base terminal using:

    // Import XTerm
    import { XTerm } from 'xterm-for-react'
    
    // Render the component
    <XTerm />
    

    'XTerm' Props

    ** Some of theme types are included with XTerm.js not with xterm-for-react

    ** Any 'Prop' with a '?' is optional.

    Prop Description
    className?: string Class name to add to the terminal container.
    options?: ITerminalOptions Options to initialize the terminal with.
    addons?: Array<ITerminalAddon> An array of XTerm addons to load along with the terminal.
    onBinary?(data: string): void Adds an event listener for when a binary event fires. This is used to enable non UTF-8 conformant binary messages to be sent to the backend. Currently this is only used for a certain type of mouse reports that happen to be not UTF-8 compatible. The event value is a JS string, pass it to the underlying pty as binary data, e.g. pty.write(Buffer.from(data, 'binary')).
    onCursorMove?(): void Adds an event listener for the cursor moves.
    onData?(data: string): void Adds an event listener for when a data event fires. This happens for example when the user types or pastes into the terminal. The event value is whatever string results, in a typical setup, this should be passed on to the backing pty.
    onKey?(event: { key: string; domEvent: KeyboardEvent }): void Adds an event listener for when a key is pressed. The event value contains the string that will be sent in the data event as well as the DOM event that triggered it.
    onLineFeed?(): void Adds an event listener for when a line feed is added.
    onScroll?(newPosition: number): void Adds an event listener for when a scroll occurs. The event value is the new position of the viewport.
    onSelectionChange?(): void Adds an event listener for when a selection change occurs.
    onRender?(event: { start: number; end: number }): void Adds an event listener for when rows are rendered. The event value contains the start row and end rows of the rendered area (ranges from 0 to Terminal.rows - 1).
    onResize(event: { cols: number; rows: number }): void Adds an event listener for when the terminal is resized. The event value contains the new size.
    onTitleChange?(newTitle: string): void Adds an event listener for when an OSC 0 or OSC 2 title change occurs. The event value is the new title.
    customKeyEventHandler?(event: KeyboardEvent): boolean Attaches a custom key event handler which is run before keys are processed, giving consumers of xterm.js ultimate control as to what keys should be processed by the terminal and what keys should not.

    Calling XTerm Functions

    If we don't have a wrapper for a specific method in XTerm.js you can call any function in XTerm.js using a ref. You can look here for the functions provided by XTerm.js

    (There will soon wrapper functions for XTerm.js functions but right now you will need to use a ref.)

        import * as React from 'react'
     
        export const Terminal = () => {
            const xtermRef = React.useRef(null)
     
            React.useEffect(() => {
                // You can call any method in XTerm.js by using 'xterm xtermRef.current.terminal.[What you want to call]
                xtermRef.current.terminal.writeln("Hello, World!")
            }, [])
     
            return (
                // Create a new terminal and set it's ref.
                <XTerm ref={xtermRef} />
            )
        }

    Terminal Options

    You can pass options that you want to use to instantiate the XTerm.js 'Terminal' with as a prop tot he XTerm component. Here is a link to the terminal options documentation.

        // Import XTerm
        import { XTerm } from 'xterm-for-react'
    
        // Render the component
        <XTerm options={{ lineHeight: 3 }} />
    

    Addons

    You can use XTerm.js addons by using the addons prop. This prop is an array of addons you want to load.

    You can see an example of using addons please see this file in the example folder.

        // Import the addon
        import { SearchAddon } from 'xterm-addon-search'
    
        // Instantiate the addon
        const searchAddon = new SearchAddon()
    
        // Load the addons as a prop
        <XTerm addons={[searchAddon]} />
    

    Examples

    If you want to see a example of this in action check out the example folder in the this repo.

    Other Resources

    XTerm.js Documentation

    Issues / Feature Requests

    If you have any feature requests or have any issues please post them here.

    Contributing

    If you would like to contribute to this project in terms of code please see our contributing page.

    Versioning

    We use SemVer as our versioning standard.

    Credits

    • Thanks to everyone who made XTerm.js for enabling this project to be possible.
    • Much of the documentation about the usage and features of XTerm where taken from their documentation.
    • Thanks to create-react-library for creating a easy template for creating React libraries.
    • And of course thanks to all the React guys for making React a thing.

    License

    Distributed under the MIT License. See LICENSE for more information.

    Install

    npm i xterm-for-react

    DownloadsWeekly Downloads

    1,444

    Version

    1.0.4

    License

    MIT

    Unpacked Size

    1.41 MB

    Total Files

    8

    Last publish

    Collaborators

    • robert-harbison