ANSI Escape Sequences
| Date Published: | |
| Last Modified: |
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 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 |
| 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 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 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
Fnky. ANSI Escape Sequences. Retrieved 2024-06-25, from https://gist.github.com/fnky/458719343aabd01cfb17a3a4f7296797. ↩︎
Wikipedia (2024, Jun 1). ANSI escape code. Retrieved 2024-06-26, from https://en.wikipedia.org/wiki/ANSI_escape_code. ↩︎
Authors
This work is licensed under a Creative Commons Attribution 4.0 International License .