Shiny Bindings

Overview

shiny.webawesome does not try to forward every browser event emitted by every Web Awesome component into Shiny.

Instead, the package generates a curated binding surface that fits Shiny’s reactive input model. In practice, that means the package favors bindings that represent committed, meaningful Shiny input state rather than transient browser telemetry.

This article describes the current binding categories, the design philosophy behind them, and representative examples.

Binding Categories

The current generated binding surface uses three categories:

Durable semantic values

This is the default binding model.

The binding subscribes to a supported commit/value event and then reads the component’s current durable state. Examples include:

• wa_select() reading its current selected value
• wa_dialog() exposing its current open state
• wa_tree() exposing its current selected item ids

The important idea is that Shiny receives the semantic state the user would care about, not the raw browser event name.

Action-style bindings

Some components are inherently action-like in Shiny. For those, the binding uses action semantics rather than pretending the component exposes a durable value payload.

The canonical example is wa_button(), whose Shiny input behaves like an action input that invalidates on each click.

Action-with-payload bindings

Some rare components need both:

• action invalidation semantics
• a separate companion payload input exposing the latest committed payload

The canonical current example is wa_dropdown().

For wa_dropdown(input_id = "menu", ...):

• input$menu behaves like an action counter and invalidates on every selection, including repeated selection of the same item
• input$menu_value exposes the latest selected item value

This split is useful because repeated same-item selections should still invalidate Shiny even when the latest payload value does not change.

Design Philosophy

The package’s binding model follows a few rules:

• bindings should expose the Shiny contract, not simply mirror raw browser event names
• default bindings should prefer committed semantic state
• action-like controls should use action semantics only through explicit policy
• action-with-payload contracts should remain narrow and explicit

This keeps the reactive surface smaller and easier to reason about.

It also preserves a clear boundary between:

• browser-local interaction handling
• Shiny-reactive input publication

If a browser-side interaction does not belong in the package’s curated binding surface, it is usually a better fit for browser-side code or the package’s command/helper layer.

Examples

library(shiny.webawesome)

binding_preview <- wa_select(
  "favorite_letter",
  wa_option("A", value = "a"),
  wa_option("B", value = "b"),
  wa_option("C", value = "c")
)

cat(as.character(binding_preview), sep = "\n")

## <wa-select id="favorite_letter">
##   <wa-option value="a">A</wa-option>
##   <wa-option value="b">B</wa-option>
##   <wa-option value="c">C</wa-option>
## </wa-select>

Example: durable semantic value

wa_select() is a representative durable-value binding.

library(shiny)
library(shiny.webawesome)

ui <- webawesomePage(
  title = "Semantic binding",
  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)

Here, the Shiny input reflects the current selected value, not a raw event stream.

Example: event-driven semantic state

wa_dialog() is also a semantic binding, but its Shiny value is derived from committed dialog lifecycle state rather than a conventional text or scalar form value.

library(shiny)
library(shiny.webawesome)

ui <- webawesomePage(
  title = "Semantic dialog state",
  actionButton("open_dialog", "Open dialog"),
  wa_dialog(
    "dialog",
    label = "Example dialog",
    "Dialog body"
  ),
  verbatimTextOutput("dialog_state")
)

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

  output$dialog_state <- renderPrint({
    input$dialog
  })
}

shinyApp(ui, server)

Here, the binding publishes the committed semantic state of the component: whether the dialog is currently open.

Example: structured semantic selection

wa_tree() is another semantic binding, but its Shiny value is a structured selection derived from selected descendant tree items.

library(shiny)
library(shiny.webawesome)

ui <- webawesomePage(
  title = "Semantic tree selection",
  wa_tree(
    "navigation_tree",
    selection = "multiple",
    wa_tree_item("Section A", id = "section_a"),
    wa_tree_item("Section B", id = "section_b"),
    wa_tree_item("Section C", id = "section_c")
  ),
  verbatimTextOutput("tree_value")
)

server <- function(input, output, session) {
  output$tree_value <- renderPrint({
    input$navigation_tree
  })
}

shinyApp(ui, server)

The Shiny value is a vector of selected descendant wa-tree-item ids. For stable selection values, selectable tree items should have DOM id attributes.

Example: action-style binding

wa_button() is action-like in Shiny.

library(shiny)
library(shiny.webawesome)

ui <- webawesomePage(
  title = "Action binding",
  wa_button("run_action", "Run"),
  verbatimTextOutput("click_count")
)

server <- function(input, output, session) {
  output$click_count <- renderPrint({
    input$run_action
  })
}

shinyApp(ui, server)

The input invalidates on each click in the same way a Shiny action input does.

Example: action-with-payload binding

wa_dropdown() is the current canonical action-with-payload example.

library(shiny)
library(shiny.webawesome)

ui <- webawesomePage(
  title = "Action with payload",
  wa_dropdown(
    "menu",
    wa_dropdown_item("Alpha", value = "alpha"),
    wa_dropdown_item("Beta", value = "beta"),
    trigger = wa_button("menu_trigger", "Open menu")
  ),
  verbatimTextOutput("action_value"),
  verbatimTextOutput("payload_value")
)

server <- function(input, output, session) {
  output$action_value <- renderPrint({
    input$menu
  })

  output$payload_value <- renderPrint({
    input$menu_value
  })
}

shinyApp(ui, server)

In this case:

• input$menu is the action-style invalidator
• input$menu_value is the latest committed payload state

Current Bound Components

The package currently generates Shiny bindings for the following components.

Component	Binding category	Notes
wa_button()	action	Shiny action-style invalidation on click
wa_carousel()	semantic	durable semantic value
wa_checkbox()	semantic	durable semantic value
wa_color_picker()	semantic	durable semantic value
wa_comparison()	semantic	durable semantic value
wa_details()	semantic	durable semantic value
wa_dialog()	semantic	event-driven semantic open state
wa_drawer()	semantic	event-driven semantic open state
wa_dropdown()	action-with-payload	action invalidator plus input$<id>_value payload
wa_input()	semantic	durable semantic value
wa_number_input()	semantic	durable semantic value
wa_radio_group()	semantic	durable semantic value
wa_rating()	semantic	durable semantic value
wa_select()	semantic	durable semantic value
wa_slider()	semantic	durable semantic value
wa_switch()	semantic	durable semantic value
wa_tab_group()	semantic	durable semantic value
wa_textarea()	semantic	durable semantic value
wa_tree()	semantic	selected descendant item ids

In the website build, these entries should link to the corresponding reference pages.

Relationship to the Command API

Bindings and the command/helper layer solve different problems.

Use generated bindings when the package already exposes the Shiny-reactive contract you need.

Use the command/helper layer when you need browser-side property or method interaction that falls outside the generated binding/update surface.

For more on that boundary, see the Command API guide.