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:374

Creates a new Terminal object.

Parameters:

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

Returns: Terminal


Properties

buffer

● buffer: IBuffer

Defined in xterm.d.ts:363

(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:356

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

Defined in xterm.d.ts:337

The element containing the terminal.


markers

● markers: ReadonlyArray<IMarker>

Defined in xterm.d.ts:369

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


onCursorMove

● onCursorMove: IEvent<void>

Defined in xterm.d.ts:387

Adds an event listener for the cursor moves.

returns: an IDisposable to stop listening.


onData

● onData: IEvent<string>

Defined in xterm.d.ts:396

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:404

Adds an event listener for 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:410

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:431

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:438

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:417

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:423

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:445

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.


rows

● rows: number

Defined in xterm.d.ts:349

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

Defined in xterm.d.ts:342

The textarea that accepts input for the terminal.


<Static> strings

● strings: ILocalizableStrings

Defined in xterm.d.ts:374

Natural language strings that can be localized.


Methods

addCsiHandler

addCsiHandler(flag: string, callback: function): IDisposable

Defined in xterm.d.ts:586

(EXPERIMENTAL) Adds a handler for CSI escape sequences.

Parameters:

Name Type Description
flag string The flag should be one-character string, which specifies the final character (e.g “m” for SGR) of the CSI sequence.
callback function The function to handle the escape sequence. The callback is called with the numerical params, as well as the special characters (e.g. “$” for DECSCPP). Return true if the sequence was handled; false if we should try a previous handler (set by addCsiHandler or setCsiHandler). The most recently-added handler is tried first.

Returns: IDisposable An IDisposable you can call to remove this handler.


addDisposableListener

addDisposableListener(type: string, handler: function): IDisposable

Defined in xterm.d.ts:545

Adds an event listener to the Terminal, returning an IDisposable that can be used to conveniently remove the event listener.

deprecated: use Terminal.onEvent(listener) instead.

Parameters:

Name Type Description
type string The type of event.
handler function The event handler.

Returns: IDisposable


addMarker

addMarker(cursorYOffset: number): IMarker

Defined in xterm.d.ts:660

(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


addOscHandler

addOscHandler(ident: number, callback: function): IDisposable

Defined in xterm.d.ts:597

(EXPERIMENTAL) Adds a handler for OSC escape sequences.

Parameters:

Name Type Description
ident number The number (first parameter) of the sequence.
callback function The function to handle the escape sequence. The callback is called with OSC data string. Return true if the sequence was handled; false if we should try a previous handler (set by addOscHandler or setOscHandler). The most recently-added handler is tried first.

Returns: IDisposable An IDisposable you can call to remove this handler.


attachCustomKeyEventHandler

attachCustomKeyEventHandler(customKeyEventHandler: function): void

Defined in xterm.d.ts:573

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:

Name Type Description
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.

Returns: void


blur

blur(): void

Defined in xterm.d.ts:450

Unfocus the terminal.

Returns: void


clear

clear(): void

Defined in xterm.d.ts:747

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

Returns: void


clearSelection

clearSelection(): void

Defined in xterm.d.ts:681

Clears the current terminal selection.

Returns: void


deregisterCharacterJoiner

deregisterCharacterJoiner(joinerId: number): void

Defined in xterm.d.ts:653

(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:615

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

Parameters:

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

Returns: void


destroy

destroy(): void

Defined in xterm.d.ts:714

Destroys the terminal and detaches it from the DOM.

deprecated: Use dispose() instead.

Returns: void


dispose

dispose(): void

Implementation of IDisposable.dispose

Defined in xterm.d.ts:707

Returns: void


emit

emit(type: string, data?: any): void

Implementation of IEventEmitter.emit

Defined in xterm.d.ts:536

Emits an event on the terminal.

deprecated: This is being removed from the API with no replacement, see issue #1505.

Parameters:

Name Type Description
type string The type of event
Optional data any data associated with the event.

Returns: void


focus

focus(): void

Defined in xterm.d.ts:455

Focus the terminal.

Returns: void


getOption

getOption(key: “bellSound” | “bellStyle” | “cursorStyle” | “fontFamily” | “fontWeight” | “fontWeightBold” | “rendererType” | “termName”): string

getOption(key: “allowTransparency” | “cancelEvents” | “convertEol” | “cursorBlink” | “debug” | “disableStdin” | “enableBold” | “macOptionIsMeta” | “rightClickSelectsWord” | “popOnBell” | “screenKeys” | “useFlowControl” | “visualBell” | “windowsMode”): boolean

getOption(key: “colors”): string[]

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

getOption(key: “handler”): function

getOption(key: string): any

Defined in xterm.d.ts:773

Retrieves an option’s value from the terminal.

Parameters:

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

Returns: string

Defined in xterm.d.ts:778

Retrieves an option’s value from the terminal.

Parameters:

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

Returns: boolean

Defined in xterm.d.ts:783

Retrieves an option’s value from the terminal.

Parameters:

Name Type Description
key “colors” The option key.

Returns: string[]

Defined in xterm.d.ts:788

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

Defined in xterm.d.ts:793

Retrieves an option’s value from the terminal.

Parameters:

Name Type Description
key “handler” The option key.

Returns: function

Defined in xterm.d.ts:798

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:671

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:676

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

Returns: ISelectionPosition | undefined


hasSelection

hasSelection(): boolean

Defined in xterm.d.ts:665

Gets whether the terminal has an active selection.

Returns: boolean


loadAddon

loadAddon(addon: ITerminalAddon): void

Defined in xterm.d.ts:892

(EXPERIMENTAL) Loads an addon into this instance of xterm.js.

Parameters:

Name Type Description
addon ITerminalAddon The addon to load.

Returns: void


off

off(type: “blur” | “focus” | “linefeed” | “selection” | “data” | “key” | “keypress” | “keydown” | “refresh” | “resize” | “scroll” | “title” | string, listener: function): void

Defined in xterm.d.ts:527

Deregisters an event listener.

deprecated: use Terminal.onEvent(listener).dispose() instead.

Parameters:

Name Type Description
type “blur” | “focus” | “linefeed” | “selection” | “data” | “key” | “keypress” | “keydown” | “refresh” | “resize” | “scroll” | “title” | string The type of the event.
listener function The listener.

Returns: void


on

on(type: “blur” | “focus” | “linefeed” | “selection”, listener: function): void

on(type: “data”, listener: function): void

on(type: “key”, listener: function): void

on(type: “keypress” | “keydown”, listener: function): void

on(type: “refresh”, listener: function): void

on(type: “resize”, listener: function): void

on(type: “scroll”, listener: function): void

on(type: “title”, listener: function): void

on(type: string, listener: function): void

Defined in xterm.d.ts:463

Registers an event listener.

deprecated: use Terminal.onEvent(listener) instead.

Parameters:

Name Type Description
type “blur” | “focus” | “linefeed” | “selection” The type of the event.
listener function The listener.

Returns: void

Defined in xterm.d.ts:470

Registers an event listener.

deprecated: use Terminal.onEvent(listener) instead.

Parameters:

Name Type Description
type “data” The type of the event.
listener function The listener.

Returns: void

Defined in xterm.d.ts:477

Registers an event listener.

deprecated: use Terminal.onEvent(listener) instead.

Parameters:

Name Type Description
type “key” The type of the event.
listener function The listener.

Returns: void

Defined in xterm.d.ts:484

Registers an event listener.

deprecated: use Terminal.onEvent(listener) instead.

Parameters:

Name Type Description
type “keypress” | “keydown” The type of the event.
listener function The listener.

Returns: void

Defined in xterm.d.ts:491

Registers an event listener.

deprecated: use Terminal.onEvent(listener) instead.

Parameters:

Name Type Description
type “refresh” The type of the event.
listener function The listener.

Returns: void

Defined in xterm.d.ts:498

Registers an event listener.

deprecated: use Terminal.onEvent(listener) instead.

Parameters:

Name Type Description
type “resize” The type of the event.
listener function The listener.

Returns: void

Defined in xterm.d.ts:505

Registers an event listener.

deprecated: use Terminal.onEvent(listener) instead.

Parameters:

Name Type Description
type “scroll” The type of the event.
listener function The listener.

Returns: void

Defined in xterm.d.ts:512

Registers an event listener.

deprecated: use Terminal.onEvent(listener) instead.

Parameters:

Name Type Description
type “title” The type of the event.
listener function The listener.

Returns: void

Defined in xterm.d.ts:519

Registers an event listener.

deprecated: use Terminal.onEvent(listener) instead.

Parameters:

Name Type Description
type string The type of the event.
listener function The listener.

Returns: void


open

open(parent: HTMLElement): void

Defined in xterm.d.ts:562

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


refresh

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

Defined in xterm.d.ts:873

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:646

(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:

Name Type Description
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.

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:609

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

Parameters:

Name Type Description
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.
Optional options ILinkMatcherOptions Options for the link matcher.

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


reset

reset(): void

Defined in xterm.d.ts:878

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

Returns: void


resize

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

Defined in xterm.d.ts:554

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:720

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:726

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:736

Scrolls the display of the terminal to the bottom.

Returns: void


scrollToLine

scrollToLine(line: number): void

Defined in xterm.d.ts:742

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:731

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:689

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:694

Selects all text within the terminal.

Returns: void


selectLines

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

Defined in xterm.d.ts:701

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”, value: string): void

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

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

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

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

setOption(key: “colors”, value: string[]): void

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

setOption(key: “handler”, value: function): void

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

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

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

Defined in xterm.d.ts:805

Sets an option on the terminal.

Parameters:

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

Returns: void

Defined in xterm.d.ts:811

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” The option value.

Returns: void

Defined in xterm.d.ts:817

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

Defined in xterm.d.ts:823

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

Defined in xterm.d.ts:829

Sets an option on the terminal.

Parameters:

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

Returns: void

Defined in xterm.d.ts:835

Sets an option on the terminal.

Parameters:

Name Type Description
key “colors” The option key.
value string[] The option value.

Returns: void

Defined in xterm.d.ts:841

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

Defined in xterm.d.ts:847

Sets an option on the terminal.

Parameters:

Name Type Description
key “handler” The option key.
value function The option value.

Returns: void

Defined in xterm.d.ts:853

Sets an option on the terminal.

Parameters:

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

Returns: void

Defined in xterm.d.ts:859

Sets an option on the terminal.

Parameters:

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

Returns: void

Defined in xterm.d.ts:865

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): void

Defined in xterm.d.ts:753

Writes text to the terminal.

Parameters:

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

Returns: void


writeUtf8

writeUtf8(data: Uint8Array): void

Defined in xterm.d.ts:767

Writes UTF8 data to the terminal. This has a slight performance advantage over the string based write method due to lesser data conversions needed on the way from the pty to xterm.js.

Parameters:

Name Type Description
data Uint8Array The data to write to the terminal.

Returns: void


writeln

writeln(data: string): void

Defined in xterm.d.ts:759

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

Parameters:

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

Returns: void


<Static> applyAddon

applyAddon(addon: any): void

Defined in xterm.d.ts:886

Applies an addon to the Terminal prototype, making it available to all newly created Terminals.

deprecated: Use the new loadAddon API/addon format.

Parameters:

Name Type Description
addon any The addon to apply.

Returns: void