Package {bslibdash}

bslibdash: Bootstrap 5 dashboards for Shiny

Description

Build Bootstrap 5 dashboards in Shiny, on bslib::bslib. bslibdash provides a page shell (dashboardPage(), dashboardHeader(), dashboardSidebar(), dashboardBody(), dashboardFooter()), sidebar navigation (sidebarMenu(), menuItem(), sidebarUserPanel()), cards (box(), boxLayout(), tabBox()), KPI tiles (valueBox(), infoBox()), header dropdowns (dropdownMenu(), notificationItem(), messageItem(), taskItem()), and lightweight feedback helpers (accordions, badges, toasts).

Details

Function names mirror shinydashboard wherever the underlying concept is the same, so most apps port across as a search-and-replace. bslibdash is not a drop-in clone: a small number of legacy arguments and behaviours that no longer make sense on Bootstrap 5 have been removed — see vignette("getting-started", package = "bslibdash") for the full migration story.

Every bslibdash component attaches its CSS via bslib::bs_dependency_defer(), so any bslib::bs_theme() (including the bundled brand_bs_theme()) recompiles bslibdash styles against the active theme.

Learn more

• vignette("getting-started", package = "bslibdash") — minimal skeleton and the migration guide from shinydashboard.

• vignette("components", package = "bslibdash") — a tour of every component with copy-pasteable examples.

• vignette("theming", package = "bslibdash") — customising brand_bs_theme(), swapping Bootswatch presets, and adding bespoke SCSS.

Author(s)

Maintainer: Alexandros Kouretsis alexandros@appsilon.com

Authors:

• Ardalan Mirshani ardalan.mirshani@novartis.com

• Dominik Rafacz dominik.rafacz_ext@novartis.com

Other contributors:

• Novartis Open Source Initiative [copyright holder]

See Also

Useful links:

• https://github.com/Novartis/bslibdash

• https://opensource.nibr.com/bslibdash/

• Report bugs at https://github.com/Novartis/bslibdash/issues

Accordion container

Description

Accordion container

Accordion item

Usage

accordion(..., id, width = 12, .list = NULL)

accordionItem(..., title, status = NULL)

Arguments

Value

accordion() returns a bslib::accordion() tag that may be included in a Shiny UI.

accordionItem() returns a bslib::accordion_panel() tag that may be passed to accordion().

Examples

accordion(
  id = "filters",
  accordionItem(title = "Date range", shiny::p("Last 30 days")),
  accordionItem(title = "Region", shiny::p("All regions"))
)

accordionItem(
  title = "Advanced settings",
  status = "info",
  shiny::p("Optional controls")
)

Action button/link

Description

Action button/link

Usage

actionButton(
  inputId,
  label,
  icon = NULL,
  width = NULL,
  ...,
  status = NULL,
  outline = FALSE,
  size = NULL,
  flat = FALSE
)

Arguments

Value

Returns a UI element for an action button. The server value received for the input corresponding to inputId will be an integer that increments with each click.

Examples

actionButton(
  inputId = "refresh",
  label = "Refresh",
  icon = "arrow-clockwise",
  status = "primary"
)

Create dashboard badge item

Description

Create dashboard badge item

Backwards-compatible alias to badge()

Usage

badge(..., position = c("left", "right"), color, rounded = FALSE)

dashboardBadge(..., position = c("left", "right"), color, rounded = FALSE)

Arguments

Value

An htmltools::span() tag that may be included in a Shiny UI (e.g. inside a menuItem() label).

Examples

badge("NEW", color = "success", position = "right", rounded = TRUE)

Create a card

Description

Create a card

Update a card from the server side

Backwards-compatible alias to updateBox()

Usage

box(
  ...,
  title = NULL,
  footer = NULL,
  status = NULL,
  background = NULL,
  width = 6,
  height = NULL,
  collapsible = FALSE,
  collapsed = FALSE,
  closable = FALSE,
  maximizable = FALSE,
  icon = NULL,
  label = NULL,
  id = NULL
)

updateBox(
  id,
  action = c("remove", "toggle", "update", "restore", "toggleMaximize"),
  options = NULL,
  session = shiny::getDefaultReactiveDomain()
)

updateCard(
  id,
  action = c("remove", "toggle", "update", "restore", "toggleMaximize"),
  options = NULL,
  session = shiny::getDefaultReactiveDomain()
)

Arguments

Value

box() returns a bslib::card() tag, wrapped in a shiny::column() when width is an integer between 1 and 12.

updateBox() and updateCard() return nothing. These functions are called for their side-effects.

See Also

Other cards: boxLayout()

Examples

