Getting Started

library(bs4Dashkit)

Overview

bs4Dashkit extends {bs4Dash} by standardizing branding, sidebar behavior, navbar utilities, and theme customization. Every feature is optional — you can adopt as little or as much as you need.

The package is organised around four areas:

  1. Brand and sidebar — dash_titles() + use_bs4Dashkit_core()
  2. Theming — use_dash_theme() and named presets
  3. Navbar — dash_nav_title(), refresh / help buttons, and user menu
  4. Footer — dash_footer() with flexible logo and text positioning

Minimal example

The smallest possible bs4Dashkit app requires exactly two calls beyond normal bs4Dash boilerplate:

library(shiny)
library(bs4Dash)
library(bs4Dashkit)

# 1. Build the brand object
ttl <- dash_titles("My Dashboard", icon = icon("cloud"))

ui <- bs4DashPage(
  title   = ttl$app_name,           # browser tab title
  header  = bs4DashNavbar(title = ttl$brand),
  sidebar = bs4DashSidebar(),
  body    = bs4DashBody(
    use_bs4Dashkit_core(ttl)        # 2. always the first call in body and called once
  )
)

server <- function(input, output, session) {}
shinyApp(ui, server)

dash_titles() accepts a single string and sensible defaults handle everything else. When no icon is supplied, the sidebar brand defaults to text-only modes. use_bs4Dashkit_core() loads the CSS dependencies, activates the sidebar brand mode, and applies the default theme.

If you prefer, you can also pass a simple shiny::icon() tag:

ttl <- dash_titles(
  brand_text = "My Dashboard",
  icon = icon("cloud")
)

dash_titles() — the brand object

dash_titles() is the single entry point for all brand-related configuration. It returns a named list with three slots:

Slot Where it goes
ttl$app_name bs4DashPage(title = ...)
ttl$brand bs4DashNavbar(title = ...); the sidebar brand mirrors this automatically in a standard bs4DashPage()
ttl$deps inside bs4DashBody(...) (handled automatically by use_bs4Dashkit_core()) 
ttl <- dash_titles(
  brand_text     = "OLTCR Dashboards",
  icon           = icon("project-diagram"),
  weight         = 700,
  effect         = "shimmer",          # "none" | "glow" | "shimmer" | "emboss"
  glow_color     = "#2f6f8f",
  size           = "20px",
  collapsed      = "icon-text",
  expanded       = "icon-text",
  collapsed_text = "OLT",              # shown when sidebar is collapsed
  expanded_text  = "OLTCR Dashboards",
  brand_divider  = TRUE
)

brand_text is the primary label for the app. It is always used for the navbar brand and is also the default expanded sidebar label. Use expanded_text only when the expanded sidebar should say something different, and use collapsed_text when the collapsed sidebar needs a shorter label. In practice, about 3 characters works best in the narrow collapsed sidebar.

If you want a fully textless icon brand, set brand_text = NULL and keep both sidebar states at "icon-only":

ttl <- dash_titles(
  brand_text = NULL,
  app_name   = "Icon Lab",
  icon       = icon("cloud"),
  collapsed  = "icon-only",
  expanded   = "icon-only"
)

Alternatively, use an image instead of a Font Awesome icon:

ttl <- dash_titles(
  brand_text = "My App",
  icon_img   = "logo.png",        # overrides `icon`
  icon_shape = "rounded"              # "circle" | "rounded" | "square"
)

NB: Place logo.png in your app’s www/ directory.

use_bs4Dashkit_core() — the core entry point

Always place this as the first element inside bs4DashBody(). It:

body = bs4DashBody(
  use_bs4Dashkit_core(ttl, preset = "professional"),
  # ... rest of your content
)

Available presets:

use_bs4Dashkit_core(ttl, preset = "professional")  # cool blue-grey (default)
use_bs4Dashkit_core(ttl, preset = "modern")        # brighter accent colours
use_bs4Dashkit_core(ttl, preset = "dark-lite")     # dark surfaces and lighter text
bs4dashkit_theme_presets()                         # list built-in presets

For a runnable template app, use:

app <- bs4dashkit_example_app()

For a fuller interactive playground that exercises sidebar states, hover behavior, presets, navbar controls, and footer styling together, use:

app <- bs4dashkit_demo_app()

You can also launch the packaged example directory directly:

shiny::runApp(system.file("examples", "real-shiny-app", package = "bs4Dashkit"))

That packaged example contains the full app code directly in inst/examples/real-shiny-app/app.R, so it can be read, modified, and run as a standalone reference app.

There is also a heavier shipped example that exercises the navbar title alignment controls, sidebar text sizing and weights, icon-only branding, and theme presets together:

shiny::runApp(system.file("examples", "test-all", package = "bs4Dashkit"))

Global options

Set package-level defaults once (e.g. in your global.R) so every app in a project inherits them:

options(
  bs4Dashkit.sidebar.collapsed = "icon-only",
  bs4Dashkit.sidebar.expanded  = "icon-text",
  bs4Dashkit.brand_divider     = TRUE,
  bs4Dashkit.accent            = "#2f6f8f",
  bs4Dashkit.theme_preset      = "professional"
)

If preset = NULL, use_bs4Dashkit_core() uses the package option bs4Dashkit.theme_preset (if set). If accent = NULL, it uses bs4Dashkit.accent.

use_bs4Dashkit_core(ttl, preset = NULL) # uses option if set
use_bs4Dashkit_core(ttl, accent = NULL) # uses option if set

dash_titles() reads these options when the corresponding arguments are NULL, so you can omit them from individual calls.

Troubleshooting

What next?