Native Package - rahulpandita/react-term GitHub Wiki

The @next_term/native package provides a React Native terminal component backed by React Native Skia for rendering, with touch gesture recognition and hardware keyboard support.

Component Architecture

flowchart TD
  NT["NativeTerminal\n(public API)"]
  TS["TerminalSurface\n(low-level canvas)"]
  GH["GestureHandler\n(touch input)"]
  KH["KeyboardHandler\n(hardware keys)"]
  SR["SkiaRenderer\n(draw commands)"]
  BS["BufferSet + VTParser\n(`@next_term/core`)"]

  NT --> TS
  NT --> GH
  NT --> KH
  TS --> SR
  BS --> SR
  KH -->|"VT sequences"| BS
  GH -->|"scroll / select"| NT

NativeTerminal

NativeTerminal is the primary React Native component.

import { useRef } from 'react';
import { NativeTerminal, type NativeTerminalHandle } from '`@next_term/native`';

function App() {
  const ref = useRef(NativeTerminalHandle)(null);

  return (
    (NativeTerminal
      cols={80}
      rows={24}
      fontSize={14}
      onData={(data) =) pty.write(data)}
      ref={ref}
    />
  );
}

ref.current?.write('\x1b[1mHello from native!\x1b[0m\r\n');

NativeTerminalProps

Prop	Type	Description
cols	number	Terminal width in columns
rows	number	Terminal height in rows
fontSize	number	Font size in pixels
fontFamily	string	Font family
theme	Theme	Color theme
scrollback	number	Scrollback buffer size
onData	(data: string) => void	User input callback
onResize	(cols: number, rows: number) => void	Resize callback
onRenderCommands	(cmds: RenderCommand[]) => void	Raw render command hook
style	ViewStyle	React Native style

NativeTerminalHandle

ref.current?.write(data);
ref.current?.resize(cols, rows);
ref.current?.focus();
ref.current?.blur();

SkiaRenderer

SkiaRenderer produces a declarative RenderCommand[] array from the terminal grid each frame. Skia then draws these commands on the native canvas.

Render command types:

Type	Key Fields	Purpose
rect	x, y, width, height, color	Background cell rectangle
text	x, y, text, fontSize, fontFamily, bold, italic, color	Glyph
line	x, y, width, color	Underline / strikethrough

Supported attributes: ATTR_BOLD, ATTR_ITALIC, ATTR_UNDERLINE, ATTR_STRIKETHROUGH, ATTR_INVERSE.

GestureHandler

GestureHandler recognizes touch gestures and translates them into terminal actions.

Gesture	Action
Swipe up/down	Scroll viewport
Tap	Focus / place cursor
Long press	Start text selection

GestureConfig allows customizing scroll speed, selection threshold, and tap area size. GestureState enum: IDLE, SCROLLING, SELECTING.

KeyboardHandler

KeyboardHandler maps React Native keyboard events to VT escape sequences. It is pure logic with no React Native dependencies.

const kb = new KeyboardHandler();
kb.setApplicationCursorKeys(true); // DECCKM mode

const seq = kb.handleKeyPress('ArrowUp', {
  ctrl: false, alt: false, shift: false, meta: false,
});
// seq = '\x1bOA' (application cursor keys mode)

KeyModifiers: { ctrl, alt, shift, meta }.