Class: Terminal

The class that represents an xterm.js terminal.

Hierarchy

  • Terminal

Implements

Index

Constructors

Properties

Methods

Constructors

constructor

+ new Terminal(options?: ITerminalOptions): Terminal

Defined in xterm.d.ts:628

Creates a new Terminal object.

Parameters:

Name Type Description
options? ITerminalOptions An object containing a set of options.

Returns: Terminal

Properties

buffer

buffer: IBufferNamespace

Defined in xterm.d.ts:605

(EXPERIMENTAL) The terminal’s current buffer, this might be either the normal buffer or the alt buffer depending on what’s running in the terminal.


cols

cols: number

Defined in xterm.d.ts:598

The number of columns in the terminal’s viewport. Use ITerminalOptions.cols to set this in the constructor and Terminal.resize for when the terminal exists.


element

element: *HTMLElement undefined*

Defined in xterm.d.ts:579

The element containing the terminal.


markers

markers: ReadonlyArray‹IMarker

Defined in xterm.d.ts:611

(EXPERIMENTAL) Get all markers registered against the buffer. If the alt buffer is active this will always return [].


onBinary

onBinary: IEvent‹string›

Defined in xterm.d.ts:646

Adds an event listener for when a binary event fires. This is used to enable non UTF-8 conformant binary messages to be sent to the backend. Currently this is only used for a certain type of mouse reports that happen to be not UTF-8 compatible. The event value is a JS string, pass it to the underlying pty as binary data, e.g. pty.write(Buffer.from(data, 'binary')).

returns an IDisposable to stop listening.


onCursorMove

onCursorMove: IEvent‹void›

Defined in xterm.d.ts:652

Adds an event listener for the cursor moves.

returns an IDisposable to stop listening.


onData

onData: IEvent‹string›

Defined in xterm.d.ts:661

Adds an event listener for when a data event fires. This happens for example when the user types or pastes into the terminal. The event value is whatever string results, in a typical setup, this should be passed on to the backing pty.

returns an IDisposable to stop listening.


onKey

onKey: IEvent‹object›

Defined in xterm.d.ts:669

Adds an event listener for when a key is pressed. The event value contains the string that will be sent in the data event as well as the DOM event that triggered it.

returns an IDisposable to stop listening.


onLineFeed

onLineFeed: IEvent‹void›

Defined in xterm.d.ts:675

Adds an event listener for when a line feed is added.

returns an IDisposable to stop listening.


onRender

onRender: IEvent‹object›

Defined in xterm.d.ts:696

Adds an event listener for when rows are rendered. The event value contains the start row and end rows of the rendered area (ranges from 0 to Terminal.rows - 1).

returns an IDisposable to stop listening.


onResize

onResize: IEvent‹object›

Defined in xterm.d.ts:703

Adds an event listener for when the terminal is resized. The event value contains the new size.

returns an IDisposable to stop listening.


onScroll

onScroll: IEvent‹number›

Defined in xterm.d.ts:682

Adds an event listener for when a scroll occurs. The event value is the new position of the viewport.

returns an IDisposable to stop listening.


onSelectionChange

onSelectionChange: IEvent‹void›

Defined in xterm.d.ts:688

Adds an event listener for when a selection change occurs.

returns an IDisposable to stop listening.


onTitleChange

onTitleChange: IEvent‹string›

Defined in xterm.d.ts:710

Adds an event listener for when an OSC 0 or OSC 2 title change occurs. The event value is the new title.

returns an IDisposable to stop listening.


parser

parser: IParser

Defined in xterm.d.ts:617

(EXPERIMENTAL) Get the parser interface to register custom escape sequence handlers.


rows

rows: number

Defined in xterm.d.ts:591

The number of rows in the terminal’s viewport. Use ITerminalOptions.rows to set this in the constructor and Terminal.resize for when the terminal exists.


textarea

textarea: *HTMLTextAreaElement undefined*

