---
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** themes into **RStudio**'s `.rstheme` format and
install them in your **RStudio** IDE. It also includes a set of ready-to-use
themes.

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

## Installing built-in themes

To install all built-in **RStudio** themes that come with this package:

```{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 quickly preview themes from R:

```{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 using 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 into an **RStudio** theme:

```{r}
#| eval: false

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

This function converts and installs the theme. Set `apply = TRUE` to apply it
after installation.

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

- Choose a theme `.json` 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 **RStudio**'s
  **Global Options \> Appearance \> Add** to manually add `.rstheme` files you
  have created or converted.