thematic

repository·main·Indexed 42 days ago

https://github.com/rstudio/thematic

Simplified, centralized theming for ggplot2, lattice, and base R graphics. It enables automatic styling of plots to match the visual context of Shiny apps, RStudio themes, and R Markdown documents.

Tokens
1.3K
Snippets
4
Records
6
Agent score
4%

What's inside thematic

  1. Override thematic defaults with plot-specific code

    main

    Because {thematic} works by setting new global defaults, you can always override them using standard plot-specific theming code (e.g., ggplot2::theme()).

    To use a complete {ggplot2} theme (like theme_bw() or theme_minimal()) while preserving {thematic}'s semantic color adjustments, use theme_set() to set the theme globally before plotting.

    # Override a specific plot
    ggp + theme(text = element_text(colour = "purple"))
    
    # Set a complete theme globally to preserve semantic styling
    theme_set(theme_bw())
    ggp
  2. Install thematic

    main

    Install the stable release of {thematic} from CRAN using install.packages("thematic").

    Depending on your use case, you may need additional packages:

    • Shiny auto-theming: Requires {shiny} 1.5.0 or higher.
    • R Markdown auto-theming: Requires {rmarkdown} 2.7 or higher.
    • Custom/Auto fonts: For best results with custom fonts, install {showtext} and/or {ragg}.
    install.packages("thematic")
    # Optional dependencies
    install.packages("shiny")
    install.packages("rmarkdown")
    install.packages("showtext")
    install.packages("ragg")
  3. Enable auto-theming in Shiny apps

    main

    To enable {thematic} for every plotOutput() inside a Shiny app, call thematic_shiny() before launching the app.

    By default, thematic_shiny() uses the app's CSS colors to inform R plotting defaults. If your app uses Google Fonts and you have {showtext} or {ragg} installed, you can pass font = "auto" to thematic_shiny() to translate CSS fonts to R fonts.

    Note: If you want {ragg} to handle font rendering in Shiny, set options(shiny.useragg = TRUE).

    library(shiny)
    library(ggplot2)
    library(thematic)
    library(ragg)
    
    # Enable ragg for font rendering
    options(shiny.useragg = TRUE)
    
    # Enable thematic for the Shiny app
    thematic_shiny(font = "auto")
    
    ui <- fluidPage(
      theme = bslib::bs_theme(
        bg = "#002B36", fg = "#EEE8D5", primary = "#2AA198",
        base_font = bslib::font_google("Pacifico")
      ),
      tabsetPanel(
        type = "pills",
        tabPanel("ggplot", plotOutput("ggplot")),
        tabPanel("lattice", plotOutput("lattice")),
        tabPanel("base", plotOutput("base"))
      )
    )
    
    server <- function(input, output) {
      output$ggplot <- renderPlot({
        ggplot(mtcars, aes(wt, mpg, label = rownames(mtcars), color = factor(cyl))) +
          geom_point() +
          ggrepel::geom_text_repel()
      })
      output$lattice <- renderPlot({
        lattice::show.settings()
      })
      output$base <- renderPlot({
        image(volcano, col = thematic_get_option("sequential"))
      })
    }
    
    shinyApp(ui, server)
  4. Apply custom colors and fonts manually

    main

    You can bypass automatic detection by providing specific colors and fonts directly to thematic_on() (or thematic_shiny()/thematic_rmd()).

    Supported parameters include:

    • bg: Background color
    • fg: Foreground color
    • accent: Accent color
    • font: Font name
    library(ggplot2)
    thematic::thematic_on(bg = "#222222", fg = "white", accent = "#0CE3AC", font = "Oxanium")
    
    ggp <- ggplot(mtcars, aes(wt, mpg, label = rownames(mtcars), color = factor(cyl))) +
      geom_point() +
      ggrepel::geom_text_repel()
    
    ggp
  5. Enable auto-theming in RStudio

    main

    To have all subsequent plots in the RStudio "Plots" viewing pane reflect your current RStudio theme, call thematic_on() before generating plots.

    • thematic_on(): Enables theming for the remainder of the R session.
    • thematic_off(): Disables theming.
    • thematic_theme(): Use this for one-off theming of specific plots.