box(
  "Card body",
  title = "Status",
  status = "primary",
  id = "status_box"
)

boxLayout(
  box("A", title = "Card A"),
  box("B", title = "Card B"),
  type = "deck"
)

if (interactive()) {
shiny::shinyApp(
  ui = bslib::page_fluid(
    shiny::actionButton("toggle", "Toggle card"),
    box("Card body", title = "Status", id = "status_box")
  ),
  server = function(input, output, session) {
    shiny::observeEvent(input$toggle, {
      updateBox("status_box", action = "toggle", session = session)
    })
  }
)
}

Container for cards

Description

Container for cards

Usage

boxLayout(..., .list = NULL, type = c("group", "deck", "columns"))

Arguments

Value

An htmltools::div() tag containing the supplied cards.

See Also

Other cards: box()

Examples

boxLayout(
  box("Revenue", title = "KPI"),
  box("Trend", title = "Chart"),
  type = "deck"
)

Default bslibdash brand theme

Description

Builds a Bootstrap 5 theme via bslib::bs_theme() with the bslibdash brand colour, typography and shape variables.

Usage

brand_bs_theme()

Details

Component CSS is no longer bundled into the theme: each bslibdash component attaches its own theme-aware bslib::bs_dependency_defer() dependency, so rendering a component with any bslib::bs_theme() produces the matching bslibdash styles. brand_bs_theme() exists to set the Bootstrap-level variables used as defaults by bslibdash page constructors.

dashboardPage() applies this theme by default. To customise it, override variables or rules via bslib and pass the result through the page theme argument:

dashboardPage(
  header = dashboardHeader(),
  sidebar = dashboardSidebar(),
  body = dashboardBody(),
  theme = brand_bs_theme() |>
    bslib::bs_add_variables(primary = "#8B0000")
)

Value

Returns a bslib::bs_theme() object.

Examples

theme <- brand_bs_theme()
class(theme)

Column system

Description

Column system

Usage

column(width, ..., offset = 0)

Arguments

Value

A shiny::column() tag that may be included in a Shiny UI.

Examples

shiny::fluidRow(
  column(8, shiny::p("Main content")),
  column(4, shiny::p("Side panel"))
)

Dashboard body

Description

Containers for tab content placed inside dashboardBody():

Usage

dashboardBody(...)

tabItems(..., id = "sidebarMenu")

tabItem(tabName = NULL, ...)

Arguments

Details

• tabItems() is the parent container.

• tabItem(tabName) is one tab; tabName must match the corresponding menuItem() tabName.

Value

dashboardBody() returns an htmltools::div() tag that may be passed to dashboardPage().

tabItems() returns an htmltools::div() tag containing a hidden shiny::tabsetPanel().

tabItem() returns an htmltools::tagList() that may be passed to tabItems().

Examples

dashboardBody(
  tabItems(
    tabItem(tabName = "overview", shiny::h2("Overview")),
    tabItem(tabName = "reports", shiny::h2("Reports"))
  )
)
tabItems(
  tabItem(tabName = "overview", shiny::p("Overview content")),
  tabItem(tabName = "reports", shiny::p("Reports content"))
)
tabItem(
  tabName = "overview",
  shiny::h2("Overview"),
  shiny::p("This is the overview tab.")
)

Dashboard footer

Description

Dashboard footer

Usage

dashboardFooter(left = NULL, right = NULL, fixed = FALSE)

Arguments

Value

A ⁠<footer>⁠ tag that may be passed to dashboardPage(), or NULL if left and right are both NULL.

Examples

dashboardFooter(
  left = "Copyright (c) 2026",
  right = "Contact: team@example.org"
)

Dashboard navbar

Description

Dashboard navbar

Usage

dashboardHeader(
  ...,
  title = NULL,
  rightUi = NULL,
  sidebarIcon = icon("bars"),
  disable = FALSE,
  .list = NULL
)

Arguments

Value

A ⁠<nav>⁠ tag that may be passed to dashboardPage(), or NULL if disable = TRUE.

Examples

dashboardHeader(
  title = "Operations",
  rightUi = dropdownMenu(
    type = "notifications",
    notificationItem("Server restarted", status = "info")
  )
)

Branded dashboard page

Description

A bslib sidebar layout that arranges the four standard dashboard slots. The title argument, when set, replaces the title text inside header if dashboardHeader() was called without one.

Usage

dashboardPage(
  header,
  sidebar,
  body,
  title = NULL,
  footer = NULL,
  theme = brand_bs_theme()
)

Arguments

Value

A bslib::page() tag that may be passed to the ui argument of shiny::shinyApp().

