---
title: "Themes"
date-meta: 2022-12-12
---

## 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](https://tmtheme-editor.herokuapp.com/) 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](https://www.garrickadenbuie.com/project/rsthemes/) provides a number of additional common themes for use in RStudio.

![](images/rstudio-theme.png){width="800" fig-alt="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](https://tmtheme-editor.herokuapp.com/), 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.                                                                                                                                                              |

: {tbl-colwidths="\[25,75\]"}

## 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.

:::{.column-body}

| 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_cursor                                | 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](https://cran.r-project.org/web/packages/rstudioapi/index.html) 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:
```r
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:

``` code
$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
```
