---
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 30 themes
#> ℹ Use `rstudiothemes::list_rstudiothemes()` to list installed themes
#> ℹ Use `rstudiothemes::try_rstudiothemes()` to try all installed themes
```

This will add many popular themes (e.g., Tokyo Night, Nord, Winter is Coming,
Dracula, etc.) to your RStudio themes directory.

To see themes available now:

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

## Trying themes

You can quickly preview themes directly from R:

```{r}
#| eval: false

try_rstudiothemes()
```

Pass a subset of styles (e.g., `"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="Screenshot of theme Winter is Coming Dark Blue"}

Screenshot of theme Winter is Coming Dark Blue

:::

Alternatively, go to **Tools \> Global Options \> Appearance \> Add** in RStudio
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 will convert and install the theme immediately, optionally
applying it (with `apply = TRUE`).

## Workflow example: From VS Code theme to RStudio

1.  Choose a theme `.json` from VS Code.
2.  Convert and install it with `convert_to_rstudio_theme()`.
3.  Apply it with `rstudioapi::applyTheme()` or via RStudio UI.

This workflow lets you easily bring your preferred editor theme into RStudio.

## Tips and tricks

-   **List installed themes:** `list_rstudiothemes(list_installed = TRUE)`
-   **Try specific categories:** filter themes by Light/Dark style
-   **Use the Add-Theme UI**: RStudio's **Global Options \> Appearance \> Add**
    to manually add `.rstheme` files you've created or converted.