@term-ui/react

Build beautiful, interactive terminal applications with React. Leverage familiar React components and styling patterns to harness the power of the terminal—no more wrestling with low‑level ANSI codes.

⚠️ Alpha Status: Term UI is currently in alpha. The API is unstable and subject to change. You may encounter bugs during use.

📺 Terminal Compatibility: Some features depend on terminal capabilities and may not work in all terminal emulators. In the future, we plan to provide an easy-to-use API for detecting these features so applications can gracefully fallback when needed.

---

📖 Table of Contents

• ✨ Features

• ⚙️ Installation

• 🚀 Quick Start

• 🧩 API Reference

  • <term-view>
  • <term-text>

• 🎨 Styling

• 🖥️ Examples

• 📝 Contributing

• 📄 License

---

✨ Features

• React for the Terminal: Build terminal UIs with React components and hooks.
• React 19 Support: Compatible with the latest React version.
• Flexbox Layout: Arrange elements with display: 'flex', flexDirection, justifyContent, and alignItems.
• Styling: Inline styles support colors, borders, padding, margin, and background.
• Color Compositing: Use full RGBA color values for backgrounds, borders, and text. $1
• Built with Zig, WebAssembly & TypeScript: Zig and WebAssembly for performance, TypeScript and React for developer convenience.

---

⚙️ Installation

# npm
npm install @term-ui/react

# pnpm
pnpm add @term-ui/react

# bun
bun install @term-ui/react

# yarn
yarn add @term-ui/react

---

🚀 Quick Start

import React, { useState } from 'react';
import TermUi from '@term-ui/react';

const App = () => {
  const [count, setCount] = useState(0);
  const [borderColor, setBorderColor] = useState('gray');

  return (
    <term-view
      style={{
        width: '100%',
        height: '100%',
        display: 'flex',
        flexDirection: 'column',
        alignItems: 'center',
        justifyContent: 'center',
        padding: 2,
        gap: 1,
        borderStyle: 'rounded',
        borderColor: 'cyan',
      }}
    >
      <term-text style={{ color: 'cyan', bold: true }}>Count: {count}</term-text>

      <term-view
        style={{
          borderStyle: 'double',
          padding: 1,
          cursor: 'pointer',
          borderColor,
        }}
        onClick={() => setCount(count + 1)}
        onMouseEnter={() => setBorderColor('pink')}
        onMouseLeave={() => setBorderColor('gray')}
      >
        <term-text>Click to increment</term-text>
      </term-view>
    </term-view>
  );
};

TermUi.createRoot(<App />);

---

🧩 API Reference

<term-view>

The primary container component. Use it to build layouts and capture events.

Prop	Type
style	React.CSSProperties
onClick	(event: MouseClickEvent) => void
onMouseEnter	(event: MouseEnterEvent) => void
onMouseLeave	(event: MouseLeaveEvent) => void
onMouseMove	(event: MouseMoveEvent) => void
onMouseDown	(event: MouseDownEvent) => void
onMouseUp	(event: MouseUpEvent) => void
onScroll	(event: ScrollEvent) => void
children	ReactNode

<term-text>

Text rendering component. Supports styling props for typography.

Prop	Type
style	React.CSSProperties
children	ReactNode

---

🎨 Styling

Term UI uses inline style objects:

<term-view
  style={{
    width: 40,
    height: 5,
    display: 'flex',
    flexDirection: 'row',
    justifyContent: 'center',
    alignItems: 'center',
    borderStyle: 'rounded',
    borderColor: 'cyan',
    backgroundColor: 'rgba(0, 0, 0, 0.5)',
    color: 'white',
    padding: 1,
    margin: 2,
    cursor: 'pointer',
  }}
>
  <term-text style={{ fontWeight: 'bold', textDecoration: 'underline' }}>Hello, Terminal!</term-text>
</term-view>

Supported style properties:

Property	Accepted Values
display	'flex', 'block', 'inline-block', 'inline-flex', 'none', 'inline'
position	'relative', 'absolute'
width, height	Numbers, percentages (e.g., '50%'), 'auto'
minWidth, minHeight	Numbers, percentages (e.g., '50%'), 'auto'
maxWidth, maxHeight	Numbers, percentages (e.g., '50%'), 'auto'
top, right, bottom, left	Numbers, percentages (e.g., '50%'), 'auto'
margin, marginTop, marginRight, marginBottom, marginLeft	Numbers, percentages, 'auto'
padding, paddingTop, paddingRight, paddingBottom, paddingLeft	Numbers, percentages
overflow, overflowX, overflowY	'visible', 'hidden', 'clip', 'scroll'
flexDirection	'row', 'column', 'row-reverse', 'column-reverse'
flexWrap	'no-wrap', 'wrap', 'wrap-reverse'
flexBasis	Numbers, percentages, 'auto'
flexGrow, flexShrink	Numbers
alignItems, alignSelf, justifyItems, justifySelf	'start', 'end', 'flex-start', 'flex-end', 'center', 'baseline', 'stretch'
alignContent, justifyContent	'start', 'end', 'flex-start', 'flex-end', 'center', 'stretch', 'space-between', 'space-around', 'space-evenly'
gap	Numbers, percentages
textAlign	'start', 'end', 'left', 'right', 'center', 'inherit'
textWrap	'wrap', 'nowrap', 'inherit'
fontWeight	'normal', 'bold', 'dim', 'inherit'
fontStyle	'normal', 'italic', 'inherit'
textDecoration	'none', 'underline', 'double', 'dashed', 'line-through', 'wavy', 'inherit'
color	Named colors (all CSS colors supported), hex values ('#ff0000'), RGB/RGBA values
backgroundColor, borderColor	Named colors (all CSS colors supported), hex values ('#ff0000'), RGB/RGBA values, 'linear-gradient(...)', 'radial-gradient(...)'
borderStyle	'none', 'solid', 'heavy', 'double', 'rounded', 'dashed'/'dashed-double', 'dashed-double-heavy', 'dashed-wide', 'dashed-wide-heavy', 'dashed-triple', 'dashed-triple-heavy', 'dashed-quadruple', 'dashed-quadruple-heavy'
cursor	'alias', 'cell', 'copy', 'crosshair', 'default', 'e-resize', 'ew-resize', 'grab', 'grabbing', 'help', 'move', 'n-resize', 'ne-resize', 'nesw-resize', 'no-drop', 'not-allowed', 'ns-resize', 'nw-resize', 'nwse-resize', 'pointer', 'progress', 's-resize', 'se-resize', 'sw-resize', 'text', 'vertical-text', 'w-resize', 'wait', 'zoom-in', 'zoom-out'

Color Support:

• Named colors: Supports all CSS named colors including 'white', 'black', 'red', 'green', 'blue', 'cyan', 'magenta', 'yellow', etc.
• Hex: '#ff0000', '#f00'
• RGB/RGBA: 'rgb(255, 0, 0)', 'rgba(255, 0, 0, 0.5)'
• Gradients: 'linear-gradient(to right, red, blue)', 'radial-gradient(circle, yellow, green)'

Size Units:

• Numbers are interpreted as character cells: width: 10 (10 characters wide)
• 'px' units are supported but treated as equivalent to 1 character cell (e.g., width: '20px' is the same as width: 20)

---

Examples

Check out the examples directory for more complex examples and use cases.

🗺️ Roadmap

Here are some features and improvements we're planning for future releases:

• Element Focus Management: Keyboard navigation and focus control between elements
• Form Inputs: Native form components like text inputs, checkboxes, and select menus
• Built-in State Selectors: CSS-like :hover and :active state selectors for styling without JavaScript state tracking
• Advanced Styling System: Class-based styling with CSS selectors for targeting children and siblings, with improved style cascading.
• DevTools: Developer tools for inspecting and debugging terminal UI applications
• Build Tools: Optimized build configurations for terminal applications
• Hot Reloading: Support for hot module replacement during development

---

📄 License

Released under the MIT License. See LICENSE for details.