Defined in xterm.d.ts:584

The textarea that accepts input for the terminal.


unicode

unicode: IUnicodeHandling

Defined in xterm.d.ts:623

(EXPERIMENTAL) Get the Unicode handling interface to register and switch Unicode version.


Static strings

strings: ILocalizableStrings

Defined in xterm.d.ts:628

Natural language strings that can be localized.

Methods

addMarker

addMarker(cursorYOffset: number): *IMarker undefined*

Defined in xterm.d.ts:829

deprecated use registerMarker instead.

Parameters:

Name Type
cursorYOffset number
Returns: *IMarker undefined*

attachCustomKeyEventHandler

attachCustomKeyEventHandler(customKeyEventHandler: function): void

Defined in xterm.d.ts:748

Attaches a custom key event handler which is run before keys are processed, giving consumers of xterm.js ultimate control as to what keys should be processed by the terminal and what keys should not.

Parameters:

customKeyEventHandler: function

The custom KeyboardEvent handler to attach. This is a function that takes a KeyboardEvent, allowing consumers to stop propagation and/or prevent the default action. The function returns whether the event should be processed by xterm.js.

▸ (event: KeyboardEvent): boolean

Parameters:

Name Type
event KeyboardEvent

Returns: void


blur

blur(): void

Defined in xterm.d.ts:715

Unfocus the terminal.

Returns: void


clear

clear(): void

Defined in xterm.d.ts:909

Clear the entire buffer, making the prompt line the new first line.

Returns: void


clearSelection

clearSelection(): void

Defined in xterm.d.ts:850

Clears the current terminal selection.

Returns: void


deregisterCharacterJoiner

deregisterCharacterJoiner(joinerId: number): void

Defined in xterm.d.ts:816

(EXPERIMENTAL) Deregisters the character joiner if one was registered. NOTE: character joiners are only used by the canvas renderer.

Parameters:

Name Type Description
joinerId number The character joiner’s ID (returned after register)

Returns: void


deregisterLinkMatcher

deregisterLinkMatcher(matcherId: number): void

Defined in xterm.d.ts:770

(EXPERIMENTAL) Deregisters a link matcher if it has been registered.

deprecated The link matcher API is now deprecated in favor of the link provider API, see registerLinkProvider.

Parameters:

Name Type Description
matcherId number The link matcher’s ID (returned after register)

Returns: void


dispose

dispose(): void

Implementation of IDisposable

Defined in xterm.d.ts:876

Returns: void


focus

focus(): void

Defined in xterm.d.ts:720

Focus the terminal.

Returns: void


getOption

getOption(key: “bellSound” “bellStyle” “cursorStyle” “fontFamily” “logLevel” “rendererType” “termName” “wordSeparator”): string

Defined in xterm.d.ts:949

Retrieves an option’s value from the terminal.

Parameters:

Name Type Description
key “bellSound” | “bellStyle” | “cursorStyle” | “fontFamily” | “logLevel” | “rendererType” | “termName” | “wordSeparator” The option key.

Returns: string

getOption(key: “allowTransparency” “cancelEvents” “convertEol” “cursorBlink” “disableStdin” “macOptionIsMeta” “rightClickSelectsWord” “popOnBell” “visualBell” “windowsMode”): boolean

Defined in xterm.d.ts:954

Retrieves an option’s value from the terminal.

Parameters:

Name Type Description
key “allowTransparency” | “cancelEvents” | “convertEol” | “cursorBlink” | “disableStdin” | “macOptionIsMeta” | “rightClickSelectsWord” | “popOnBell” | “visualBell” | “windowsMode” The option key.

Returns: boolean

getOption(key: “cols” “fontSize” “letterSpacing” “lineHeight” “rows” “tabStopWidth” “scrollback”): number

Defined in xterm.d.ts:959

Retrieves an option’s value from the terminal.

Parameters:

Name Type Description
key “cols” | “fontSize” | “letterSpacing” | “lineHeight” | “rows” | “tabStopWidth” | “scrollback” The option key.

Returns: number

getOption(key: “fontWeight” “fontWeightBold”): FontWeight

Defined in xterm.d.ts:964

Retrieves an option’s value from the terminal.

Parameters:

Name Type Description
key “fontWeight” | “fontWeightBold” The option key.

Returns: FontWeight

getOption(key: string): any

Defined in xterm.d.ts:969

Retrieves an option’s value from the terminal.

Parameters:

Name Type Description
key string The option key.

Returns: any


getSelection

getSelection(): string

Defined in xterm.d.ts:840

Gets the terminal’s current selection, this is useful for implementing copy behavior outside of xterm.js.

Returns: string


getSelectionPosition

getSelectionPosition(): *ISelectionPosition undefined*

Defined in xterm.d.ts:845

Gets the selection position or undefined if there is no selection.

Returns: *ISelectionPosition undefined*

hasSelection

hasSelection(): boolean

Defined in xterm.d.ts:834

Gets whether the terminal has an active selection.

Returns: boolean


loadAddon

loadAddon(addon: ITerminalAddon): void

Defined in xterm.d.ts:1049

Loads an addon into this instance of xterm.js.

Parameters:

Name Type Description
addon ITerminalAddon The addon to load.

Returns: void


open

open(parent: HTMLElement): void

Defined in xterm.d.ts:737

Opens the terminal within an element.

Parameters:

Name Type Description
parent HTMLElement The element to create the terminal within. This element must be visible (have dimensions) when open is called as several DOM- based measurements need to be performed when this function is called.

Returns: void


paste

paste(data: string): void

Defined in xterm.d.ts:943

Writes text to the terminal, performing the necessary transformations for pasted text.

Parameters:

Name Type Description
data string The text to write to the terminal.

Returns: void


refresh

refresh(start: number, end: number): void

Defined in xterm.d.ts:1038

Tells the renderer to refresh terminal content between two rows (inclusive) at the next opportunity.

Parameters:

Name Type Description
start number The row to start from (between 0 and this.rows - 1).
end number The row to end at (between start and this.rows - 1).

Returns: void


registerCharacterJoiner

registerCharacterJoiner(handler: function): number

Defined in xterm.d.ts:809

(EXPERIMENTAL) Registers a character joiner, allowing custom sequences of characters to be rendered as a single unit. This is useful in particular for rendering ligatures and graphemes, among other things.

Each registered character joiner is called with a string of text representing a portion of a line in the terminal that can be rendered as a single unit. The joiner must return a sorted array, where each entry is itself an array of length two, containing the start (inclusive) and end (exclusive) index of a substring of the input that should be rendered as a single unit. When multiple joiners are provided, the results of each are collected. If there are any overlapping substrings between them, they are combined into one larger unit that is drawn together.

All character joiners that are registered get called every time a line is rendered in the terminal, so it is essential for the handler function to run as quickly as possible to avoid slowdowns when rendering. Similarly, joiners should strive to return the smallest possible substrings to render together, since they aren’t drawn as optimally as individual characters.

NOTE: character joiners are only used by the canvas renderer.

Parameters:

handler: function

The function that determines character joins. It is called with a string of text that is eligible for joining and returns an array where each entry is an array containing the start (inclusive) and end (exclusive) indexes of ranges that should be rendered as a single unit.

▸ (text: string): [number, number][]

Parameters:

Name Type
text string

Returns: number

The ID of the new joiner, this can be used to deregister


registerLinkMatcher

registerLinkMatcher(regex: RegExp, handler: function, options?: ILinkMatcherOptions): number

Defined in xterm.d.ts:762

(EXPERIMENTAL) Registers a link matcher, allowing custom link patterns to be matched and handled.

deprecated The link matcher API is now deprecated in favor of the link provider API, see registerLinkProvider.

