Class GespenstTerminal

Readonlyelement

Readonlyrenderer

geometry

• get geometry(): TerminalGeometry

  Current character-grid and backing-surface geometry.

  Returns TerminalGeometry

theme

• get theme(): Readonly<TerminalTheme>

  Current authored theme. Missing values inherit from DEFAULT_THEME.

  Returns Readonly<TerminalTheme>

blur

• blur(): void

  Removes focus from the hidden terminal input.

  Returns void

clearSelection

• clearSelection(): void

  Clears the active text selection.

  Returns void

connect

• connect(
      transport: TerminalTransport,
      options?: TerminalConnectionOptions,
  ): TerminalConnection

  Connects terminal output and input to bidirectional PTY byte streams.

  Parameters

  • transport: TerminalTransport
  • options: TerminalConnectionOptions = {}

  Returns TerminalConnection

  Remarks

  Incoming chunks are awaited through GespenstTerminal.writeAsync. Outgoing input is copied into a bounded queue whose default limit is 1 MiB. Geometry is intentionally separate; subscribe to resize and forward columns and rows through the backend's control protocol.

dispose

• dispose(): void

  Releases transports, addons, fonts, workers, renderers, events, and DOM resources.

  Returns void

fit

• fit(): void

  Recalculates terminal geometry from its current container, ignoring fixed initial grid values.

  Returns void

focus

• focus(): void

  Focuses the hidden terminal input.

  Returns void

getSelection

• getSelection(): Promise<string>

  Reads selected text.

  Returns Promise<string>

loadAddon

• loadAddon(addon: TerminalAddon): void

  Activates an addon and owns it until terminal disposal.

  Parameters

  • addon: TerminalAddon

  Returns void

loadFont

• loadFont(face: TerminalFontFace): Promise<void>

  Loads a font face in the document and active rendering backend.

  Parameters

  • face: TerminalFontFace

  Returns Promise<void>

  Remarks

  Loading a face does not select it. Follow with GespenstTerminal.setFont when the terminal should use the new family.

on

• on<
      Key extends
          | "error"
          | "resize"
          | "input"
          | "bell"
          | "title"
          | "cwd"
          | "notification"
          | "progress"
          | "clipboardWrite"
          | "bufferChange"
          | "renderer"
          | "writeParsed"
          | "selectionChange"
          | "scroll"
          | "viewportChange"
          | "font",
  >(
      type: Key,
      listener: (value: BrowserTerminalEventMap[Key]) => void,
  ): Disposable

  Subscribes to a typed browser terminal event.

  Type Parameters

  • Key extends
        | "error"
        | "resize"
        | "input"
        | "bell"
        | "title"
        | "cwd"
        | "notification"
        | "progress"
        | "clipboardWrite"
        | "bufferChange"
        | "renderer"
        | "writeParsed"
        | "selectionChange"
        | "scroll"
        | "viewportChange"
        | "font"

  Parameters

  • type: Key
  • listener: (value: BrowserTerminalEventMap[Key]) => void

  Returns Disposable

open

• open(container: HTMLElement): Promise<void>

  Mounts a terminal created without a container and recalculates its layout.

  Parameters

  • container: HTMLElement

  Returns Promise<void>

paste

• paste(data: string): void

  Sends text through bracketed-paste handling when enabled.

  Parameters

  • data: string

  Returns void

pasteClipboard

• pasteClipboard(request: ClipboardPasteRequest): Promise<ClipboardPasteResult>

  Delivers a user-authorized browser clipboard snapshot to Ghostty.

  Parameters

  • request: ClipboardPasteRequest

  Returns Promise<ClipboardPasteResult>

readBuffer

• readBuffer(range?: TerminalBufferRange): Promise<TerminalBufferSnapshot>

  Reads retained active-buffer rows without reparsing terminal output.

  Parameters

  • Optionalrange: TerminalBufferRange

  Returns Promise<TerminalBufferSnapshot>

readViewport

• readViewport(): Promise<ViewportSnapshot>

  Reads a complete visible viewport snapshot.

  Returns Promise<ViewportSnapshot>

