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.

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