Themes

Switching global themes

RStudio provides support for two global themes that customize the RStudio IDE’s user interface: Modern and Sky. By default, the Modern theme is selected.

The Modern theme flattens all user interface elements with a default white background, while the Sky theme has a light blue background.

To switch between RStudio themes, from the Tools > Global Options > Appearance menu, use the RStudio theme dropdown.

Editor themes

RStudio provides support for adding custom editor themes in one of two formats: tmTheme or rstheme. The tmTheme format was first introduced for TextMate, and has since become one of the standard formats for themes. This tmTheme editor also includes a large collection of tmThemes. The rstheme format is specific to RStudio.

To switch between the Editor themes, from the Tools > Global Options > Appearance menu, use the Editor theme selector. A number of common themes are included, but users can also define and uploaded their own themes. The rsthemes R package provides a number of additional common themes for use in RStudio.

A screenshot of the Global Options > Appearance tab, so that the theme of the IDE can be changed.

Creating custom themes for RStudio

User defined themes are supported in one of two formats: tmTheme and rstheme. A tmTheme is an XML based theme description first introduced by the text editor TextMate. An rstheme is a CSS based theme format designed to work specifically with RStudio. When a tmTheme is added to RStudio, it is converted to an rstheme before it is saved locally. To create a new theme for RStudio, you can write a tmTheme and import it to RStudio, write an rstheme, or write a tmTheme and then modify the rstheme that RStudio will generate for you.

Creating a tmTheme

To create a new tmTheme from scratch you can use a tmTheme editor like this one, or write it by hand. tmTheme files are very general and may include any scope the writer wishes; however, RStudio only supports a certain set of scopes. Below, you can find a table that describes the scopes supported by RStudio and the impact they will have on your resulting theme:

Scope Description
comment Changes the color and style of comments.
constant Changes the color and style of constants like TRUE, FALSE, and numeric literals.
constant.language Changes the color and style of language constants like TRUE and FALSE. This value will override the settings in the “constant” scope for language constants, if set. Also in R Markdown files, everything surrounded in *.
constant.numeric Changes the color and style of numeric literals. This value will override the settings in the “constant” scope for numeric literals, if set. Also in R Markdown files, everything surrounded in **.
keyword Changes the color and style of keywords like function, if, else, stop, and operators.
keyword.operator Changes the color and style of operators like (, ), =, +, and -. This value will override the settings in the “keyword” scope for operators, if set.
marker-layer.active_debug_line Changes the color and style of the highlighting on the line of code which is currently being debugged.
markup.heading Changes the color and style of the characters that start a heading in R Markdown documents.
meta.tag Changes the color and style of metadata tags in R Markdown documents, like title.
string Changes the color and style of string literals.
support.function Changes the color and style of code blocks in R Markdown documents.

Creating an rstheme

While an rstheme can be written from scratch, they contain a fair amount of generated values. The most straightforward method to create one would be to write a tmTheme and import to RStudio and then modify the generated rstheme. Another straightforward method would be to copy an existing rstheme and then modify the values.

Because of the structure of the elements being styled, not all the CSS rule sets may end up being used. Below is a table that describes the most relevant selectors, which tmTheme scope they correspond to, if any, and how they impact the style of RStudio.

Selector Description
.ace_bracket Overrides default styling for matching bracket highlighting provided by Ace.
.ace_comment Changes the color and style of comments.
.ace_constant Changes the color and style of constants like TRUE, FALSE, and numeric literals.
.ace_constant.ace_language Changes the color and style of language constants like TRUE and FALSE. This rule set will override rules in .ace_constant for language constants. Also in R Markdown files, everything surrounded in *.
.ace_constant.ace_numeric Changes the color and style of numeric literals. This value will override the settings in the “constant” scope, if set. Also in R Markdown files, everything surrounded in **.
.ace_cusor Changes the color and style of the text cursor in the editor window.
.ace_editor Changes the default color and background of the RStudio editor windows. This selector will usually be the first in a list of other selectors for the same rule set, such as .rstudio-themes-flat.ace_editor_theme and so on.
.ace_gutter Changes the color and style of the gutter: the panel on the left-hand side of the editor which holds line numbers, breakpoints, and fold widgets.
.ace_gutter-active-line Changes the color and style of the gutter at the active line in the editor.
.ace_heading Changes the color and style of headings in R Markdown documents.
.ace_indent-guide Changes the color and style of the indent guide, which can be enabled or disabled through Global Options > Code > Display > Show indent guides.
.ace_invisible Changes the color and style of invisible characters, which can be enabled or disabled through Global Options > Code Display > Show whitespace characters.
.ace_keyword Changes the color and style of keywords like function, if, else, stop, and operators.
.ace_keyword.ace_operator Changes the color and style of operators like (, ), =, +, and -. This value will override the settings in the .ace_keyword block for operators, if set.
.ace_meta.ace_tag Changes the color and style of metadata tags in R Markdown documents, like title and output.
.ace_marker-layer .ace_active-debug-line Changes the color and style of the highlighting on the line of code which is currently being debugged.
.ace_marker-layer .ace_bracket Changes the color and style of the highlighting on matching brackets.
.ace_marker-layer .ace_selection Changes the color and style of the highlighting for the currently selected line or block of lines.
.ace_markup.ace_heading Changes the color and style of the characters that start a heading in R Markdown documents.
.ace_paren_color_0 to .ace_paren_color_6 Changes the color and style of the rainbow parentheses.
.ace_print-margin Changes the color and style, if applicable, of the line-width margin that can be enabled or disabled through Global Options > Code > Display > Show margin.
.ace_selection.ace_start Changes the color and style of the highlighting for the start of the currently selected block of lines.
.ace_string Changes the color and style of string literals.
.ace_support.ace_function Changes the color and style of code blocks in R Markdown documents.

