fansi v0.4.0


Monthly downloads



ANSI Control Sequence Aware String Functions

Counterparts to R string manipulation functions that account for the effects of ANSI text formatting control sequences.


fansi - ANSI Control Sequence Aware String Functions

Counterparts to R string manipulation functions that account for the effects of ANSI text formatting control sequences.

Formatting Strings with Control Sequences

Many terminals will recognize special sequences of characters in strings and change display behavior as a result. For example, on my terminal the sequence "\033[42m" turns text background green:


The sequence itself is not shown, but the text display changes.

This type of sequence is called an ANSI CSI SGR control sequence. Most *nix terminals support them, and newer versions of Windows and Rstudio consoles do too. You can check whether your display supports them by running term_cap_test().

Whether the fansi functions behave as expected depends on many factors, including how your particular display handles Control Sequences. See ?fansi for details, particularly if you are getting unexpected results.

Control Sequences Require Special Handling

ANSI control characters and sequences (Control Sequences hereafter) break the relationship between byte/character position in a string and display position.

For example, in "Hello \033[42mWorld, Good\033[m Night Moon!" the space after "World," is thirteenth displayed character, but the eighteenth actual character ("\033" is a single character, the ESC). If we try to split the string after the space with substr things go wrong in several ways:

bad substring

We end up cutting up our string in the middle of "World", and worse the formatting bleeds out of our string into the prompt line. Compare to what happens when we use substr_ctl, the Control Sequence aware version of substr:

good substring


fansi provides counterparts to the following string functions:

  • substr
  • strsplit
  • strtrim
  • strwrap
  • nchar / nzchar

These are drop-in replacements that behave (almost) identically to the base counterparts, except for the Control Sequence awareness.

fansi also includes improved versions of some of those functions, such as substr2_ctl which allows for width based substrings. There are also utility functions such as strip_ctl to remove Control Sequences and has_ctl to detect whether strings contain them.

Most of fansi is written in C so you should find performance of the fansi functions to be comparable to the base functions. strwrap_ctl is much faster, and strsplit_ctl is somewhat slower than the corresponding base functions.

HTML Translation

You can translate ANSI CSI SGR formatted strings into their HTML counterparts with sgr_to_html:

translate to html


It is possible to set knitr hooks such that R output that contains ANSI CSI SGR is automatically converted to the HTML formatted equivalent and displayed as intended. See the vignette for details.


This package is available on CRAN:


It has no runtime dependencies.

For the development version use: devtools::install_github('brodieg/fansi@development') or:

f.dl <- tempfile() <- tempfile()
github.url <- ''
download.file(github.url, f.dl)
install.packages(file.path(, 'fansi-development'), repos=NULL, type='source')

There is no guarantee that development versions are stable or even working (Travis build status: ). The master branch typically mirrors CRAN and should be stable.


Functions in fansi

Name Description
strip_ctl Strip ANSI Control Sequences
sgr_to_html Convert ANSI CSI SGR Escape Sequence to HTML Equivalents
fansi_lines Colorize Character Vectors
strsplit_ctl ANSI Control Sequence Aware Version of strsplit
term_cap_test Test Terminal Capabilities
unhandled_ctl Identify Unhandled ANSI Control Sequences
strtrim_ctl ANSI Control Sequence Aware Version of strtrim
strwrap_ctl ANSI Control Sequence Aware Version of strwrap
has_ctl Checks for Presence of Control Sequences
html_code_block Format Character Vector for Display as Code in HTML
html_esc Escape Characters With Special HTML Meaning
nchar_ctl ANSI Control Sequence Aware Version of nchar
substr_ctl ANSI Control Sequence Aware Version of substr
tabs_as_spaces Replace Tabs With Spaces
fansi Details About Manipulation of Strings Containing Control Sequences
set_knit_hooks Set an Output Hook to Display ANSI CSI SGR in Rmarkdown
No Results!

Vignettes of fansi

No Results!

Last month downloads


License GPL (>= 2)
LazyData true
VignetteBuilder knitr
Encoding UTF-8
Collate 'constants.R' 'fansi-package.R' 'has.R' 'internal.R' 'load.R' 'misc.R' 'nchar.R' 'strip.R' 'strwrap.R' 'strtrim.R' 'strsplit.R' 'substr2.R' 'tohtml.R' 'unhandled.R'
NeedsCompilation yes
Packaged 2018-10-04 19:06:14 UTC; bg
Repository CRAN
Date/Publication 2018-10-05 05:10:12 UTC

Include our badge in your README