A React wrapper made for XTerm.js
npm install xterm-for-react-18
XTerm For React is a React wrapper made for XTerm.js to allow you to easly integrate XTerm into any React project.
You can install XTerm For React using the following commands:
NPM:
``
npm install xterm-for-react-18
Yarn:
`
yarn add xterm-for-react-18
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' 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?:
| 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.)
`jsx
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.
)
}
`Terminal Options
You can pass options that you want to use to instantiate the XTerm.js 'Terminal' as props to the XTerm component. Here is a link to the terminal options documentation.
// Import XTerm
import { XTerm } from 'xterm-for-react' // Render the component
Addons
You can use XTerm.js addons by using the
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
Examples
If you want to see a example of this in action check out the
example`` folder in the this repo.If you have any feature requests or have any issues please post them here.
If you would like to contribute to this project in terms of code please see our contributing page.
We use SemVer as our versioning standard.
- 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.
Distributed under the MIT License. See LICENSE for more information.