As of RStudio v1.2, 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 RMarkdown 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 RMarkdown 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 RMarkdown documents.
meta.tag Changes the color and style of metadata tags in RMarkdown documents, like title.
string Changes the color and style of string literals.
support.function Changes the color and style of code blocks in RMarkdown 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 Scope Description
.ace_bracket Overrides default styling for matching bracket highlighting provided by Ace.
.ace_comment comment Changes the color and style of comments.
.ace_constant constant Changes the color and style of constants like TRUE, FALSE, and numeric literals.
.ace_constant.ace_language constant.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 RMarkdown files, everything surrounded in *.
.ace_constant.ace_numeric constant.numeric Changes the color and style of numeric literals. This value will override the settings in the “constant” scope, if set. Also in RMarkdown 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 RMarkdown 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 keyword Changes the color and style of keywords like function, if, else, stop, and operators.
.ace_keyword.ace_operator keyword.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 meta.tag Changes the color and style of metadata tags in RMarkdown documents, like title and output.
.ace_marker-layer .ace_active-debug-line marker-layer.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 markup.heading Changes the color and style of the characters that start a heading in RMarkdown 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 string Changes the color and style of string literals.
.ace_support.ace_function support.function Changes the color and style of code blocks in RMarkdown 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 C:\\Users\\<your user account>\\Documents\\.R\\rstudio\\themes on Windows and ~/.R/rstudio/themes on linux and Mac. You can also use the theme related functions provided in the RStudio API to save a local copy of your converted theme.

If you upload your rstheme file to a URL-addressable location, you can also share a snippet of code that anyone can run to try your theme:

> rstudioapi::addTheme("http://your/theme/path/theme.rstheme", apply = TRUE)

This will download, install, and apply the theme immediately on the user’s machine.