Examples

ui <- dashboardPage(
  header = dashboardHeader(title = "bslibdash dashboard"),
  sidebar = dashboardSidebar(
    sidebarMenu(
      id = "sidebarMenu",
      menuItem("Overview", tabName = "overview")
    )
  ),
  body = dashboardBody(
    tabItems(
      tabItem(
        tabName = "overview",
        box("Overview content", title = "Overview")
      )
    )
  )
)

Create a dashboard main sidebar

Description

Create a dashboard main sidebar

Dashboard main sidebar menu

Dashboard sidebar menu item

Dashboard sidebar menu sub-item

Dashboard sidebar menu header

Usage

dashboardSidebar(..., disable = FALSE, width = NULL, collapsed = FALSE)

sidebarMenu(..., id = NULL, .list = NULL)

menuItem(
  text,
  ...,
  icon = NULL,
  badgeLabel = NULL,
  badgeColor = "success",
  tabName = NULL,
  selected = NULL,
  expandedName = NULL,
  startExpanded = FALSE,
  condition = NULL
)

menuSubItem(
  text,
  tabName = NULL,
  icon = bslibdash::icon("angle-double-right"),
  selected = NULL
)

sidebarHeader(title)

Arguments

Value

dashboardSidebar() returns an ⁠<aside>⁠ tag that may be passed to dashboardPage(), or NULL if disable = TRUE.

sidebarMenu() returns an htmltools::div() tag that may be passed to dashboardSidebar().

menuItem() returns a menu item that may be passed to sidebarMenu().

menuSubItem() returns a menu item that may be passed to menuItem().

sidebarHeader() returns an htmltools::div() tag that may be passed to sidebarMenu().

Examples

dashboardSidebar(
  sidebarMenu(
    id = "sidebarMenu",
    sidebarHeader("Main"),
    menuItem("Overview", tabName = "overview", icon = icon("house")),
    menuItem(
      "Reports",
      icon = icon("bar-chart"),
      menuSubItem("Daily", tabName = "reports_daily"),
      menuSubItem("Monthly", tabName = "reports_monthly")
    )
  )
)

sidebarMenu(
  id = "sidebarMenu",
  menuItem("Overview", tabName = "overview", icon = icon("house")),
  menuItem("Settings", tabName = "settings", icon = icon("gear"))
)

menuItem(
  "Reports",
  icon = icon("bar-chart"),
  menuSubItem("Daily", tabName = "reports_daily"),
  menuSubItem("Monthly", tabName = "reports_monthly")
)

menuSubItem(
  "Daily report",
  tabName = "reports_daily",
  icon = bslibdash::icon("angle-double-right")
)

sidebarHeader("Administration")

Dropdown menu

Description

Dropdown menu

Message item

Notification item

Task item

Usage

dropdownMenu(
  ...,
  type = c("messages", "notifications", "tasks"),
  badgeStatus = "primary",
  icon = NULL,
  headerText = NULL,
  .list = NULL,
  href = NULL
)

messageItem(
  from,
  message,
  icon = shiny::icon("user"),
  time = NULL,
  href = NULL,
  image = NULL,
  color = "secondary",
  inputId = NULL
)

notificationItem(
  text,
  icon = bslibdash::icon("exclamation-triangle"),
  status = "success",
  href = NULL,
  inputId = NULL
)

taskItem(text, value = 0, color = "info", href = NULL, inputId = NULL)

Arguments

Value

dropdownMenu() returns an htmltools::div() tag that may be passed to dashboardHeader().

messageItem() returns a dropdown item that may be passed to dropdownMenu().

notificationItem() returns a dropdown item that may be passed to dropdownMenu().

taskItem() returns a dropdown item that may be passed to dropdownMenu().

Examples

dropdownMenu(
  type = "notifications",
  badgeStatus = "warning",
  notificationItem("Backup completed", status = "success"),
  notificationItem("New deployment", status = "info")
)

messageItem(
  from = "Ops bot",
  message = "Deployment finished successfully.",
  time = "5 mins ago",
  color = "success"
)

notificationItem(
  text = "3 new alerts",
  status = "danger"
)

taskItem(
  text = "Data refresh",
  value = 75,
  color = "info"
)

Dropdown menu output

Description

Dropdown menu output

Usage

dropdownMenuOutput(outputId)

Arguments

Value

A shiny::uiOutput() container to be filled by renderDropdownMenu().

Examples

dropdownMenuOutput("alerts_menu")

Create an bslibdash icon

Description

Create an bslibdash icon

Usage

icon(name, class = NULL, style = NULL, size = NULL, color = NULL, css = NULL)

