ANSI Escape Sequences

ANSI escape sequences (also called ANSI escape codes) are special “in-band” character sequences that are used to control the formatting, color, and other output characteristics of text in a terminal or console. They can be used to enhance the user experience of a terminal, create advanced text-based user interfaces, and are often used in command-line applications. They are also very useful in microcontroller firmware for creating sophisticated debug shells and colouring debug logs when sending serial data to a terminal program.

NinjaTerm, a web-based program for viewing serial data from microcontrollers, supports many ANSI escape codes. So do many other terminal programs, such as PuTTY and minicom.

Escape Character

ANSI escape sequences begin with the escape character, which is represented by the ASCII code 27 (decimal) or 0x1B (hexadecimal). This character is often represented in code as \x1B or \033.

This page will use the text ESC to represent the escape character. Anytime you see ESC, replace it with the actual escape character using 0x1B or equivalent in your code.

Terminal programs which support ANSI escape sequences will interpret the escape character as the start of a special command sequence, and will not print these received bytes to the screen (the values don’t correspond to any printable characters anyway).

Control Sequence Introducer (CSI)

A [ after ESC is used to introduce a control sequence. Most of the useful ANSI escape sequences (including cursor movement, text clearing and text styling) are in this CSI subset.

Cursor Movement

The CSI sequence with letters A to G can be used to move the cursor around the terminal¹:

Escape Sequence	Name	Acronym	Description
ESC[<n>A	Cursor Up	CUU	Move the cursor up n lines.
ESC[<n>B	Cursor Down	CUD	Move the cursor down n lines.
ESC[<n>C	Cursor Forward	CUF	Move the cursor right n columns.
ESC[<n>D	Cursor Back	CUB	Move the cursor left n columns.
ESC[<n>E	Cursor Next Line	CNL	Move the cursor to the beginning line, n lines down. n defaults to 1. Not ANSI.SYS.
ESC[<n>F	Cursor Previous Line	CPL	Move the cursor to the beginning line, n lines up. n defaults to 1. Not ANSI.SYS.
ESC[<n>G	Cursor Horizontal Absolute	CHA	Move the cursor to column n. Not ANSI.SYS.

These commands have no effect if the cursor is already at the edge of the terminal (as defined by the number of rows and columns of the terminal).

Erase in Display

ESC[<n>J is used to erase parts of the display. The value of n determines what parts of the display are erased. The following values of n are supported:

• 0: Erase from the cursor to the end of the screen.
• 1: Erase from the cursor to the beginning of the screen.
• 2: Erase the entire screen.
• 3: Erase the entire screen and delete all lines saved in the scrollback buffer. This was added for xterm and is supported by a number of terminal applications.

If n is omitted, it defaults to 0.

Select Graphic Rendition (SGR)

The sequence ESC[<n>m is used to set display attributes and modes. This includes text color, background color and text style.

Attributes can be chained together by separating them with a ;. For example, ESC[1;31m sets the text to bold and red.

n	Name	Description
0	Reset or normal	Reset all attributes.
1	Bold or increased intensity	Set the text to bold. Some terminals implemented this as increasing the intensity of the colour rather than making the text bold.
2	Faint or decreased intensity
3	Italic	Not widely supported. Sometimes treated as inverse.
4	Underline
30-37	Foreground color	Set the foreground (text) color. See the table below for the color codes.
38	Foreground color	Set the foreground color. The next argument is either 5;n (8-bit colour selection) or 2;r;g;b (24-bit colour selection).
39	Default foreground color	Set the foreground color to the default color.
40-47	Background color	Set the background color. See the table below for the color codes.

Colors

The table below shows the color codes that can be used². Foreground colours set the text colour, background colours set the background colour.

The background colour of the cell shows the colour (not the text colour).

FG Code	BG Code	Name	VGA
30	40	Black	0, 0, 0
31	41	Red	170, 0, 0
32	42	Green	0, 170, 0
33	43	Yellow	170, 85, 0
34	44	Blue	0, 0, 170
35	45	Magenta	170, 0, 170
36	46	Cyan	0, 170, 170
37	47	White	170, 170, 170
38	48	Extended	8-bit or 24-bit colours.
39	49	Default	Default foreground or background color.
90	100	Bright Black	85, 85, 85
91	101	Bright Red	255, 85, 85
92	102	Bright Green	85, 255, 85
93	103	Bright Yellow	255, 255, 85
94	104	Bright Blue	85, 85, 255
95	105	Bright Magenta	255, 85, 255
96	106	Bright Cyan	85, 255, 255
97	107	Bright White	255, 255, 255

For example, ESC[31m sets the text to red. ESC[31;44m sets the text to red and the background to blue. Both of these use the basic colour codes which have the widest support.

Using the 8-bit colour selection, ESC[38;5;160m sets the text to a red colour. Using the 24-bit colour selection, ESC[38;2;255;0;0m also sets the text to red (255, 0, 0).

References

Footnotes

1. Fnky. ANSI Escape Sequences. Retrieved 2024-06-25, from https://gist.github.com/fnky/458719343aabd01cfb17a3a4f7296797. ↩

2. Wikipedia (2024, Jun 1). ANSI escape code. Retrieved 2024-06-26, from https://en.wikipedia.org/wiki/ANSI_escape_code. ↩