Skip to main content

ANSI Escape Sequences

Geoffrey Hunter
mbedded.ninja Author

Overview

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

Escape SequenceNameAcronymDescription
ESC[<n>ACursor UpCUUMove the cursor up n lines.
ESC[<n>BCursor DownCUDMove the cursor down n lines.
ESC[<n>CCursor ForwardCUFMove the cursor right n columns.
ESC[<n>DCursor BackCUBMove the cursor left n columns.
ESC[<n>ECursor Next LineCNLMove the cursor to the beginning line, n lines down. n defaults to 1. Not ANSI.SYS.
ESC[<n>FCursor Previous LineCPLMove the cursor to the beginning line, n lines up. n defaults to 1. Not ANSI.SYS.
ESC[<n>GCursor Horizontal AbsoluteCHAMove 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.

nNameDescription
0Reset or normalReset all attributes.
1Bold or increased intensitySet the text to bold. Some terminals implemented this as increasing the intensity of the colour rather than making the text bold.
2Faint or decreased intensity
3ItalicNot widely supported. Sometimes treated as inverse.
4Underline
30-37Foreground colorSet the foreground (text) color. See the table below for the color codes.
38Foreground 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).

39Default foreground colorSet the foreground color to the default color.
40-47Background colorSet the background color. See the table below for the color codes.

Colors

The table below shows the color codes that can be used2. 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 CodeBG CodeNameVGA
3040Black0, 0, 0
3141Red170, 0, 0
3242Green0, 170, 0
3343Yellow170, 85, 0
3444Blue0, 0, 170
3545Magenta170, 0, 170
3646Cyan0, 170, 170
3747White170, 170, 170
3848Extended

8-bit or 24-bit colours.

3949DefaultDefault foreground or background color.
90100Bright Black85, 85, 85
91101Bright Red255, 85, 85
92102Bright Green85, 255, 85
93103Bright Yellow255, 255, 85
94104Bright Blue85, 85, 255
95105Bright Magenta255, 85, 255
96106Bright Cyan85, 255, 255
97107Bright White255, 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.