Parameters:

regex: RegExp

The regular expression to search for, specifically this searches the textContent of the rows. You will want to use \s to match a space ‘ ‘ character for example.

handler: function

The callback when the link is called.

▸ (event: MouseEvent, uri: string): void

Parameters:

Name Type
event MouseEvent
uri string

Optional options: ILinkMatcherOptions

Options for the link matcher.

Returns: number

The ID of the new matcher, this can be used to deregister.


registerLinkProvider

registerLinkProvider(linkProvider: ILinkProvider): IDisposable

Defined in xterm.d.ts:778

(EXPERIMENTAL) Registers a link provider, allowing a custom parser to be used to match and handle links. Multiple link providers can be used, they will be asked in the order in which they are registered.

Parameters:

Name Type Description
linkProvider ILinkProvider The link provider to use to detect links.

Returns: IDisposable


registerMarker

registerMarker(cursorYOffset: number): *IMarker undefined*

Defined in xterm.d.ts:824

(EXPERIMENTAL) Adds a marker to the normal buffer and returns it. If the alt buffer is active, undefined is returned.

Parameters:

Name Type Description
cursorYOffset number The y position offset of the marker from the cursor.
Returns: *IMarker undefined*

The new marker or undefined.


reset

reset(): void

Defined in xterm.d.ts:1043

Perform a full reset (RIS, aka ‘\x1bc’).

Returns: void


resize

resize(columns: number, rows: number): void

Defined in xterm.d.ts:729

Resizes the terminal. It’s best practice to debounce calls to resize, this will help ensure that the pty can respond to the resize event before another one occurs.

Parameters:

Name Type
columns number
rows number

Returns: void


scrollLines

scrollLines(amount: number): void

Defined in xterm.d.ts:882

Scroll the display of the terminal

Parameters:

Name Type Description
amount number The number of lines to scroll down (negative scroll up).

Returns: void


scrollPages

scrollPages(pageCount: number): void

Defined in xterm.d.ts:888

Scroll the display of the terminal by a number of pages.

Parameters:

Name Type Description
pageCount number The number of pages to scroll (negative scrolls up).

Returns: void


scrollToBottom

scrollToBottom(): void

Defined in xterm.d.ts:898

Scrolls the display of the terminal to the bottom.

Returns: void


scrollToLine

scrollToLine(line: number): void

Defined in xterm.d.ts:904

Scrolls to a line within the buffer.

Parameters:

Name Type Description
line number The 0-based line index to scroll to.

Returns: void


scrollToTop

scrollToTop(): void

Defined in xterm.d.ts:893

Scrolls the display of the terminal to the top.

Returns: void


select

select(column: number, row: number, length: number): void

Defined in xterm.d.ts:858

Selects text within the terminal.

Parameters:

Name Type Description
column number The column the selection starts at.
row number The row the selection starts at.
length number The length of the selection.

Returns: void


selectAll

selectAll(): void

Defined in xterm.d.ts:863

Selects all text within the terminal.

Returns: void


selectLines

selectLines(start: number, end: number): void

Defined in xterm.d.ts:870

Selects text in the buffer between 2 lines.

Parameters:

Name Type Description
start number The 0-based line index to select from (inclusive).
end number The 0-based line index to select to (inclusive).

Returns: void


setOption

setOption(key: “fontFamily” “termName” “bellSound” “wordSeparator”, value: string): void

Defined in xterm.d.ts:976

Sets an option on the terminal.

Parameters:

Name Type Description
key “fontFamily” | “termName” | “bellSound” | “wordSeparator” The option key.
value string The option value.

Returns: void

setOption(key: “fontWeight” “fontWeightBold”, value: null “normal” “bold” “100” “200” “300” “400” “500” “600” “700” “800” “900” number): void

Defined in xterm.d.ts:982

Sets an option on the terminal.

Parameters:

Name Type Description
key “fontWeight” | “fontWeightBold” The option key.
value null | “normal” | “bold” | “100” | “200” | “300” | “400” | “500” | “600” | “700” | “800” | “900” | number The option value.

Returns: void

setOption(key: “logLevel”, value: LogLevel): void

Defined in xterm.d.ts:988

Sets an option on the terminal.

Parameters:

Name Type Description
key “logLevel” The option key.
value LogLevel The option value.

Returns: void

setOption(key: “bellStyle”, value: null “none” “visual” “sound” “both”): void

Defined in xterm.d.ts:994

Sets an option on the terminal.

Parameters:

Name Type Description
key “bellStyle” The option key.
value null | “none” | “visual” | “sound” | “both” The option value.

Returns: void

setOption(key: “cursorStyle”, value: null “block” “underline” “bar”): void

Defined in xterm.d.ts:1000

Sets an option on the terminal.

Parameters:

Name Type Description
key “cursorStyle” The option key.
value null | “block” | “underline” | “bar” The option value.

Returns: void

setOption(key: “allowTransparency” “cancelEvents” “convertEol” “cursorBlink” “disableStdin” “macOptionIsMeta” “popOnBell” “rightClickSelectsWord” “visualBell” “windowsMode”, value: boolean): void

Defined in xterm.d.ts:1006

Sets an option on the terminal.

Parameters:

Name Type Description
key “allowTransparency” | “cancelEvents” | “convertEol” | “cursorBlink” | “disableStdin” | “macOptionIsMeta” | “popOnBell” | “rightClickSelectsWord” | “visualBell” | “windowsMode” The option key.
value boolean The option value.

Returns: void

setOption(key: “fontSize” “letterSpacing” “lineHeight” “tabStopWidth” “scrollback”, value: number): void

Defined in xterm.d.ts:1012

Sets an option on the terminal.

Parameters:

Name Type Description
key “fontSize” | “letterSpacing” | “lineHeight” | “tabStopWidth” | “scrollback” The option key.
value number The option value.

Returns: void

setOption(key: “theme”, value: ITheme): void

Defined in xterm.d.ts:1018

Sets an option on the terminal.

Parameters:

Name Type Description
key “theme” The option key.
value ITheme The option value.

Returns: void

setOption(key: “cols” “rows”, value: number): void

Defined in xterm.d.ts:1024

Sets an option on the terminal.

Parameters:

Name Type Description
key “cols” | “rows” The option key.
value number The option value.

Returns: void

setOption(key: string, value: any): void

Defined in xterm.d.ts:1030

Sets an option on the terminal.

Parameters:

Name Type Description
key string The option key.
value any The option value.

Returns: void


write

write(data: string Uint8Array, callback?: function): void

Defined in xterm.d.ts:919

Write data to the terminal.

Parameters:

data: *string Uint8Array*

The data to write to the terminal. This can either be raw bytes given as Uint8Array from the pty or a string. Raw bytes will always be treated as UTF-8 encoded, string data as UTF-16.

Optional callback: function

Optional callback that fires when the data was processed by the parser.

▸ (): void

Returns: void


writeUtf8

writeUtf8(data: Uint8Array, callback?: function): void

Defined in xterm.d.ts:937

Write UTF8 data to the terminal.

deprecated use write instead

Parameters:

data: Uint8Array

The data to write to the terminal.

Optional callback: function

Optional callback when data was processed.

▸ (): void

Returns: void


writeln

writeln(data: string Uint8Array, callback?: function): void

Defined in xterm.d.ts:929

Writes data to the terminal, followed by a break line character (\n).

Parameters:

data: *string Uint8Array*

The data to write to the terminal. This can either be raw bytes given as Uint8Array from the pty or a string. Raw bytes will always be treated as UTF-8 encoded, string data as UTF-16.

Optional callback: function

Optional callback that fires when the data was processed by the parser.

▸ (): void

Returns: void