shadshiny gives you surfaces and structure – cards, tabs, a sidebar shell, resizable panes – but leaves page layout to plain CSS. This guide shows how to assemble them into real app shells.
Cards as the base surface
shad_card() is the primary container. Compose it from
its parts; each is optional:
shad_card(
shad_card_header(
shad_card_title("Team members"),
shad_card_description("Invite your colleagues to collaborate.")
),
shad_card_content(
# ... body ...
),
shad_card_footer(
shad_button("Save"), shad_button("Cancel", variant = "outline")
)
)Container, stack, grid
Three primitives cover almost all page layout. They are CSS-only wrappers: each argument becomes a custom property on the root, so there is no utility-class soup and no JavaScript.
shad_container() is the outermost wrapper – a centred,
max-width column:
shad_container(page_content, size = "lg") # sm/md/lg/xl/full, or a CSS lengthshad_stack() is “these things, spaced” – a flex column
by default, a row when you ask:
shad_stack(section_one, section_two, gap = 6)
shad_stack(
shad_button("Save"), shad_button("Cancel", variant = "outline"),
direction = "horizontal", gap = 2, align = "center"
)shad_grid() handles two dimensions. Reach for
min_width first – it fits as many equal columns as will
fit, with no breakpoints to reason about:
shad_grid(card_one, card_two, card_three, min_width = "16rem")When you want an exact column count, pass cols,
optionally per breakpoint (base, sm 40rem,
md 48rem, lg 64rem). Each breakpoint falls
back to the one below it, so you only name the ones that change:
template takes an explicit track list, and
shad_grid_item() spans cells:
shad_grid(
main_panel,
shad_grid_item(wide_chart, span = "full"),
template = "2fr 1fr"
)Gaps and padding accept a spacing token step –
gap = 4 is var(--shad-space-4), the same scale
the components use internally – or any CSS length when you need to
escape the scale.
Tabs
shad_tabs() splits a region into panes. The active pane
is input$id; switch it from the server with
update_shad_tabs().
shad_tabs(
"settings_tabs", selected = "profile",
shad_tab("profile", "Profile", profile_ui),
shad_tab("account", "Account", account_ui),
shad_tab("billing", "Billing", billing_ui)
)Outputs inside an initially-hidden tab are suspended. A
textOutput()orplotOutput()in a tab that isn’t theselectedone won’t render until you switch to it – and sometimes not even then. Force it withoutputOptions(output, "id", suspendWhenHidden = FALSE). The same applies to outputs inside a dialog or sheet that opens later.
Page shells
Two wrappers assemble a whole page in one call. Both take the
page_shad() theming arguments (theme_preset,
dark, theme) and wrap their content in a
shad_container() unless you pass
container = FALSE.
shad_page_navbar() – a title bar carrying a tab strip,
panels below. The window scrolls; the bar is sticky.
input$<inputId> is the active tab.
ui <- shad_page_navbar(
shad_tab("overview", "Overview", overview_ui),
shad_tab("reports", "Reports", reports_ui),
title = "Acme", inputId = "nav",
header_end = bslib::input_dark_mode()
)shad_page_sidebar() – the application frame: a
collapsible sidebar, a bar with its trigger, and a scrolling main
region. This shell takes the full viewport height and scrolls its main
region rather than the window, so the sidebar rail and footer stay
put.
ui <- shad_page_sidebar(
sidebar = shad_sidebar(
shad_sidebar_group("Platform",
shad_sidebar_item("home", "Home", icon = "home", active = TRUE),
shad_sidebar_item("inbox", "Inbox", icon = "mail", badge = "3"))),
inputId = "shell", title = "Acme",
shad_grid(kpi_one, kpi_two, kpi_three, min_width = "14rem")
)⌘K navigation
shad_command_palette() is the “jump anywhere” pattern: a
modal, searchable list of everything the app can do, opened with ⌘K /
Ctrl+K. Items come from data – a named vector, or a named list of them
for grouped sections:
shad_command_palette("palette", items = list(
"Go to" = c(Dashboard = "dashboard", Reports = "reports"),
"Actions" = list(
list(value = "new", label = "New report", shortcut = "N",
keywords = "create add")
)
))Drop shad_command_trigger("palette") in the page bar for
people who do not know the shortcut, and observe
input$palette_event – not
input$palette:
server <- function(input, output, session) {
observeEvent(input$palette_event, {
switch(input$palette_event$value,
dashboard = update_shad_tabs("nav", "dashboard"),
reports = update_shad_tabs("nav", "reports"),
new = shad_show_dialog(new_report_dialog())
)
})
}input$palette holds the last value, but Shiny drops a
repeat of the same value – so choosing “Reports” twice would only fire
once. _event carries value plus a
nonce and fires every time, which is what navigation
needs.
update_shad_command() replaces the items from the
server: recent documents, search hits, commands gated on the signed-in
user.
The sidebar shell, by hand
shad_page_sidebar() is a thin wrapper over
shad_sidebar_layout(). Use the layout directly when the
sidebar is one region of a larger page rather than the page itself.
sidebar <- shad_sidebar(
header = tags$div(
style = "display:flex;gap:0.5rem;align-items:center;padding:0.25rem",
shad_icon("terminal"), tags$strong("Acme")
),
shad_sidebar_group("Platform",
shad_sidebar_item("home", "Home", icon = "circle", active = TRUE),
shad_sidebar_item("inbox", "Inbox", icon = "mail", badge = "3"),
shad_sidebar_item("search", "Search", icon = "search")
),
shad_sidebar_group("Account",
shad_sidebar_item("settings", "Settings", icon = "more-horizontal")
),
footer = shad_muted(style = "padding:0.25rem", "v1.0.0")
)
ui <- page_shad(
tags$div(style = "height:100vh",
shad_sidebar_layout(
"shell",
sidebar = sidebar,
main = tags$div(
style = "padding:1.5rem",
shad_sidebar_trigger(), # the collapse toggle
uiOutput("page")
)
)
)
)Reading the sidebar. The layout reports a list, not a scalar. Observe the active item specifically:
server <- function(input, output, session) {
# input$shell is list(collapsed=, mobileOpen=, active=)
observeEvent(input$shell$active, {
output$page <- renderUI(switch(input$shell$active,
home = home_ui, inbox = inbox_ui, search = search_ui, settings = settings_ui
))
}, ignoreInit = TRUE)
}Toggle it from the server with
shad_sidebar_toggle("shell") or
update_shad_sidebar("shell", collapsed = TRUE).
Resizable panes
For a two-pane workspace (list + detail, editor + preview), use
shad_resizable():
shad_resizable(
"split",
shad_resizable_panel(default_size = 35, list_ui),
shad_resizable_handle(),
shad_resizable_panel(default_size = 65, detail_ui)
)Scrollable regions
shad_scroll_area(height = ) gives a fixed-height region
a styled scrollbar – useful for long lists inside a card or a chat
transcript. For a growing conversation that should pin to the bottom,
reach for shad_message_scroller() instead (see the chat
gallery).
Separators
shad_separator() draws a divider. Horizontal separators
span the full width by default, which overflows inside a flex row – give
them style = "flex:1" when using one as a rule between
inline items (for example an “OR” divider).
tags$div(style = "display:flex;align-items:center;gap:0.75rem",
shad_separator(style = "flex:1"),
shad_muted("OR"),
shad_separator(style = "flex:1")
)Where to next
- Gallery: navigation & structure – these components, live.
- Server API – driving tabs, sidebars and overlays.
-
shad_run_example("02-analytics-dashboard")– a full sidebar + menubar shell. ```