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

``bash
npm install react-ttyd
`

or

`bash
yarn add react-ttyd
`

Quick Start

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

`bash


macOS

brew install ttyd

Start ttyd

ttyd --writable bash
`

Then use the component in your React application:

`tsx
import { Ttyd } from 'react-ttyd';

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

$3

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

`bash


Start ttyd with basic auth


ttyd --writable --credential testuser:testpw bash
`

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

$3

`bash


Install ngrok

brew install ngrok

Run ngrok

ngrok http 7681
`

API Reference

$3

| 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 | - |

$3

| 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' |

$3

The termOptions prop accepts all Xterm.js terminal options.

Common options:

`tsx
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!

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

`tsx
wsUrl="ws://localhost:7681/ws"
authToken="your-auth-token"
/>
`

$3

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

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

$3

`tsx
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:

`bash


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:

$3


- [ ] 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

$3

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

$3

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

$3

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

$3

- [ ] 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