Guide · Open source
How to use xterm.js: install and add a web terminal
Updated · written with AI from the project's own documentation and checked against our catalogue data
Xterm.js is a frontend component that lets a web application show a fully featured terminal to its users in the browser. It is aimed at developers who are building an in-browser IDE, a cloud workspace or a web console and need an integrated terminal. After this guide you will know how to install it with npm, open a terminal on a page, connect it to a backend process and add optional addons.
xterm.jsxtermjs/xterm.js · ★ 21.3k · MIT Install options & downloads Quick start
- 1Install npm. xterm.js is distributed only through npm, so make sure npm is available on your machine.
- 2Add the package. Run npm install --save @xterm/xterm in your project folder.
- 3Include the stylesheet. Link css/xterm.css from the installed package in your HTML page.
- 4Open a Terminal. Create a Terminal object and call open with a DOM element.
- 5Connect a backend. Wire term.onData and pty.onData to a pseudoterminal such as node-pty so a real process drives the terminal.
- 6Add addons if needed. Install an addon such as @xterm/addon-web-links and load it with terminal.loadAddon.
What xterm.js is and is not
Xterm.js handles the display of terminal output and keyboard input inside a web page. It does not run commands by itself. The README is explicit that xterm.js is not a terminal application you can download and use on your computer, and that it is not bash.
To get a working shell, xterm.js has to be connected to a process such as bash through a pseudoterminal library like node-pty. The README notes that xterm.js works with most terminal apps such as bash, vim and tmux, including curses-based apps and mouse events.
Install xterm.js with npm
xterm.js ships exclusively through npm, so you need npm installed first. Then add the @xterm/xterm package to your project as a dependency.
- Both CommonJS and ES module files are included in the npm package.
- The README recommends loading it with ES module syntax, either with TypeScript or with modern JavaScript tooling.
- The package also publishes a beta build from the master branch, installed with the @beta tag. The README says it can contain bugs or breaking changes.
npm install --save @xterm/xtermOpen a terminal on a web page
Import Terminal, create an instance, open it on a DOM element and write text to it. The README example writes a coloured greeting using ANSI escape sequences.
You must also include the xterm.css file so the terminal is styled correctly.
import { Terminal } from '@xterm/xterm';
const term = new Terminal();
term.open(document.getElementById('terminal'));
term.write('Hello from \x1B[1;3;31mxterm.js\x1B[0m $ ')
<link rel="stylesheet" href="node_modules/@xterm/xterm/css/xterm.css" />Connect the terminal to a backend process
A terminal on a page is only a display until it is wired to a process. Most use cases connect input and output to a pseudoterminal API such as node-pty. Output from the process is written into the terminal, and keystrokes from the terminal are sent to the process.
- Use pty.onData to pass process output to term.write.
- Use term.onData to pass keystrokes to pty.write.
- Your backend is responsible for starting the shell. Xterm.js does not start one.
pty.onData(data => term.write(data));
term.onData(data => pty.write(data));Add addons for extra features
Addons are separate modules that extend Terminal through the xterm.js API. Install the addon, import it, create it and pass it to terminal.loadAddon. The README says this is all that is needed to get web links working.
The xterm.js team maintains addons including attach (websocket connection), fit (fits the terminal to its container), search, serialize, webgl, clipboard, image and web-links. Anyone can build an addon.
- @xterm/addon-fit: fits the terminal to the containing element.
- @xterm/addon-attach: attaches to a server process over a websocket.
- @xterm/addon-search: adds search functionality.
- @xterm/addon-webgl: renders using a canvas webgl2 context.
npm install --save @xterm/addon-web-links
import { Terminal } from '@xterm/xterm';
import { WebLinksAddon } from '@xterm/addon-web-links';
const terminal = new Terminal();
terminal.loadAddon(new WebLinksAddon());Use headless mode in Node.js
The @xterm/headless package is a stripped-down version of xterm.js that runs in Node.js without a browser. The README describes a use case where it tracks the state of a terminal whose process is running on the server, combined with the serialize addon so the state can be restored after a reconnection.
What people use it for
- Building a browser-based IDE or cloud workspace with an integrated terminal, as SourceLair does.
- Adding a web console to a server or device management tool.
- Providing the terminal panel inside an editor, as VS Code does.
- Tracking terminal state on the server with @xterm/headless so sessions can be restored after reconnection.
- Sharing a terminal over the web, as the ttyd project does.
Frequently asked questions
Is xterm.js free to use?
Yes. The repository is licensed under MIT. Check the licence file in the repository for the full terms before you ship a product.
How do I install xterm.js?
Install npm, then run npm install --save @xterm/xterm in your project. Load Terminal from '@xterm/xterm' and remember to include css/xterm.css.
Can I use xterm.js to run bash on my computer?
Not by itself. The README says xterm.js is not a terminal application and is not bash. You need a host app and a backend process, such as bash connected through node-pty, to get a working shell.
What do I need to use xterm.js?
The README lists npm as the prerequisite for installing it. Your project also needs a backend process connected through a pseudoterminal library such as node-pty for most use cases.
What are the alternatives to xterm.js?
The comparable projects listed for this item are hterm, term.js and ttyd. ttyd is a command-line tool for sharing a terminal over the web and is itself built on xterm.js.
Which browsers does xterm.js support?
The README says the officially supported browsers are the latest versions of Chrome, Edge, Firefox and Safari. It also works in Electron apps and may work on earlier browser versions.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use xterm.js if you are a developer building a browser-based IDE, cloud workspace or web console that needs a real terminal inside a web page. Pick something else if you want a terminal app to install on your computer, or if you only want to run bash or tmux directly.
Install options & downloads