Everything shadshiny does from the server falls into four groups: update input values, open/close overlays, raise toasts, and – for the few cases without a wrapper – send a custom message directly. All helpers are Shiny-module safe and default to the current reactive domain.
Updating inputs
Every valued component has an update_shad_*() twin
taking the same inputId:
update_shad_select("plan", selected = "pro")
update_shad_combobox("lang", selected = c("R", "Python"), multiple = TRUE)
update_shad_checkbox("tos", value = TRUE)
update_shad_switch("dark", value = FALSE)
update_shad_radio_group("size", selected = "md")
update_shad_toggle("bold", value = TRUE)
update_shad_toggle_group("align", selected = "center")
update_shad_slider("volume", value = 60)
update_shad_input_otp("code", value = "123456")
update_shad_native_select("country", selected = "in")
update_shad_calendar("day", value = Sys.Date())
update_shad_date_picker("due", value = Sys.Date() + 7)
update_shad_tabs("tabs", selected = "billing")
update_shad_accordion("faq", value = "shipping")
update_shad_collapsible("details", open = TRUE)
update_shad_pagination("pager", selected = 2)
update_shad_carousel("gallery", selected = 3)
update_shad_resizable("split", sizes = c(35, 65))
update_shad_sidebar("shell", collapsed = TRUE)
update_shad_progress("upload", value = 80)
update_shad_button("save", loading = TRUE) # or disabled=, label=
update_shad_command("palette", items = c("Recent: Q3.pdf" = "q3"))Set or clear an error on the shad_form_field() wrapping
a control directly:
update_shad_form_field("email", "Enter a valid email address.")
update_shad_form_field("email", NULL)The one exception: text inputs.
shad_input() and shad_textarea() render real
<input>/<textarea> elements and
use Shiny’s native text bindings. There is no
update_shad_input(). Update them with base Shiny:
updateTextInput(session, "email", value = "you@example.com")
updateTextAreaInput(session, "bio", value = "Hello!")Theming at runtime
update_shad_theme() swaps the preset and/or dark mode
live:
observe(update_shad_theme(preset = input$preset, dark = input$dark))
update_shad_theme(preset = "default") # clear the presetOpening & closing overlays
Overlays can open from a UI trigger, or from the server
by inputId:
shad_dialog_open("edit") ; shad_dialog_close("edit")
shad_alert_dialog_open("confirm") ; shad_alert_dialog_close("confirm")
shad_sheet_open("filters") ; shad_sheet_close("filters")
shad_drawer_open("cart") ; shad_drawer_close("cart")
shad_popover_open("picker") ; shad_popover_close("picker")
shad_sidebar_toggle("shell") # collapse/expand the sidebarA confirm flow with an alert-dialog:
observeEvent(input$delete, shad_alert_dialog_open("confirm_delete"))
observeEvent(input$confirm_delete, { # the dialog's confirm action
do_the_deletion()
shad_alert_dialog_close("confirm_delete")
shad_toast_success("Deleted.")
})Overlays only reachable this way have to exist in the UI. When the
content depends on what just happened, build the dialog in the server
and show it – shiny::showModal()’s shape:
observeEvent(input$delete, {
shad_show_dialog(shad_dialog(
"confirm", title = paste("Delete", input$project, "?"),
description = "This cannot be undone.",
footer = tagList(shad_dialog_close_button(),
shad_button(inputId = "confirm_go", "Delete",
variant = "destructive"))
))
})It opens itself and, by default, destroys and removes itself once it
closes – so inputs inside it are live while open and gone afterwards.
Pass transient = FALSE to keep it (and its values) in the
document for a later shad_dialog_open().
shad_remove_dialog(id) closes one from the server. Accepts
shad_dialog(), shad_alert_dialog(),
shad_sheet() and shad_drawer() – not
shad_popover(), which has no trigger to anchor to.
Dialog and sheet content portals to
<body>on open. The open element carriesdata-state="open"on.shad-dialog__content(not on the root#id). This matters if you probe open state from JavaScript – query the content globally, not as a descendant of the id.
Toasts
Toasts are entirely server-side. The base shad_toast()
plus four shorthands:
shad_toast("Saved.")
shad_toast_success("Profile updated.")
shad_toast_error("Something went wrong.")
shad_toast_warning("Your trial ends in 3 days.")
shad_toast_loading("Uploading…") # a persistent spinner toastFor a loading → done flow, capture the id and update it:
observeEvent(input$export, {
id <- shad_toast_loading("Preparing export…")
# ... do the work ...
shad_toast_update(id, message = "Export ready.", type = "success")
})
shad_toast_dismiss(id) # or shad_toast_dismiss() to clear allDeferred callbacks run outside the reactive domain. If you raise or update a toast (or scroll a component) inside a
later::later()/promisescallback, the default-session lookup fails. Passsessionexplicitly, and wrap reactive reads/writes inshiny::withReactiveDomain(session, { ... }):later::later(function() { shiny::withReactiveDomain(session, { shad_toast_update(id, message = "Done.", type = "success", session = session) }) }, delay = 2)
Binding an ExtendedTask to a button
bind_shad_task_button() is an experimental presentation
binding for an application-owned shiny::ExtendedTask. It
observes task$status() and calls
update_shad_button() for the four supported states:
| Task status | Button presentation |
|---|---|
initial |
enabled, not loading |
running |
loading, disabled, label_busy
|
success |
enabled, optional label_success
|
error |
enabled, optional label_error
|
The task still belongs to the application. The helper does not invoke
it, call task$result(), create a worker, or choose an
asynchronous backend. It returns the observer invisibly and destroys
that observer when the session ends.
task <- shiny::ExtendedTask$new(function(value) {
expensive_work(value) # return a promise-compatible result
})
bind_shad_task_button(
task, "run", label_busy = "Working...", label_success = "Complete",
label_error = "Try again", session = session
)
observeEvent(input$run, task$invoke(input$value), ignoreInit = TRUE)The async function can be supplied by an optional application dependency. Keep those choices outside shadshiny’s imports and guard them when writing reusable application examples:
if (requireNamespace("mirai", quietly = TRUE)) {
task <- shiny::ExtendedTask$new(function(value) {
mirai::mirai({ expensive_work(value) }, value = value)
})
}
if (requireNamespace("promises", quietly = TRUE) &&
requireNamespace("future", quietly = TRUE)) {
task <- shiny::ExtendedTask$new(function(value) {
promises::future_promise(expensive_work(value))
})
}These examples intentionally leave task creation, worker policy,
error handling, and result rendering to the application.
bind_shad_task_button() only translates the reactive
lifecycle into button state.
The command palette from the server
shad_command_palette() opens on ⌘K, from
shad_command_trigger(), or from the server:
shad_command_open("palette")
shad_command_close("palette")
# swap the items for whatever the session knows
update_shad_command("palette", items = list(
"Recent" = c("Q3 report" = "q3", "Q4 forecast" = "q4")
))Read selections from
input$<id>_event, a list of
value and nonce – not
input$<id>:
observeEvent(input$palette_event, {
switch(input$palette_event$value,
dashboard = update_shad_tabs("nav", "dashboard"),
reports = update_shad_tabs("nav", "reports"))
})input$<id> holds the last value, and Shiny drops a
repeat of the same value. That is fine for a filter and wrong for
navigation: choosing “Reports” twice has to work twice.
_event fires every time.
The shadshiny:attr message sets or removes an attribute
on any element – handy for, say, a password reveal that flips an input’s
type:
observeEvent(input$reveal, {
session$sendCustomMessage("shadshiny:attr",
list(id = "password", attr = "type",
value = if (revealed()) "text" else "password"))
})Reading component values
Bound components report through input$<id> like
any Shiny input. Two shapes are worth calling out:
-
Sidebar layout emits a list, not a scalar:
input$shellislist(collapsed=, mobileOpen=, active=). Observeinput$shell$activefor the selected nav item. -
Menus and command items report the chosen item’s
value as an event – observe
input$menu/input$cmdand switch on it.
Bookmarking
shadshiny inputs work with Shiny’s bookmarking.
Turn it on with enableBookmarking("url") (or
"server"). Components with a meaningful constructor initial
value seed it through shiny::restoreInput(); the package’s
strict, source-derived component-contract test keeps that set in sync as
inputs evolve. This includes input OTP values and collapsible open state
as well as the standard text, choice, date, navigation, and numeric
controls.
Some state is intentionally not seeded from a single constructor
value: transient overlay visibility; event-only menu, command, and
navigation-menu activity; action-button counts and
browser-security-constrained file uploads; and composite carousel,
sidebar, resizable, or data-table state. Restore any
application-specific version of that state explicitly in an
onRestored() observer, using the component’s updater or
imperative helper when one exists.
Gotchas checklist
- No
update_shad_input()– useupdateTextInput()forshad_input(). - Outputs inside an initially-hidden tab, dialog or sheet are
suspended; set
outputOptions(output, "id", suspendWhenHidden = FALSE). - Sidebar value is a list; watch
$active. - In
later/promisescallbacks, passsession=and usewithReactiveDomain(). -
shad_item(media = )treats a string as an icon name. Pass"file"withmedia_variant = "icon", or wrap non-icon content in a tag – never a renderedshad_icon().
Where to next
- Forms & validation – updating and validating a real form.
- Overlays & the server – dialogs and confirm flows in depth.
- Layout & composition – driving tabs and sidebars. ```