reset

• reset(): void

  Resets terminal state to initial values.

  Returns void

resize

• resize(cols?: number, rows?: number): void

  Fits to the container or applies an explicit character-grid size.

  Parameters

  • Optionalcols: number
  • Optionalrows: number

  Returns void

  Remarks

  Calling without both dimensions respects fixed cols and rows creation options. Use GespenstTerminal.fit to force container measurement.

restore

• restore(snapshot: Uint8Array): Promise<void>

  Restores terminal state from compatible snapshot bytes.

  Parameters

  • snapshot: Uint8Array

  Returns Promise<void>

scrollLines

• scrollLines(delta: number): void

  Scrolls the viewport by a signed row count.

  Parameters

  • delta: number

  Returns void

scrollToBottom

• scrollToBottom(): void

  Scrolls to the end of the buffer.

  Returns void

scrollToTop

• scrollToTop(): void

  Scrolls to the beginning of the buffer.

  Returns void

selectAll

• selectAll(): void

  Selects all terminal buffer content.

  Returns void

sendKey

• sendKey(input: KeyInput): void

  Encodes a physical keyboard input toward the PTY.

  Parameters

  • input: KeyInput

  Returns void

sendPointer

• sendPointer(input: PointerInput): void

  Encodes a pointer input or updates terminal selection.

  Parameters

  • input: PointerInput

  Returns void

sendText

• sendText(data: string): void

  Sends composed text toward the PTY.

  Parameters

  • data: string

  Returns void

setAccessibility

• setAccessibility(level: "off" | "basic" | "full"): void

  Changes the browser accessibility mirror level.

  Parameters

  • level: "off" | "basic" | "full"

  Returns void

setDefaultCursor

• setDefaultCursor(style: CursorStyle, blink: boolean): void

  Changes Ghostty's default cursor shape and blink behavior.

  Parameters

  • style: CursorStyle
  • blink: boolean

  Returns void

setFont

• setFont(options: Partial<TerminalFontOptions>): Promise<TerminalGeometry>

  Applies font values and returns recalculated terminal geometry.

  Parameters

  • options: Partial<TerminalFontOptions>

  Returns Promise<TerminalGeometry>

setMinimumContrastRatio

• setMinimumContrastRatio(ratio: number): void

  Changes the renderer's minimum contrast ratio.

  Parameters

  • ratio: number

  Returns void

setScrollbackLines

• setScrollbackLines(lines: number): void

  Changes the maximum retained scrollback lines.

  Parameters

  • lines: number

  Returns void

setTheme

• setTheme(theme: TerminalTheme): Promise<void>

  Replaces the terminal color theme.

  Parameters

  • theme: TerminalTheme

  Returns Promise<void>

snapshot

• snapshot(): Promise<Uint8Array<ArrayBufferLike>>

  Serializes terminal state into Ghostty snapshot bytes.

  Returns Promise<Uint8Array<ArrayBufferLike>>

updateTheme

• updateTheme(theme: TerminalTheme): Promise<void>

  Patches the current terminal color theme.

  Parameters

  • theme: TerminalTheme

  Returns Promise<void>

write

• write(data: string | Uint8Array<ArrayBufferLike>): void

  Queues terminal output for VT parsing without waiting for the next rendered frame.

  Parameters

  • data: string | Uint8Array<ArrayBufferLike>

  Returns void

writeAsync

• writeAsync(data: string | Uint8Array<ArrayBufferLike>): Promise<void>

  Parses and renders terminal output before resolving.

  Parameters

  • data: string | Uint8Array<ArrayBufferLike>

  Returns Promise<void>

Staticcreate

• create(options: TerminalOptions): Promise<GespenstTerminal>

  Creates and asynchronously initializes a browser terminal.

  Parameters

  • options: TerminalOptions

  Returns Promise<GespenstTerminal>

  Remarks

  The returned promise resolves after WASM, font readiness, execution context, and renderer initialization. If initialization fails, any inserted terminal root is removed.