react-ttyd

A React component for integrating ttyd web terminal with Xterm.js, supporting WebGL rendering and WebSocket connections.

Features

• 🚀 WebGL, Canvas, and DOM rendering support
• 🔌 WebSocket integration for ttyd connections
• 📋 Clipboard support (copy/paste)
• 🔗 Clickable links
• 🖼️ Image support in terminal
• 📱 Responsive terminal with fit addon
• ⚡ High performance with WebGL renderer
• 🎨 Customizable terminal options
• 🔒 Authentication support (basic auth and token-based)
• 🌐 Unicode support

Installation

npm install react-ttyd

or

yarn add react-ttyd

Quick Start

First, make sure you have a ttyd server running. Check ttyd for installation instructions.

# macOS
brew install ttyd

# Start ttyd
ttyd --writable bash

Then use the component in your React application:

import { Ttyd } from 'react-ttyd';

function App() {
  return (
    <Ttyd 
      wsUrl="ws://localhost:7681/ws"
      clientOptions={{
        rendererType: 'webgl'
      }}
      termOptions={{
        fontSize: 14,
      }}
    />
  );
}

With Basic Authentication

If your ttyd server requires authentication, you can provide credentials:

# Start ttyd with basic auth
ttyd --writable --credential testuser:testpw bash

<Ttyd 
  wsUrl="ws://localhost:7681/ws"
  authToken={btoa('testuser:testpw')}
  clientOptions={{
    rendererType: 'webgl'
  }}
/>

Expose the ttyd port

# Install ngrok
brew install ngrok

# Run ngrok
ngrok http 7681

API Reference

Ttyd Component Props

Prop	Type	Description	Default
wsUrl	string	WebSocket URL of ttyd server	Required
tokenUrl	string	URL to fetch auth token (if using token auth)	-
authToken	string	Base64 encoded credentials for basic auth	-
clientOptions	ClientOptions	Terminal client options	{}
termOptions	ITerminalOptions	Xterm.js terminal options	{}
onConnectionOpen	(event: Event) => void	WebSocket open callback	-
onConnectionClose	(event: CloseEvent) => void	WebSocket close callback	-
onConnectionError	(event: Event) => void	WebSocket error callback	-
onData	(data: string) => void	Terminal data callback	-
id	string	Terminal container element ID	-
className	string	Terminal container CSS class	-
addons	TerminalAddon[]	Additional Xterm.js addons	-

ClientOptions

Option	Type	Description	Default
rendererType	'webgl' | 'canvas' | 'dom'	Renderer type	'webgl'
enableZmodem	boolean	Enable Zmodem support	false
enableTrzsz	boolean	Enable trzsz support	false
enableSixel	boolean	Enable Sixel support	false
isWindows	boolean	Windows compatibility mode	Auto-detected
unicodeVersion	'6' | '11'	Unicode version	'11'

Terminal Options

The termOptions prop accepts all Xterm.js terminal options.

Common options:

<Ttyd
  wsUrl="ws://localhost:7681/ws"
  termOptions={{
    fontSize: 14,
    fontFamily: 'Menlo, Monaco, "Courier New", monospace',
    theme: {
      background: '#1e1e1e',
      foreground: '#ffffff'
    },
    cursorBlink: true,
    cursorStyle: 'block'
  }}
/>

Advanced Usage 🚧 Under Development

This section is currently under development. More advanced features and examples will be added soon!

<Ttyd 
  wsUrl="ws://localhost:7681/ws"
  authToken={btoa('testuser:testpw')}
/>

<Ttyd 
  wsUrl="ws://localhost:7681/ws"
  authToken="your-auth-token"
/>

Custom Addons

import { Terminal } from '@xterm/xterm';
import { MyCustomAddon } from './MyCustomAddon';

<Ttyd 
  wsUrl="ws://localhost:7681/ws"
  addons={[new MyCustomAddon()]}
/>

Event Handlers

<Ttyd 
  wsUrl="ws://localhost:7681/ws"
  onConnectionOpen={(event) => {
    console.log('Connected to ttyd server');
  }}
  onConnectionClose={(event) => {
    console.log('Disconnected from ttyd server');
  }}
  onConnectionError={(event) => {
    console.error('Connection error:', event);
  }}
  onData={(data) => {
    console.log('Terminal output:', data);
  }}
/>

Examples

Check out the example directory for a complete working example.

To run the example:

# Clone the repository
git clone https://github.com/tantara/react-ttyd.git
cd react-ttyd

# Install dependencies
npm install

# Build the library
npm run build

# Start ttyd server (in another terminal)
ttyd --writable bash

# Run the example
cd example/nextjs # or cd example/vite
npm install
npm run dev

Browser Support

• Chrome/Edge (recommended for WebGL support)
• Firefox
• Safari
• Mobile browsers (with touch support)

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• ttyd - Share your terminal over the web
• Xterm.js - Terminal for the web
• @homebridge/plugin-ui-utils - Inspiration for the terminal implementation

TODO

The following features from the original ttyd/html implementation are not yet ported to react-ttyd:

Core Features

• Token-based authentication (tokenUrl and refreshToken())
• Command protocol support (SET_PREFERENCES command)
• URL query parameter parsing for options
• Flow control (pause/resume commands)
• Reconnection mechanism with overlay
• Window unload warning when terminal is active
• Title management (titleFixed option)
• closeOnDisconnect behavior

File Transfer & Advanced Features

• Zmodem support (enableZmodem option)
• Trzsz support (enableTrzsz option)
• Sixel graphics support (enableSixel option)
• Modal for file uploads
• sendFile() functionality
• Drag and drop file support

UI/UX Features

• Resize overlay (disableResizeOverlay option)
• Leave alert (disableLeaveAlert option)
• Connection status overlay
• Reconnection overlay with "Press Enter to Reconnect"
• Selection copy overlay (scissors icon)

Terminal Management

• Global window.term object with fit() method
• Dispose pattern for proper cleanup
• Binary data handling
• Proper WebSocket command protocol

Configuration

• Server-side preference updates
• Windows-specific options (isWindows)
• trzszDragInitTimeout option

Related Projects

• ttyd - The backend terminal server
• xterm.js - The terminal emulator used in this component