Arguments

Value

An HTML tag object that can be included in a Shiny UI.

Examples

if (interactive()) {
  icon("user")
  icon("bar-chart", class = "text-primary", size = "1.25rem")
}

Info box

Description

Info box

Usage

infoBox(
  title,
  value = NULL,
  subtitle = NULL,
  icon = shiny::icon("bar-chart"),
  color = "aqua",
  width = 4,
  href = NULL,
  fill = FALSE
)

Arguments

Value

An htmltools::div() tag, wrapped in a shiny::column() unless width is NULL.

Examples

infoBox(
  title = "CPU",
  value = "42%",
  subtitle = "Current usage",
  icon = icon("cpu"),
  color = "success"
)

Info box output

Description

Info box output

Usage

infoBoxOutput(outputId, width = 4)

Arguments

Value

A shiny::uiOutput() container to be filled by renderInfoBox().

Examples

infoBoxOutput("system_status")

Sidebar menu item output

Description

Sidebar menu item output

Usage

menuItemOutput(outputId)

Arguments

Value

A shiny::uiOutput() container to be filled by renderMenu().

Examples

menuItemOutput("dynamic_menu_item")

Render a dropdown menu

Description

Render a dropdown menu

Usage

renderDropdownMenu(expr, env = parent.frame(), quoted = FALSE)

Arguments

Value

A shiny::renderUI() function that may be assigned to an output slot paired with dropdownMenuOutput().

Examples

if (interactive()) {
shiny::shinyApp(
  ui = bslib::page_fluid(dropdownMenuOutput("alerts_menu")),
  server = function(input, output, session) {
    output$alerts_menu <- renderDropdownMenu({
      dropdownMenu(
        type = "notifications",
        notificationItem("Job finished", status = "success")
      )
    })
  }
)
}

Render an info box

Description

Render an info box

Usage

renderInfoBox(expr, env = parent.frame(), quoted = FALSE)

Arguments

Value

A shiny::renderUI() function that may be assigned to an output slot paired with infoBoxOutput().

Examples

if (interactive()) {
shiny::shinyApp(
  ui = bslib::page_fluid(infoBoxOutput("system_status")),
  server = function(input, output, session) {
    output$system_status <- renderInfoBox({
      infoBox("CPU", "42%", icon = icon("cpu"), color = "success")
    })
  }
)
}

Render a sidebar menu element

Description

Render a sidebar menu element

Usage

renderMenu(expr, env = parent.frame(), quoted = FALSE)

Arguments

Value

A shiny::renderUI() function that may be assigned to an output slot paired with menuItemOutput() or sidebarMenuOutput().

Examples

if (interactive()) {
shiny::shinyApp(
  ui = bslib::page_fluid(menuItemOutput("dynamic_menu_item")),
  server = function(input, output, session) {
    output$dynamic_menu_item <- renderMenu({
      menuItem("Overview", tabName = "overview", icon = icon("house"))
    })
  }
)
}

Render a value box

Description

Render a value box

Usage

renderValueBox(expr, env = parent.frame(), quoted = FALSE)

Arguments

Value

A shiny::renderUI() function that may be assigned to an output slot paired with valueBoxOutput().

Examples

if (interactive()) {
shiny::shinyApp(
  ui = bslib::page_fluid(valueBoxOutput("tickets")),
  server = function(input, output, session) {
    output$tickets <- renderValueBox({
      valueBox("128", "Open tickets", icon = icon("inbox"), color = "primary")
    })
  }
)
}

Sidebar menu output

Description

Sidebar menu output

Usage

sidebarMenuOutput(outputId)

Arguments

Value

A shiny::uiOutput() container to be filled by renderMenu().

Examples

sidebarMenuOutput("dynamic_sidebar_menu")

Create a search form to place in a sidebar

Description

A search form consists of a text input field and a search button.

Usage

sidebarSearchForm(
  textId,
  buttonId,
  label = "Search...",
  icon = shiny::icon("search")
)

Arguments

Value

A ⁠<form>⁠ tag that may be passed to dashboardSidebar(). The server values received for the inputs corresponding to textId and buttonId will be the search string and the button click count.

Examples

sidebarSearchForm(
  textId = "sidebar_search",
  buttonId = "sidebar_search_btn",
  label = "Search records..."
)

Sidebar user panel

Description

Displays a user identity block (avatar, name, optional subtitle) at the top of the dashboard sidebar. Mirrors shinydashboard::sidebarUserPanel().

Usage

sidebarUserPanel(name, image = NULL, subtitle = NULL)

Arguments

Details

