Interface BrowserTerminal

High-level browser terminal API.

Remarks

A terminal owns its DOM, worker or main-thread backend, renderer, loaded fonts, addons, active transports, and event listeners. Release them together with BrowserTerminal.dispose.

interface BrowserTerminal {
    element: HTMLElement;
    geometry: TerminalGeometry;
    renderer: RendererInfo;
    theme: Readonly<TerminalTheme>;
    blur(): void;
    clearSelection(): void;
    connect(
        transport: TerminalTransport,
        options?: TerminalConnectionOptions,
    ): TerminalConnection;
    dispose(): void;
    fit(): void;
    focus(): void;
    getSelection(): Promise<string>;
    loadAddon(addon: TerminalAddon): void;
    loadFont(face: TerminalFontFace): Promise<void>;
    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;
    open(container: HTMLElement): Promise<void>;
    paste(data: string): void;
    readBuffer(range?: TerminalBufferRange): Promise<TerminalBufferSnapshot>;
    readViewport(): Promise<ViewportSnapshot>;
    reset(): void;
    resize(): void;
    resize(cols: number, rows: number): void;
    restore(snapshot: Uint8Array): Promise<void>;
    scrollLines(delta: number): void;
    scrollToBottom(): void;
    scrollToTop(): void;
    selectAll(): void;
    sendKey(input: KeyInput): void;
    sendPointer(input: PointerInput): void;
    sendText(data: string): void;
    setAccessibility(level: "off" | "basic" | "full"): void;
    setDefaultCursor(style: CursorStyle, blink: boolean): void;
    setFont(options: Partial<TerminalFontOptions>): Promise<TerminalGeometry>;
    setMinimumContrastRatio(ratio: number): void;
    setScrollbackLines(lines: number): void;
    setTheme(theme: TerminalTheme): Promise<void>;
    snapshot(): Promise<Uint8Array<ArrayBufferLike>>;
    updateTheme(theme: TerminalTheme): Promise<void>;
    write(data: string | Uint8Array<ArrayBufferLike>): void;
    writeAsync(data: string | Uint8Array<ArrayBufferLike>): Promise<void>;
}

Implemented by

GespenstTerminal

Properties

`Readonly`element

element: HTMLElement

Root DOM element owned by the terminal.

`Readonly`geometry

geometry: TerminalGeometry

The current grid and device-pixel backing-surface dimensions.

`Readonly`renderer

renderer: RendererInfo

Active renderer and text-shaping information.

`Readonly`theme

theme: Readonly<TerminalTheme>

Current authored theme. Missing properties inherit from DEFAULT_THEME.

Methods

blur

blur(): void
Blurs the terminal input element.

Returns void
- Defined in packages/core/src/types.ts:243

clearSelection

clearSelection(): void
Clears the active text selection.

Returns void
- Defined in packages/core/src/types.ts:263

connect

connect(
transport: TerminalTransport,
options?: TerminalConnectionOptions,
): TerminalConnection
Connects PTY byte streams with backpressure and lifecycle reporting.
Parameters
- transport: TerminalTransport
- Optionaloptions: TerminalConnectionOptions
Returns TerminalConnection

Remarks
Incoming chunks are parsed sequentially with BrowserTerminal.writeAsync. Terminal input is written to the transport without text conversion.
- Defined in packages/core/src/types.ts:305

dispose

dispose(): void
Releases workers, renderers, transports, addons, listeners, loaded fonts, and DOM resources.

Returns void
- Defined in packages/core/src/types.ts:312

fit

fit(): void
Recalculates grid geometry from the container, including when initial grid options were set.

Returns void
- Defined in packages/core/src/types.ts:253

focus

focus(): void
Focuses the terminal input element.

Returns void
- Defined in packages/core/src/types.ts:241

getSelection

getSelection(): Promise<string>
Reads the current selection as plain text.

Returns Promise<string>
- Defined in packages/core/src/types.ts:265

loadAddon

loadAddon(addon: TerminalAddon): void
Activates an addon and transfers disposal ownership to the terminal.
Parameters
- addon: TerminalAddon
Returns void
- Defined in packages/core/src/types.ts:298

loadFont

loadFont(face: TerminalFontFace): Promise<void>
Loads a font face in every rendering context used by the terminal.
Parameters
- face: TerminalFontFace
Returns Promise<void>
- Defined in packages/core/src/types.ts:282

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
- Defined in packages/core/src/types.ts:307

open

open(container: HTMLElement): Promise<void>
Mounts a terminal created without a container.
Parameters
- container: HTMLElement
Returns Promise<void>
- Defined in packages/core/src/types.ts:207

paste

paste(data: string): void
Sends text through bracketed-paste handling when enabled.
Parameters
- data: string
Returns void
- Defined in packages/core/src/types.ts:227

readBuffer

readBuffer(range?: TerminalBufferRange): Promise<TerminalBufferSnapshot>
Reads a clamped page of retained buffer rows; defaults to the visible viewport.
Parameters
- Optionalrange: TerminalBufferRange
Returns Promise<TerminalBufferSnapshot>
- Defined in packages/core/src/types.ts:280

readViewport

readViewport(): Promise<ViewportSnapshot>
Reads a complete visible viewport snapshot.

Returns Promise<ViewportSnapshot>

Remarks
This crosses the worker boundary when worker rendering is active. Avoid polling it on the output hot path.
- Defined in packages/core/src/types.ts:278

reset

reset(): void
Resets terminal state to its initial values.

Returns void
- Defined in packages/core/src/types.ts:271

resize

resize(): void
Fits the grid to the current container dimensions.

