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