Skip to contents

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 length

shad_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:

shad_grid(a, b, c, d, cols = c(base = 1, md = 2, lg = 4))

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() or plotOutput() in a tab that isn’t the selected one won’t render until you switch to it – and sometimes not even then. Force it with outputOptions(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