Skip to contents

Styling and Theming

Source: vignettes/styling-and-theming.Rmd
styling-and-theming.Rmd

Overview

shiny.webawesome follows upstream Web Awesome styling patterns closely.

In practice, there are two main levels to know:

  • page-level theming, palettes, and brand selection
  • component-level styling through ordinary HTML hooks and Web Awesome design tokens

This article gives a short package-specific map and points you back to the upstream Web Awesome docs for the broader styling system.

Page-Level Themes and Palettes

Web Awesome’s theme system is page-oriented, with theme, palette, and brand classes applied to the <html> element. For example:

  • wa-palette-default
  • wa-theme-default wa-palette-default wa-brand-blue

In shiny.webawesome, the corresponding place to do that is webawesomePage(class = ...).

This executed example prints the HTML scaffold emitted by a themed webawesomePage() call:

library(shiny.webawesome)

themed_page <- webawesomePage(
  title = "Themed preview",
  class = "wa-theme-default wa-palette-default wa-brand-blue",
  wa_card("Styled preview")
)

cat(as.character(themed_page), sep = "\n")
## <html class="wa-theme-default wa-palette-default wa-brand-blue">
##   <body>
##     <wa-card>Styled preview</wa-card>
##   </body>
## </html>

Here is the corresponding full Shiny page pattern:

library(shiny)
library(shiny.webawesome)

ui <- webawesomePage(
  title = "Themed page",
  class = "wa-theme-default wa-palette-default wa-brand-blue",
  wa_container(
    class = "wa-stack",
    style = "max-width: 32rem; margin: 2rem auto;",
    wa_badge("Beta", appearance = "filled"),
    wa_card("This page applies Web Awesome classes at the html root.")
  )
)

server <- function(input, output, session) {}

shinyApp(ui, server)

For the bundled non-default themes, webawesomePage() also recognizes the root classes wa-theme-awesome and wa-theme-shoelace and loads the matching bundled theme stylesheet automatically.

ui <- webawesomePage(
  title = "Awesome theme",
  class = "wa-theme-awesome wa-palette-bright wa-brand-blue",
  wa_container(
    style = "max-width: 32rem; margin: 2rem auto;",
    wa_card("The matching Awesome theme stylesheet is attached automatically.")
  )
)

For broader upstream theme and palette guidance, consult the upstream Web Awesome theming documentation. The package keeps the control surface upstream-first by treating page-root classes as the main theming hook.

Styling Individual Components

For individual components, the first styling hooks are the standard wrapper arguments class and style.

wa_card(
  "Styled card",
  class = "my-card",
  style = "max-width: 32rem;"
)

That works well for:

  • ordinary CSS class hooks
  • small app-local layout adjustments
  • utility-class usage

When you need additional standard HTML attributes, append them with htmltools::tagAppendAttributes(). See the Extra Attributes via htmltools article for that pattern.

Design tokens

Web Awesome also documents a larger design-token system for colors, spacing, typography, shadows, and related styling primitives.

In shiny.webawesome, the intended approach is still upstream-first:

  • apply page-level classes with webawesomePage(class = ...)
  • style component instances with normal class and style hooks
  • use Web Awesome design tokens in your app CSS when you need more control

For example, you can target a custom class and rely on Web Awesome token variables in your own stylesheet:

.my-card {
  border-color: var(--wa-color-brand-border-normal);
  box-shadow: var(--wa-shadow-l);
  padding: var(--wa-space-l);
}

This package does not try to wrap the full design-token catalog as a separate R API. The goal is to stay close to upstream so that the Web Awesome styling docs remain directly useful.

  • Use webawesomePage(class = ...) for page-level theme, palette, and brand classes.
  • Use wrapper class and style arguments for ordinary component-level styling hooks.
  • Use htmltools when you need extra HTML attributes beyond the wrapper surface.
  • Consult the upstream Web Awesome docs for the full theming and design-token system.