Returns void

Remarks
Call after revealing a terminal that was measured in a hidden container.
- Defined in packages/core/src/types.ts:249
resize(cols: number, rows: number): void
Sets an explicit character-grid size.
Parameters
- cols: number
- rows: number
Returns void
- Defined in packages/core/src/types.ts:251

restore

restore(snapshot: Uint8Array): Promise<void>
Restores terminal state from compatible snapshot bytes.
Parameters
- snapshot: Uint8Array
Returns Promise<void>
- Defined in packages/core/src/types.ts:269

scrollLines

scrollLines(delta: number): void
Scrolls the viewport by a signed row delta.
Parameters
- delta: number
Returns void
- Defined in packages/core/src/types.ts:255

scrollToBottom

scrollToBottom(): void
Scrolls to the end of the buffer.

Returns void
- Defined in packages/core/src/types.ts:259

scrollToTop

scrollToTop(): void
Scrolls to the beginning of the buffer.

Returns void
- Defined in packages/core/src/types.ts:257

selectAll

selectAll(): void
Selects all terminal buffer content.

Returns void
- Defined in packages/core/src/types.ts:261

sendKey

sendKey(input: KeyInput): void
Encodes a physical keyboard input toward the PTY.
Parameters
- input: KeyInput
Returns void
- Defined in packages/core/src/types.ts:221

sendPointer

sendPointer(input: PointerInput): void
Encodes a pointer input or updates selection.
Parameters
- input: PointerInput
Returns void
- Defined in packages/core/src/types.ts:223

sendText

sendText(data: string): void
Sends text input toward the PTY.
Parameters
- data: string
Returns void
- Defined in packages/core/src/types.ts:225

setAccessibility

setAccessibility(level: "off" | "basic" | "full"): void
Changes the browser accessibility mirror level.
Parameters
- level: "off" | "basic" | "full"
Returns void
- Defined in packages/core/src/types.ts:290

setDefaultCursor

setDefaultCursor(style: CursorStyle, blink: boolean): void
Changes Ghostty's default cursor shape and blink behavior.
Parameters
- style: CursorStyle
- blink: boolean
Returns void
- Defined in packages/core/src/types.ts:288

setFont

setFont(options: Partial<TerminalFontOptions>): Promise<TerminalGeometry>
Applies font options and returns the resulting geometry.
Parameters
- options: Partial<TerminalFontOptions>
Returns Promise<TerminalGeometry>
- Defined in packages/core/src/types.ts:284

setMinimumContrastRatio

setMinimumContrastRatio(ratio: number): void
Changes the renderer's minimum contrast ratio.
Parameters
- ratio: number
Returns void
- Defined in packages/core/src/types.ts:292

setScrollbackLines

setScrollbackLines(lines: number): void
Changes the maximum retained scrollback lines.
Parameters
- lines: number
Returns void
- Defined in packages/core/src/types.ts:286

setTheme

setTheme(theme: TerminalTheme): Promise<void>
Replaces the terminal theme and resolves after the resulting frame is rendered.
Parameters
- theme: TerminalTheme
Returns Promise<void>
- Defined in packages/core/src/types.ts:294

snapshot

snapshot(): Promise<Uint8Array<ArrayBufferLike>>
Serializes terminal state into Ghostty snapshot bytes.

Returns Promise<Uint8Array<ArrayBufferLike>>
- Defined in packages/core/src/types.ts:267

updateTheme

updateTheme(theme: TerminalTheme): Promise<void>
Patches the current theme and resolves after the resulting frame is rendered.
Parameters
- theme: TerminalTheme
Returns Promise<void>
- Defined in packages/core/src/types.ts:296

write

write(data: string | Uint8Array<ArrayBufferLike>): void
Queues text or bytes for VT parsing and returns immediately.
Parameters
- data: string | Uint8Array<ArrayBufferLike>
Returns void

Remarks
Prefer bytes for PTY output to avoid a decode and encode cycle.
- Defined in packages/core/src/types.ts:213

writeAsync

writeAsync(data: string | Uint8Array<ArrayBufferLike>): Promise<void>
Parses and renders text or bytes before resolving.
Parameters
- data: string | Uint8Array<ArrayBufferLike>
Returns Promise<void>

Remarks
Use this boundary for transport backpressure, ordered snapshots, and tests.
- Defined in packages/core/src/types.ts:219

Interface BrowserTerminal

Remarks

Implemented by

Index

Properties

Methods

Properties

Readonlyelement

Readonlygeometry

Readonlyrenderer

Readonlytheme

Methods

blur

Returns void

clearSelection

Returns void

connect

Parameters

Returns TerminalConnection

Remarks

dispose

Returns void

fit

Returns void

focus

Returns void

getSelection

Returns Promise<string>

loadAddon

Parameters

Returns void

loadFont

Parameters

Returns Promise<void>

on

Type Parameters

Parameters

Returns Disposable

open

Parameters

Returns Promise<void>

paste

Parameters

Returns void

readBuffer

Parameters

Returns Promise<TerminalBufferSnapshot>

readViewport

Returns Promise<ViewportSnapshot>

Remarks

reset

Returns void

resize

Returns void

Remarks

Parameters

Returns void

restore

Parameters

Returns Promise<void>

scrollLines

Parameters

Returns void

scrollToBottom

Returns void

scrollToTop

Returns void

selectAll

Returns void

sendKey

Parameters

Returns void

sendPointer

Parameters

Returns void

sendText

Parameters

Returns void

setAccessibility

Parameters

`Readonly`element

`Readonly`geometry

`Readonly`renderer

`Readonly`theme