XTermJS is an open-source terminal emulator for web applications. It allows users to interact with a shell directly from the browser and supports features like Unicode, ANSI escape codes, and custom keybindings.
Existing Libraries and Their Limitations
There are already a couple of libraries, the most notable being xterm-for-react and react-xterm. However, these libraries have not been updated for many years and do not support hooks and components, limiting their flexibility and usability.
By building react-xtermjs, we wanted to provide an easy-to-use solution that leverages the full capabilities of XTerm.js integrating with React.
How to Use the Library
Here is an example where I load an XTerm addon using react-xtermjs useXTerm hook. XTerm.js provides many add-ons, which you can find here.
JAVASCRIPT
import { FitAddon } from '@xterm/addon-fit'
import { useEffect } from 'react'
import { useXTerm } from 'react-xtermjs'
const TerminalComponent = () => {
const { instance, ref } = useXTerm()
const fitAddon = new FitAddon()
useEffect(() => {
// Load the fit addon
instance?.loadAddon(fitAddon)
const handleResize = () => fitAddon.fit()
// Write custom message on your terminal
instance?.writeln('Welcome react-xtermjs!')
instance?.writeln('This is a simple example using an addon.')
// Handle resize event
window.addEventListener('resize', handleResize)
return () => {
window.removeEventListener('resize', handleResize)
}
}, [ref, instance])
return
}
If you prefer, you can also use the component approach. Check the example here.
Note that the useXTerm hook allows more flexibility with the underlying XTerm.js instance. However, it is more verbose than the XTerm component. You can choose whichever option fits your needs.
Agents ship fast. Guardrails keep them safe.
Qovery ensures every agent action is scoped, audited, and policy-checked. Start deploying in under 10 minutes.
At Qovery, we built a Kubernetes management platform. We needed a terminal in our Web Console (UI) to allow users to connect directly to their running applications via a shell.
@xterm/addon-attach is for the web socket, which is necessary for communication between our Shell API and our web console.
All the code is available in our open-source repository. You can view the implementation here.
Voilà
The goal of react-xtermjs is to simplify adding a terminal to your React apps with an easy-to-use component and hook.
If you encounter any issues, please let us know by opening an issue on our GitHub repo.
Frequently asked questions
What is xterm.js?
An open-source terminal emulator for the browser. It renders a real terminal in a web page with support for Unicode, ANSI escape codes and custom themes, and it exposes an add-on system for things like automatic resizing, web links and search.
Why use react-xtermjs instead of xterm.js directly?
Wiring xterm.js into React means managing the terminal instance, the DOM container and the add-on lifecycle across renders by hand. react-xtermjs wraps that in an XTerm component and a useXTerm hook so the instance is created, attached and disposed with the component.
How do you load an xterm.js add-on in React?
Instantiate the add-on and pass it through the hook or component, then call the terminal's loadAddon. With the useXTerm hook you get the terminal instance back from the hook, so add-ons such as FitAddon are attached in the same effect that owns the instance rather than in a separate lifecycle.
Can you connect a browser terminal to a running container?
Yes. The terminal itself only renders input and output; the connection is a WebSocket to a process on the other end. Qovery uses exactly this pattern to give users a shell into running applications from the web console.
How do you install react-xtermjs?
It is published on npm as react-xtermjs and installs alongside xterm.js as a peer. Once installed you can either drop in the XTerm component for the common case or use the useXTerm hook when you need direct access to the terminal instance.
