README.md

Xterm.js is a front-end component written in TypeScript that lets applications bring fully-featured terminals to their users in the browser. It's used by popular projects such as VS Code, Hyper and Theia.

Features

Terminal apps just work: Xterm.js works with most terminal apps such as bash, vim and tmux, this includes support for curses-based apps and mouse event support.

Perfomant: Xterm.js is really fast, it even includes a GPU-accelerated renderer.

Rich unicode support: Supports CJK, emojis and IMEs.

Self-contained: Requires zero dependencies to work.

Accessible: Screen reader support can be turned on using the screenReaderMode option.

And much more: Links, theming, addons, well documented API, etc.

What xterm.js is not

Xterm.js is not a terminal application that you can download and use on your computer.

Xterm.js is not bash. Xterm.js can be connected to processes like bash and let you interact with them (provide input, receive output).

Getting Started

First you need to install the module, we ship exclusively through npm so you need that installed and then add xterm.js as a dependency by running:

npm install xterm

To start using xterm.js on your browser, add the xterm.js and xterm.css to the head of your html page. Then create a <div id="terminal"></div> onto which xterm can attach itself. Finally instantiate the Terminal object and then call the open function with the DOM object of the div.

Importing

The recommended way to load xterm.js is via the ES6 module syntax:

import { Terminal } from'xterm';

Addons

Addons are JavaScript modules that extend the Terminal prototype with new methods and attributes to provide additional functionality. There are a handful available in the main repository in the src/addons directory and you can even write your own by using the public API.

To use an addon, just import the JavaScript module and pass it to Terminal's applyAddon method:

You will also need to include the addon's CSS file if it has one in the folder.

Importing Addons in TypeScript

There are currently no typings for addons if they are accessed via extending Terminal prototype, so you will need to upcast if using TypeScript, eg. (xterm as any).fit(). Alternatively, you can import the addon function and enhance the terminal on demand. This has better typing support and is friendly to treeshaking.

Browser Support

Since xterm.js is typically implemented as a developer tool, only modern browsers are supported officially. Here is a list of the versions we aim to support:

Chrome latest

Edge latest

Firefox latest

Safari latest

IE11

Xterm.js works seamlessly in Electron apps and may even work on earlier versions of the browsers, these are the versions we strive to keep working.

API

The full API for xterm.js is contained within the TypeScript declaration file, use the branch/tag picker in GitHub (w) to navigate to the correct version of the API.

Note that some APIs are marked experimental, these are added to enable experimentation with new ideas without committing to support it like a normal semver API. Note that these APIs can change radically between versions so be sure to read release notes if you plan on using experimental APIs.

Real-world uses

Xterm.js is used in several world-class applications to provide great terminal experiences.

SourceLair: In-browser IDE that provides its users with fully-featured Linux terminals based on xterm.js.

Microsoft Visual Studio Code: Modern, versatile and powerful open source code editor that provides an integrated terminal based on xterm.js.

ttyd: A command-line tool for sharing terminal over the web, with fully-featured terminal emulation based on xterm.js.

Do you use xterm.js in your application as well? Please open a Pull Request to include it here. We would love to have it in our list. Note: Please add any new contributions to the end of the list only.