In addition to these rule sets, you will also find a number of rule sets related to the Terminal pane, with selectors that include .terminal or selectors that begin with .xterm. It is possible to change these values as well, but it may be advisable to keep a back up copy of your original theme in case you don’t like any of the changes. There are also a number of classes that can be used to modify parts of RStudio unrelated to the editor. These classes are all prefixed with rstheme_, with the exception of dataGridHeader and themedPopupPanel. Any classes you find in the html of RStudio which are not prefixed with rstheme_, ace_, or explicitly listed in this article are subject to change at anytime, and so are unsafe to use in custom themes.

Since an rstheme is just CSS, anything that you can do with CSS you can do in an rstheme.

Testing changes to a theme

If you’re modifying a theme which has already been added to RStudio, you may need to restart RStudio desktop in order to make the changes take effect.

Sharing a theme

Once you’re satisfied with your theme, you can easily share it with anyone by simply sharing the tmTheme or rstheme file. You can find rstheme files in appdata/roaming/rstudio/themes on Windows and ~/.config/rstudio/themes on linux and Mac.

Themes API

For those interested in authoring packages or integrating themes programmatically, you can make use of the rstudioapi package.

Then we can query the current theme using:

rstudioapi::getThemeInfo()

which, for the Modern theme and Xcode this function would return:

$editor[1] "Xcode"$global[1] "Modern"$dark[1] TRUE

This can be used to properly customize the output from your package to match the RStudio theme selected by each user.

To add a new rstheme, use:

rstudioapi::addTheme(themePath, apply, force, globally)

which returns the name of the newly added theme. It’s parameters are described below:

Parameter Description
themePath A full or relative path or URL to the rstheme file to add.
apply Whether to immediately apply the newly added theme. Default: FALSE.
force Whether to force the add operation if a file with the same name already exists. Default: FALSE.
globally Whether to add the theme for all users (TRUE) or the current user (FALSE). Default: FALSE.

To add a new tmTheme, use:

rstudioapi::convertTheme(
  themePath, add, outputLocation, 
  apply, force, globally
)

which also returns the name of the newly added theme. It’s parameters are described in the table below:

Parameter Description
themePath A full or relative path to the tmTheme file to add.
add Whether to add the converted theme to RStudio immediately. Default: TRUE.
outputLocation A full or relative path where an additional copy of the converted theme will be saved. If this value is not set and add is set to FALSE, no file will be saved. Default: NULL.
apply Whether to immediately apply the newly added theme. Default: FALSE.
force Whether to force the add operation if a file with the same name already exists. Default: FALSE.
globally Whether to add the theme for all users (TRUE) or the current user (FALSE). Default: FALSE.

To apply a particular theme use:

rstudioapi::applyTheme(name)

where name is the name of theme returned by rstudioapi::getThemes().

To remove a custom theme use:

rstudioapi::removeTheme(name)

where name is the name of theme returned by rstudioapi::getThemes().

To list all the available editor themes, use:

rstudioapi::getThemes()

which returns a list of themes in the format id = list(name = "a theme name", isDark = TRUE). For example, some values in the list would look like:

$ambiance
ambiance$name
[1] "Ambiance"

$ambiance$isDark
[1] TRUE

$chaos
$chaos$name
[1] "Chaos"

$chaos$isDark
[1] TRUE

$chrome
$chrome$name
[1] "Chrome"

$chrome$isDark
[1] FALSE
Back to top