13 KiB
ansi-escape-sequences
A simple library containing all known terminal ansi escape codes and sequences. Useful for adding colour to your command-line output, or building a dynamic text user interface.
API Reference
Example
const ansi = require('ansi-escape-sequences')
- ansi-escape-sequences
- .cursor
- .hide
- .show
- .up([lines]) ⇒
string - .down([lines]) ⇒
string - .forward([lines]) ⇒
string - .back([lines]) ⇒
string - .nextLine([lines]) ⇒
string - .previousLine([lines]) ⇒
string - .horizontalAbsolute(n) ⇒
string - .position(n, m) ⇒
string
- .erase
- .display(n) ⇒
string - .inLine(n) ⇒
string
- .display(n) ⇒
- .style :
enum - .styles(effectArray) ⇒
string - .format(str, [styleArray]) ⇒
string
- .cursor
ansi.cursor
cursor-related sequences
Kind: static property of ansi-escape-sequences
- .cursor
- .hide
- .show
- .up([lines]) ⇒
string - .down([lines]) ⇒
string - .forward([lines]) ⇒
string - .back([lines]) ⇒
string - .nextLine([lines]) ⇒
string - .previousLine([lines]) ⇒
string - .horizontalAbsolute(n) ⇒
string - .position(n, m) ⇒
string
cursor.hide
Hides the cursor
Kind: static property of cursor
cursor.show
Shows the cursor
Kind: static property of cursor
cursor.up([lines]) ⇒ string
Moves the cursor lines cells up. If the cursor is already at the edge of the screen, this has no effect
Kind: static method of cursor
| Param | Type | Default |
|---|---|---|
| [lines] | number |
1 |
cursor.down([lines]) ⇒ string
Moves the cursor lines cells down. If the cursor is already at the edge of the screen, this has no effect
Kind: static method of cursor
| Param | Type | Default |
|---|---|---|
| [lines] | number |
1 |
cursor.forward([lines]) ⇒ string
Moves the cursor lines cells forward. If the cursor is already at the edge of the screen, this has no effect
Kind: static method of cursor
| Param | Type | Default |
|---|---|---|
| [lines] | number |
1 |
cursor.back([lines]) ⇒ string
Moves the cursor lines cells back. If the cursor is already at the edge of the screen, this has no effect
Kind: static method of cursor
| Param | Type | Default |
|---|---|---|
| [lines] | number |
1 |
cursor.nextLine([lines]) ⇒ string
Moves cursor to beginning of the line n lines down.
Kind: static method of cursor
| Param | Type | Default |
|---|---|---|
| [lines] | number |
1 |
cursor.previousLine([lines]) ⇒ string
Moves cursor to beginning of the line n lines up.
Kind: static method of cursor
| Param | Type | Default |
|---|---|---|
| [lines] | number |
1 |
cursor.horizontalAbsolute(n) ⇒ string
Moves the cursor to column n.
Kind: static method of cursor
| Param | Type | Description |
|---|---|---|
| n | number |
column number |
cursor.position(n, m) ⇒ string
Moves the cursor to row n, column m. The values are 1-based, and default to 1 (top left corner) if omitted.
Kind: static method of cursor
| Param | Type | Description |
|---|---|---|
| n | number |
row number |
| m | number |
column number |
ansi.erase
erase sequences
Kind: static property of ansi-escape-sequences
- .erase
- .display(n) ⇒
string - .inLine(n) ⇒
string
- .display(n) ⇒
erase.display(n) ⇒ string
Clears part of the screen. If n is 0 (or missing), clear from cursor to end of screen. If n is 1, clear from cursor to beginning of the screen. If n is 2, clear entire screen.
Kind: static method of erase
| Param | Type |
|---|---|
| n | number |
erase.inLine(n) ⇒ string
Erases part of the line. If n is zero (or missing), clear from cursor to the end of the line. If n is one, clear from cursor to beginning of the line. If n is two, clear entire line. Cursor position does not change.
Kind: static method of erase
| Param | Type |
|---|---|
| n | number |
ansi.style : enum
Various formatting styles (aka Select Graphic Rendition codes).
Kind: static enum of ansi-escape-sequences
Properties
| Name | Type | Default |
|---|---|---|
| reset | string |
"\u001b[0m" |
| bold | string |
"\u001b[1m" |
| italic | string |
"\u001b[3m" |
| underline | string |
"\u001b[4m" |
| fontDefault | string |
"\u001b[10m" |
| font2 | string |
"\u001b[11m" |
| font3 | string |
"\u001b[12m" |
| font4 | string |
"\u001b[13m" |
| font5 | string |
"\u001b[14m" |
| font6 | string |
"\u001b[15m" |
| imageNegative | string |
"\u001b[7m" |
| imagePositive | string |
"\u001b[27m" |
| black | string |
"\u001b[30m" |
| red | string |
"\u001b[31m" |
| green | string |
"\u001b[32m" |
| yellow | string |
"\u001b[33m" |
| blue | string |
"\u001b[34m" |
| magenta | string |
"\u001b[35m" |
| cyan | string |
"\u001b[36m" |
| white | string |
"\u001b[37m" |
| grey | string |
"\u001b[90m" |
| gray | string |
"\u001b[90m" |
| "bg-black" | string |
"\u001b[40m" |
| "bg-red" | string |
"\u001b[41m" |
| "bg-green" | string |
"\u001b[42m" |
| "bg-yellow" | string |
"\u001b[43m" |
| "bg-blue" | string |
"\u001b[44m" |
| "bg-magenta" | string |
"\u001b[45m" |
| "bg-cyan" | string |
"\u001b[46m" |
| "bg-white" | string |
"\u001b[47m" |
| "bg-grey" | string |
"\u001b[100m" |
| "bg-gray" | string |
"\u001b[100m" |
Example
console.log(ansi.style.red + 'this is red' + ansi.style.reset)
ansi.styles(effectArray) ⇒ string
Returns an ansi sequence setting one or more effects
Kind: static method of ansi-escape-sequences
| Param | Type | Description |
|---|---|---|
| effectArray | string | Array.<string> |
a style, or list or styles |
Example
> ansi.styles('green')
'\u001b[32m'
> ansi.styles([ 'green', 'underline' ])
'\u001b[32;4m'
ansi.format(str, [styleArray]) ⇒ string
A convenience function, applying the provided styles to the input string and then resetting.
Inline styling can be applied using the syntax [style-list]{text to format}, where style-list is a space-separated list of styles from ansi.style. For example [bold white bg-red]{bold white text on a red background}.
Kind: static method of ansi-escape-sequences
| Param | Type | Description |
|---|---|---|
| str | string |
the string to format |
| [styleArray] | Array.<string> |
a list of styles to add to the input string |
Example
> ansi.format('what?', 'green')
'\u001b[32mwhat?\u001b[0m'
> ansi.format('what?', ['green', 'bold'])
'\u001b[32;1mwhat?\u001b[0m'
> ansi.format('[green bold]{what?}')
'\u001b[32;1mwhat?\u001b[0m'
Load anywhere
This library is compatible with Node.js, the Web and any style of module loader. It can be loaded anywhere, natively without transpilation.
Node.js:
const ansi = require('ansi-escape-sequences')
Within Node.js with ECMAScript Module support enabled:
import ansi from 'ansi-escape-sequences'
Within a modern browser ECMAScript Module:
import ansi from './node_modules/ansi-escape-sequences/dist/index.mjs'
Old browser (adds window.ansi):
<script nomodule src="./node_modules/ansi-escape-sequences/dist/index.js"></script>
© 2014-19 Lloyd Brookes <75pound@gmail.com>. Documented by jsdoc-to-markdown.