Getting Started with shiny.webawesome

Overview

shiny.webawesome provides an R and Shiny interface to the Web Awesome component library.

Most component wrappers are generated from the upstream Web Awesome metadata file custom-elements.json. The package aims to stay close to upstream Web Awesome names and component APIs while adopting normal R conventions such as snake_case argument names. The package also bundles the Web Awesome runtime it needs, so you do not need to install Web Awesome assets separately in your app. To report the bundled Web Awesome version in your current installation, use wa_version().

Because Web Awesome lives in the browser and Shiny spans both server and client, the package includes more than generated wrappers alone. In practice, there are four core areas to know:

This guide introduces each one briefly and points to the longer-form documentation for deeper coverage.

library(shiny.webawesome)

wa_version()
#> [1] "3.5.0"
button <- shiny.webawesome::wa_button("preview_button", "Preview")
cat(as.character(button), sep = "\n")
#> <wa-button id="preview_button">Preview</wa-button>

Basic Wrapper Usage

At the simplest level, you use generated wrappers as ordinary Shiny UI functions. Wrapper names follow the Web Awesome component names with the wa_ prefix, and kebab-case attributes become snake_case arguments.

There are two common ways to do that in an app:

If you are adding a few Web Awesome components to an otherwise ordinary Shiny app, using them inside fluidPage() is supported and the package will attach its runtime dependency automatically.

library(shiny)
library(shiny.webawesome)

ui <- fluidPage(
  h2("Mixed Shiny page"),
  wa_card(
    header = "Status",
    wa_badge("Beta", appearance = "filled"),
    "This card is rendered inside fluidPage()."
  )
)

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

shinyApp(ui, server)

That mixed approach is useful when you want to adopt Web Awesome gradually or only need a small number of components in an existing Bootstrap-based app. The components will work, but you should still check the rendered page for spacing, typography, color, or theme/style mismatches between the surrounding Bootstrap layout and the Web Awesome components.

If Web Awesome is the main UI system for the app, prefer webawesomePage(). It builds a minimal full-page scaffold and attaches the package dependency once at page level.

library(shiny)
library(shiny.webawesome)

ui <- webawesomePage(
  title = "Basic wrappers",
  wa_container(
    class = "wa-stack",
    style = "max-width: 32rem; margin: 2rem auto;",
    wa_button(
      "save_button",
      "Save",
      appearance = "filled",
      style = "width: 10rem;"
    ),
    wa_card("A simple card body")
  )
)

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

shinyApp(ui, server)

Two package-level helpers appear here:

For fuller layout examples, see the Layout Utilities article.

Shiny Bindings

Some components expose generated Shiny bindings. These bindings are curated to fit Shiny’s reactive model rather than mirroring every browser event emitted by the underlying Web Component.

For example, wa_select() can participate directly in ordinary Shiny input flows:

library(shiny)
library(shiny.webawesome)

ui <- webawesomePage(
  title = "Bindings",
  wa_select(
    "favorite_letter",
    wa_option("A", value = "a"),
    wa_option("B", value = "b"),
    wa_option("C", value = "c")
  ),
  verbatimTextOutput("selected_value")
)

server <- function(input, output, session) {
  output$selected_value <- renderPrint({
    input$favorite_letter
  })
}

shinyApp(ui, server)

The details of binding categories and reactive semantics are covered in the Shiny Bindings article.

Command API

Generated bindings and update helpers cover the most common component-side interactions, but sometimes a browser-side property or method still needs to be driven explicitly from the server.

For those cases, the package provides a narrow command/helper layer.

library(shiny)
library(shiny.webawesome)

ui <- webawesomePage(
  title = "Command API",
  actionButton("open_dialog", "Open dialog"),
  wa_dialog(
    "dialog",
    "Dialog body"
  )
)

server <- function(input, output, session) {
  observeEvent(input$open_dialog, {
    wa_call_method("dialog", "show", session = session)
  })
}

shinyApp(ui, server)

When you need app-local browser glue that is easier to express in JavaScript, wa_js() lets you inject a small inline snippet and pair it with ordinary Shiny inputs via Shiny.setInputValue().

For more detailed guidance for choosing between generated bindings, update helpers, command helpers, and wa_js(), please see the Command API article.

Package Options

The package currently documents its warning and diagnostic controls through the package option shiny.webawesome.warnings, which should be a named list.

Known keys currently include:

For example, you can enable additional command-layer diagnostics during development with:

options(
  shiny.webawesome.warnings = list(
    command_layer_debug = TRUE
  )
)

These options are described in more detail in the Package Options article and summarized in the package help page ?shiny.webawesome.

Next Steps

After this guide, the most relevant longer-form docs are: