Help for package bs4Dashkit

Type:

Package

Title:

Branding, Theme Application and Navigation Utilities for 'bs4Dash' Dashboards

Version:

0.1.0

Description:

Provides branding, theme application, and navigation utilities for applications built with 'bs4Dash' and 'shiny'. Supports configurable sidebar brand display modes, hover-expand behavior, and theme customization using CSS variables. Includes standardized navigation components such as refresh and help controls, along with helpers for common navigation bar and footer layouts.

License:

MIT + file LICENSE

URL:

https://github.com/PrigasG/bs4Dashkit

BugReports:

https://github.com/PrigasG/bs4Dashkit/issues

Imports:

bs4Dash, digest, htmltools, shiny

Suggests:

knitr, rmarkdown, testthat (≥ 3.0.0)

VignetteBuilder:

knitr, rmarkdown

Config/testthat/edition:

Encoding:

UTF-8

Language:

en-US

RoxygenNote:

7.3.3

NeedsCompilation:

Packaged:

2026-03-06 14:01:02 UTC; priga

Author:

George Arthur [aut, cre]

Maintainer:

George Arthur <prigasgenthian48@gmail.com>

Repository:

CRAN

Date/Publication:

2026-03-10 21:10:15 UTC

Create sidebar / navbar brand UI

Description

Produces an icon + text block for bs4Dash brand slots with rich styling and optional visual effects. Supports Font Awesome icons or image logos.

Usage

dash_brand_ui(
  brand_text,
  icon = NULL,
  icon_img = NULL,
  icon_shape = c("circle", "rounded", "square"),
  icon_size = NULL,
  icon_color = NULL,
  weight = 700,
  spacing = "-0.02em",
  size = NULL,
  italic = FALSE,
  font_family = NULL,
  color = NULL,
  gradient = NULL,
  effect = c("none", "glow", "shimmer", "emboss"),
  glow_color = NULL
)

Arguments

brand_text

Visible brand label (character)

icon

Font Awesome icon name e.g. "shield-halved". NULL for none.

icon_img

URL or www-relative path to an image logo. Overrides icon when both are supplied.

icon_shape

Shape mask for image icons: "circle", "rounded", "square". Ignored for FA icons. Default "circle".

icon_size

Size of icon/image as CSS string e.g. "20px", "1.3em". NULL = inherits sidebar default.

icon_color

CSS color for FA icon e.g. "#2f6f8f". NULL = inherit. For image icons, applies a CSS tint via mix-blend-mode (subtle).

weight

CSS font-weight: numeric or keyword. Default 700.

spacing

CSS letter-spacing. Default "-0.02em".

size

CSS font-size for label e.g. "13px". NULL = inherit.

italic

Logical. Italicise the label. Default FALSE.

font_family

CSS font-family string e.g. "'Inter', sans-serif".

color

Solid CSS color for label text. NULL = inherit. Ignored when gradient is set.

gradient

Character vector of 2 hex colors for gradient text effect e.g. c("#2f6f8f", "#5ba3c9"). Automatically enables effect = "gradient".

effect

Visual effect on label: "none", "glow", "shimmer", "emboss". "gradient" is set automatically when gradient is supplied.

glow_color

CSS color for glow effect. Defaults to first gradient color or color or the package accent blue.

Value

A named list with components:

ui: A shiny.tag.list containing the generated brand UI.
dep: A shiny.tag object containing scoped CSS dependencies for the brand styling.

Standard footer for bs4Dash dashboards

Description

Standard footer for bs4Dash dashboards

Usage

dash_footer(
  logo_src = NULL,
  left_text = NULL,
  right_text = NULL,
  right_date = NULL,
  date_format = "%B %d, %Y",
  logo_height = 20,
  logo_position = c("left", "right"),
  fixed = TRUE
)

Arguments

logo_src

Path under ⁠www/⁠ or an external URL.

left_text

Text rendered on the left side (optional).

right_text

Text rendered on the right side (optional).

right_date

Optional Date to render on the right. Ignored if right_text is set.

date_format

Format used when right_date is provided.

logo_height

Height in px for the logo image.

logo_position

Where the logo should appear: "left" or "right".

fixed

Logical. Fixed footer (TRUE/FALSE).

Value

A shiny.tag object representing a bs4DashFooter UI component.

Navbar help button (styled)

Description

Navbar help button (styled)

Usage

dash_nav_help_button(
  id,
  label = "Help",
  icon = "circle-question",
  class = NULL,
  ...
)

Arguments

id

inputId for actionButton

label

Button label

icon

Font Awesome icon name

class

Additional classes

...

Passed to shiny::actionButton

Value

A shiny.tag object representing a styled navbar action button.

Wrap a navbar control in a list item (bs4Dash rightUi convention)

Description

Wrap a navbar control in a list item (bs4Dash rightUi convention)

Usage

dash_nav_item(...)

Arguments

...

UI elements

Value

A shiny.tag object containing an HTML list item for use in bs4Dash navbar UI.

Navbar refresh button (styled)

Description

Navbar refresh button (styled)

Usage

dash_nav_refresh_button(
  id,
  label = "Refresh",
  icon = "rotate-right",
  class = NULL,
  ...
)

Arguments

id

inputId for actionButton

label

Button label

icon

Font Awesome icon name

class

Additional classes

...

Passed to shiny::actionButton

Value

A shiny.tag object representing a styled navbar refresh button.

Navbar title (center, right, or left)

Description

Creates a consistent title block for bs4Dash navbars, with optional subtitle and icon. Alignment can be "center", "right", or "left".

Usage

dash_nav_title(
  title,
  subtitle = NULL,
  icon = NULL,
  align = c("center", "right", "left")
)

Arguments

title

Main title (character or tag)

subtitle

Optional subtitle (character or tag)

icon

Optional fontawesome icon name, e.g. "shield-halved"

align

One of c("center","right","left")

Details

IMPORTANT:

align = "left" is intended to be placed in dashboardHeader(leftUi = ...)
align = "right" is intended to be placed in dashboardHeader(rightUi = ...)
align = "center" can be placed anywhere (it is positioned by CSS/JS)

Value

A shiny.tag object representing the navbar title UI.

Dashboard brand and sidebar configuration

Description

Single entry point for branding and sidebar brand behavior. Creates a reusable object you place into bs4DashPage(), bs4DashNavbar(), and bs4DashBody().

Usage

dash_titles(
  brand_text,
  app_name = NULL,
  icon = NULL,
  icon_img = NULL,
  icon_shape = c("circle", "rounded", "square"),
  icon_size = NULL,
  icon_color = NULL,
  weight = 700,
  spacing = "-0.02em",
  size = NULL,
  italic = FALSE,
  font_family = NULL,
  color = NULL,
  gradient = NULL,
  effect = c("none", "glow", "shimmer", "emboss"),
  glow_color = NULL,
  collapsed = NULL,
  expanded = NULL,
  collapsed_text = NULL,
  expanded_text = NULL,
  brand_divider = NULL,
  debug = NULL
)

Arguments

brand_text

Visible brand label shown in the navbar/sidebar.

app_name

Browser tab title. If NULL, defaults to brand_text.

icon

Font Awesome icon name for the brand (e.g. "project-diagram"). Ignored when icon_img is supplied.

icon_img

Path (www relative) or URL to an image logo. Overrides icon.

icon_shape

Shape mask for image logos. One of "circle", "rounded", "square".

icon_size

CSS size for the icon/image (e.g. "20px", "1.2em").

icon_color

CSS color for the Font Awesome icon. For image icons, a subtle tint may be applied.

weight

CSS font-weight for the brand text.

spacing

CSS letter-spacing for the brand text.

size

CSS font-size for the brand text (e.g. "14px").

italic

Logical. If TRUE, renders brand text in italics.

font_family

CSS font-family string (e.g. "'Inter', sans-serif").

color

Solid CSS text color for the brand label (ignored when gradient is set).

gradient

Character vector of length 2 giving gradient colors for the brand label. When set, gradient styling is applied.

effect

Visual effect for the brand label. One of "none", "glow", "shimmer", "emboss". If gradient is set, gradient styling is used.

glow_color

Color used for glow/shimmer effects (when applicable).

collapsed

Sidebar brand mode when the sidebar is collapsed. One of "icon-only", "icon-text", "text-only". If NULL, uses option bs4Dashkit.sidebar.collapsed.

expanded

Sidebar brand mode when the sidebar is expanded. One of "icon-only", "icon-text", "text-only". If NULL, uses option bs4Dashkit.sidebar.expanded.

collapsed_text

Short label used in collapsed mode (recommended <= 8 chars).

expanded_text

Label used in expanded mode (recommended <= 30 chars).

brand_divider

Logical. If TRUE, shows a divider under the brand block. If NULL, uses option bs4Dashkit.brand_divider.

debug

Logical. If TRUE, emits console warnings for missing icons, etc. If NULL, uses option bs4Dashkit.debug.

Value

A named list with components:

app_name: A character string for use in bs4DashPage(title = ...).
brand: A shiny.tag object for use in bs4DashNavbar(title = ...) and, if desired, as sidebar title UI.
deps: A shiny.tag.list containing CSS and JavaScript dependencies to include once in bs4DashBody(...).

Standard wrapper for a navbar user menu

Description

Standard wrapper for a navbar user menu

Usage

dash_user_menu(ui)

Arguments

ui

A UI object, typically a dropdown menu produced by the app

Value

A shiny.tag object representing the user menu UI for the navbar.

Internal helper: get bs4Dashkit option with fallback

Description

Internal helper: get bs4Dashkit option with fallback

Usage

dashkit_opt(name, default = NULL)

Ensure bs4Dashkit resource path is registered

Description

Ensure bs4Dashkit resource path is registered

Usage

dashkit_register_resources()

Load core CSS and JS for bs4Dashkit

Description

Adds the package's bundled CSS (core, theme, sidebar) and optional JS helpers.

Usage

use_bs4Dashkit(include_center_js = TRUE)

Arguments

include_center_js

Logical. If TRUE (default), also includes the JavaScript helper that supports the centered navbar title layout.

Value

A htmltools::tagList containing an htmltools::htmlDependency for the package CSS and optional JavaScript helpers.

Load bs4Dashkit core dependencies in one call

Description

Recommended entry point for bs4Dashkit in bs4DashBody().

Usage

use_bs4Dashkit_core(
  ttl,
  preset = NULL,
  accent = NULL,
  ...,
  topbar_h = 56,
  collapsed_w = 4.2,
  expanded_w = 250
)

Arguments

ttl

Output from dash_titles()

preset

Optional theme preset name (e.g. "professional"). If NULL, uses option bs4Dashkit.theme_preset (if set).

accent

Optional accent override. If NULL, uses option bs4Dashkit.accent. If preset is used, this overrides the preset accent.

...

Optional overrides passed to use_dash_theme_preset() when preset is used.

topbar_h

Height (px) for topbar + brand strip

collapsed_w

Sidebar collapsed width (rem)

expanded_w

Sidebar expanded width (px)

Value

A shiny.tag.list containing core CSS and/or JavaScript dependencies for bs4Dashkit.

Sidebar behavior: icon-only collapse + hover expand + ellipsis labels

Description

Sidebar behavior: icon-only collapse + hover expand + ellipsis labels

Usage

use_dash_sidebar_behavior(topbar_h = 56, collapsed_w = 4.2, expanded_w = 250)

Arguments

topbar_h

Height in px for navbar and sidebar brand strip

collapsed_w

Width for icon-only sidebar (rem)

expanded_w

Expanded sidebar width (px)

Value

A shiny.tag or shiny.tag.list containing sidebar behavior dependencies to include in the UI.

Toggle the sidebar header divider (line under the brand area)

Description

Toggle the sidebar header divider (line under the brand area)

Usage

use_dash_sidebar_brand_divider(show = TRUE)

Arguments

show

Logical. TRUE keeps divider (default). FALSE hides it.

Value

If show is TRUE, an empty shiny.tag.list. If show is FALSE, a shiny.tag object containing CSS that hides the sidebar brand divider.

Set sidebar brand display mode for expanded and collapsed states

Description

Controls icon visibility, text visibility, and text content in both collapsed and expanded sidebar states.

Usage

use_dash_sidebar_brand_mode(
  icon = NULL,
  collapsed = c("icon-only", "icon-text", "text-only"),
  expanded = c("icon-text", "icon-only", "text-only"),
  collapsed_text = NULL,
  expanded_text = NULL,
  debug = FALSE
)

Arguments

icon

Font Awesome icon name used in the brand, e.g. "shield-halved". Required when any mode includes "icon".

collapsed

Display mode when sidebar is collapsed: "icon-only", "icon-text", or "text-only"

expanded

Display mode when sidebar is expanded: "icon-text", "icon-only", or "text-only"

collapsed_text

Short label for collapsed "icon-text" or "text-only" mode. Keep <= 8 chars. NULL falls back to original DOM text (CSS truncates).

expanded_text

Label for expanded "icon-text" or "text-only" mode. Keep <= 30 chars. NULL falls back to original DOM text.

debug

Logical. If TRUE, prints helpful messages to the browser console for diagnosing missing icons or brand label elements.

Details

Modes:

"icon-only" : icon shown, label hidden — requires icon
"text-only" : label shown, icon hidden — collapsed_text / expanded_text optional
"icon-text" : both shown — requires icon; text args optional

Value

A shiny.tag or shiny.tag.list containing sidebar brand mode styling or dependencies.

Apply a theme via CSS variables

Description

Sets bs4Dashkit CSS custom properties (variables) for background, surfaces, borders, text, and accent color.

Usage

use_dash_theme(
  bg = "#f5f6f8",
  surface = "#ffffff",
  border = "#e2e3e7",
  text = "#1d1f23",
  muted = "#6b6f76",
  accent = "#2f6f8f",
  radius = 12,
  shadow = "0 1px 3px rgba(0,0,0,0.07)"
)

Arguments

bg

Page background color.

surface

Card and panel background color.

border

Border color used on cards, separators, and outlines.

text

Primary text color.

muted

Muted text color.

accent

Accent color used for highlights and emphasis.

radius

Corner radius in pixels.

shadow

Box shadow CSS string used for cards and surfaces.

Value

A shiny.tag.list containing stylesheet dependencies and inline CSS variables for the app theme.

Apply a theme preset

Description

Apply a theme preset

Usage

use_dash_theme_preset(preset = c("professional", "modern", "dark-lite"), ...)

Arguments

preset

One of: "professional", "modern", "dark-lite"

...

Passed to use_dash_theme() to override preset values

Value

A shiny.tag or shiny.tag.list containing theme preset CSS and related UI dependencies.