When the sidebar is collapsed on desktop, the name and subtitle are hidden and only the circular avatar remains, centered.

Value

An htmltools::div() tag that may be passed to dashboardSidebar().

Examples

dashboardSidebar(
  sidebarUserPanel(
    name = "Jane Doe",
    subtitle = "Administrator"
  ),
  sidebarMenu(
    menuItem("Overview", tabName = "overview")
  )
)

Tab box

Description

Tab box

Usage

tabBox(
  ...,
  id = NULL,
  selected = NULL,
  title = NULL,
  width = 6,
  height = NULL,
  side = c("left", "right")
)

Arguments

Value

A bslib::navset_card_tab() tag, wrapped in a shiny::column() unless width is NULL.

Examples

# Basic tab box with a title in the card header
tabBox(
  id = "quarterly",
  title = "Quarterly summary",
  shiny::tabPanel("Q1", shiny::p("Q1 content")),
  shiny::tabPanel("Q2", shiny::p("Q2 content"))
)

# Pre-select a tab and fix the card height (content scrolls inside)
tabBox(
  selected = "Q2",
  height   = "200px",
  shiny::tabPanel("Q1", shiny::p("Q1 content")),
  shiny::tabPanel("Q2", shiny::p("Q2 content"))
)

bslibdash tabsetPanel

Description

bslibdash tabsetPanel

Usage

tabsetPanel(
  ...,
  id = NULL,
  selected = NULL,
  type = c("tabs", "pills", "hidden"),
  .list = NULL
)

Arguments

Value

A shiny::tabsetPanel() tag that may be included in a Shiny UI.

Examples

tabsetPanel(
  id = "tabs",
  shiny::tabPanel("Overview", shiny::p("Overview content")),
  shiny::tabPanel("Details", shiny::p("Detail content"))
)

Create a toast

Description

Renders a notification through shiny::showNotification(). The default Shiny / bslib notification chrome (background, border, position, status color, dismiss button) is used as-is; toast() only adds support for the extra parameters below — header (title + optional icon), body, and subtitle footnote — emitted as flat blocks so they do not produce a card-in-notification (box-in-box) look. The type option in options controls the status color via Shiny's own notification statuses ("default", "message", "warning", "error").

Usage

toast(
  title,
  body = NULL,
  subtitle = NULL,
  options = NULL,
  session = shiny::getDefaultReactiveDomain()
)

Arguments

Value

The notification ID (string) returned by shiny::showNotification(), which can be used with shiny::removeNotification().

Examples

if (interactive()) {
shiny::shinyApp(
  ui = bslib::page_fluid(shiny::actionButton("show_toast", "Show toast")),
  server = function(input, output, session) {
    shiny::observeEvent(input$show_toast, {
      toast(
        title = "Heads up",
        body = "Background job finished with a warning.",
        options = list(type = "warning", delay = 3000),
        session = session
      )
    })
  }
)
}

Update the selected sidebar tab item

Description

This updates the hidden body tabset used by tabItems() and keeps the sidebar active item synchronized with the selected tab.

Usage

updateTabItems(
  session = shiny::getDefaultReactiveDomain(),
  inputId,
  selected = NULL
)

Arguments

Value

nothing. This function is called for its side-effects.

Examples

if (interactive()) {
shiny::shinyApp(
  ui = dashboardPage(
    header = dashboardHeader(title = "Demo"),
    sidebar = dashboardSidebar(
      sidebarMenu(
        id = "sidebarMenu",
        menuItem("Overview", tabName = "overview"),
        menuItem("Reports", tabName = "reports")
      )
    ),
    body = dashboardBody(
      shiny::actionButton("go_reports", "Go to reports"),
      tabItems(
        tabItem(tabName = "overview", shiny::h2("Overview")),
        tabItem(tabName = "reports", shiny::h2("Reports"))
      )
    )
  ),
  server = function(input, output, session) {
    shiny::observeEvent(input$go_reports, {
      updateTabItems(session, inputId = "sidebarMenu", selected = "reports")
    })
  }
)
}

Value box

Description

Value box

Usage

valueBox(value, subtitle, icon = NULL, color = "aqua", width = 4, href = NULL)

Arguments

Value

A bslib::value_box() tag, wrapped in a shiny::column() unless width is NULL.

Examples

valueBox(
  value = "128",
  subtitle = "Open tickets",
  icon = icon("inbox"),
  color = "primary"
)

Value box output

Description

Value box output

Usage

valueBoxOutput(outputId, width = 4)

Arguments

Value

A shiny::uiOutput() container to be filled by renderValueBox().

Examples

valueBoxOutput("tickets")