---
title: "Get started with rstudiothemes"
description: First steps with the rstudiothemes package
vignette: >
  %\VignetteIndexEntry{Get started with rstudiothemes}
  %\VignetteEngine{quarto::html}
  %\VignetteEncoding{UTF-8}
knitr:
  opts_chunk:
    collapse: true
    comment: '#>'
---

The **rstudiothemes** package provides tools to convert **Visual Studio Code**,
**Positron** and **TextMate** theme files to **RStudio** `.rstheme` files and
install them in your **RStudio** IDE. It also includes bundled **RStudio**
themes.

```{r}
#| label: setup
library(rstudiothemes)
```

## Installing bundled themes

To install all bundled **RStudio** themes:

```{r}
#| eval: false

install_rstudiothemes()

#> ✔ Installed 36 themes
#> ℹ Use `rstudiothemes::list_rstudiothemes()` to list installed themes.
#> ℹ Use `rstudiothemes::try_rstudiothemes()` to preview installed themes.
```

This adds popular themes such as Tokyo Night, Nord, Winter is Coming and
Dracula to your **RStudio** themes directory.

To list the themes available in the package:

```{r}
list_rstudiothemes(list_installed = FALSE)
```

## Trying themes

You can preview installed themes from an R session:

```{r}
#| eval: false

try_rstudiothemes()
```

Pass a subset of styles (for example, `"dark"` or `"light"`) if needed.

## Applying a theme

After installing themes, apply one with the **RStudio** API:

```{r}
#| eval: false

rstudioapi::applyTheme("Winter is Coming Dark Blue")
```

::: {#fig-winter}
![](winteriscoming.png){alt="Winter is Coming Dark Blue theme"}

Screenshot of the Winter is Coming Dark Blue theme.
:::

Alternatively, in **RStudio**, go to **Tools \> Global Options \> Appearance \>
Add** and select the installed theme.

## Converting your own themes

You can convert a **Visual Studio Code**, **Positron** or **TextMate** theme
file to an **RStudio** `.rstheme` file:

```{r}
#| eval: false

convert_to_rstudio_theme(
  "<path/to/vscode-theme.json>",
  apply = TRUE,
  force = TRUE
)
```

This function writes the `.rstheme` file, installs it and applies it when
`apply = TRUE`.

## Workflow example: from Visual Studio Code or Positron to RStudio

- Choose a `.json` theme file from **Visual Studio Code** or **Positron**.
- Convert and install it with `convert_to_rstudio_theme()`.
- Apply it with `rstudioapi::applyTheme()` or the **RStudio** UI.

This workflow brings your preferred editor theme to **RStudio**.

## Tips and tricks

- List installed themes with `list_rstudiothemes(list_installed = TRUE)`.
- Filter themes by `"light"` or `"dark"` style.
- Use the Add Theme UI in the **RStudio** IDE
  **Global Options \> Appearance \> Add** to manually add `.rstheme` files that
  you have created or converted.