API Reference

XEventEmitter

Event emitter

Type

// Event Identifier
type IEventName = string | symbol;

// Event Listener
type IEventListener = (...args: unknown[]) => void;

type IEventHandler = (ev: IEventName, listener: IEventListener) => void;

interface IEventEmitter {
    on: IEventHandler;
    once: IEventHandler;
    off: IEventHandler;
    emit(ev: IEventName, ...args: unknown[]): void;
}

Details
Methods
on: Appends a event listener to the specified event
once: Appends a one-time event listener to the specified event
off: Removes an event listener from the specified event
emit: Triggers an event with arguments if any
See also: Guide - Events

XTerminal

Creates a terminal instance

Type

interface TerminalApi {
    // ...
}

interface TerminalOptions {
    target: HTMLElement | string;
}

class XTerminal extends XEventEmitter implements TerminalApi {
    constructor(options: TerminalOptions);
}

Details
The constructor takes one argument, options containing the target element reference.
If the target element is provided, the term.mount() method is called automatically.

Example

import XTerminal from 'xterminal';

const term = new XTerminal({/* options */});

See also: Guide - Creating a Terminal

XTerminal.version

The version number

Type

interface TerminalApi {
    readonly version: string;
}

Details
This is a static property that stores the version used. It is important when reporting bugs or issues.

Example

import XTerminal from 'xterminal';

console.log(XTerminal.version);

XTerminal.XEventEmitter

The event emitter class

Type
Same as XEventEmitter.
Details
This is a static property (class) that can be used to create independent instances

Example

Using the UMD build:

const emitter = new XTerminal.XEventEmitter();

Using ESM build (tree shakeable):

import { XEventEmitter } from 'xterminal';

const emitter = new XEventEmitter();

term.mount()

Mounts the terminal instance structure to the specified DOM element.

Type

interface TerminalApi {
    mount(target: HTMLElement | string): void;
}

Details
It takes one argument that must be an actual DOM element or a CSS selector. The element's innerHTML is cleared first and then the terminal structure is rendered.
If no argument is passed, it throws an error and nothing is rendered.
The term.mount() method should only be called once for each terminal instance only if the target element option in the constructor is not provided.

Example

import XTerminal from 'xterminal';

const term = new XTerminal();
term.mount('#app');

or mount to an actual DOM element directly:

term.mount(
    document.getElementById('app')
);

See also: Guide - Creating a Terminal

term.dispose()

Gracefully close the terminal instance.

Type

interface TerminalApi {
    dispose(): void;
}

Details
This detaches all event listeners, unmounts the terminal from the DOM and clears the backing functionality of the terminal.
The terminal should not be used again once disposed.
Example
Dispose on window unload event
js
```
window.onunload = () => term.dispose();
```
See also: Guide - Disposal

term.focus()

Focus the terminal input component - ready for input.

Type

interface TerminalApi {
    focus(): void;
}

Details
This method takes no argument. It focuses the underlying input component of the terminal.
Clicking or tapping in the terminal also invokes the method.
Example
After mounting the terminal instance
js
```
term.focus();
```

term.blur()

Blurs the terminal input component.

Type

interface TerminalApi {
    blur(): void;
}

Details
This method blurs the input component of the terminal.
Example
js
```
term.blur();
```

term.pause()

Deactivate the terminal input component.

Type

interface TerminalApi {
    pause(): void;
}

Details
This method will stop events and input from being written to the terminal but rather input will be buffered.
NB: It is used in conjuction with term.resume().
Example
Prevent a user from sending input (non-interactive mode)
js
```
term.pause();
```
See also: Guide - Pause & Resume

term.resume()

Activate the terminal input component

Type

interface TerminalApi {
    resume(): void;
}

Details
This method will enable events dispatch and user input if they were deactivate using term.pause().

Example

Pause the terminal until user input is required

term.pause();
// ...
// do something
// ...
term.resume();

See also: Guide - Pause & Resume

term.setCompleter()

Sets the autocomplete function that is invoked on Tab key.

Type

interface TerminalApi {
    setCompleter(fn: (data: string) => string): void;
}

Details
This method take one argument that is a function which takes a string parameter and returns a string.
The autocomplete functionality depends highly on the completer function fn.
The fn parameter should return a better match for the input data string.

Example

term.setCompleter(data => {
    const options = ['.help', '.clear', '.exit'];
    return options.filter(s => s.startsWith(data))[0] || '';
});

See also: Guide - Autocomplete

term.write()

Write data to the terminal.

Type

interface TerminalApi {
    write(data: string | number, callback?: () => void): void;
}

Details
data: The data to write to the terminal
callback: Optional function invoked on successful write

Example

term.write('John: Hello ');
term.write('from the Eastside', () => console.log('Done!'));

See also: Guide - Output

term.writeln()

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

Type

interface TerminalApi {
    writeln(data: string | number, callback?: () => void): void;
}

Details
data: The data to write to the terminal
callback: Optional function invoked on successful write

Example

term.writeln('Hello World!');
term.writeln('Welcome!', () => console.log('Done!'));

See also: Guide - Output

term.clear()

Clear the entire terminal.

Type

interface TerminalApi {
    clear(): void;
}

Details
When invoked, the entire terminal output is cleared.
This method also triggers the clear event.

Example

Clear on CTRL+L using keypress event

term.on('keypress', e => {
    if (e.key == 'l' && e.ctrlKey) {
        term.clear();
    }
});

See also: Guide - Example using events
See also: Guide - Output

term.clearLast()

Remove the element containing the previous output.

Type

interface TerminalApi {
    clearLast(): void;
}

Details
This is like the undo for only one write operation.

Example

Greet with Hello World and replace it with Hello Dev after 5 seconds

term.writeln('Hello World!');
setTimeout(() => {
    term.clearLast();
    term.write('Hello Dev!');
}, 5000);

See also: Guide - Output

term.history

Access the history stack.

Type

interface TerminalApi {
    history: string[];
}

Details
Manages an array of entries in the history stack.
Example
Log the history whenever a new entry is added
js
```
term.on('data', () => console.log(term.history));
```
See also: History

term.clearHistory()

Clear the entire history stack.

Type

interface TerminalApi {
    clearHistory(): void;
}

Details
It take no argument as its sole role is to clear the entire local history of inputs which are accessible iteratively using ArrowUp and ArrowDown keys.

Example

Clear history on CTRL+H using keypress event

term.on('keypress', e => {
    if (e.ctrlKey && e.key == 'h') {
        term.clearHistory();
    }
});

See also: History

API Reference ​

Application ​

Input ​

Output ​

History ​

XEventEmitter ​

XTerminal ​

XTerminal.version ​

XTerminal.XEventEmitter ​

term.mount() ​

term.dispose() ​

term.focus() ​

term.blur() ​

term.pause() ​

term.resume() ​

term.setCompleter() ​

term.write() ​

term.writeln() ​

term.clear() ​

term.clearLast() ​

term.history ​

term.clearHistory() ​

API Reference

Application

Input

Output

History

XEventEmitter

XTerminal

XTerminal.version

XTerminal.XEventEmitter

term.mount()

term.dispose()

term.focus()

term.blur()

term.pause()

term.resume()

term.setCompleter()

term.write()

term.writeln()

term.clear()

term.clearLast()

term.history

term.clearHistory()