Type: Package
Title: Branding, Theme Application and Navigation Utilities for 'bs4Dash' Dashboards
Version: 0.2.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: 3
Encoding: UTF-8
Language: en-US
RoxygenNote: 7.3.3
NeedsCompilation: no
Packaged: 2026-04-21 10:00:33 UTC; priga
Author: George Arthur [aut, cre]
Maintainer: George Arthur <prigasgenthian48@gmail.com>
Repository: CRAN
Date/Publication: 2026-04-21 18:02:19 UTC

Interactive bs4Dashkit demo app

Description

Returns a richer runnable shiny.appobj for testing sidebar brand states, hover-expand behavior, theme presets, navbar controls, and footer styling in one place.

Usage

bs4dashkit_demo_app()

Value

A shiny.appobj.

Minimal bs4Dashkit example app

Description

Returns a tiny runnable shiny.appobj that demonstrates the recommended dash_titles() plus use_bs4Dashkit_core() flow.

Usage

bs4dashkit_example_app()

Value

A shiny.appobj.

Built-in bs4Dashkit theme presets

Description

Returns the theme presets shipped with bs4Dashkit so they are easy to discover in code completion, validation errors, and documentation.

Usage

bs4dashkit_theme_presets(values = FALSE)

Arguments

values

Logical. If TRUE, also returns the preset theme values as a list-column named tokens.

Value

A data frame with one row per preset and columns preset and description. If values = TRUE, the returned data frame also includes a tokens list-column.

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). May be NULL for icon-only brands.

icon

Font Awesome icon name e.g. "shield-halved", or a simple icon("shield-halved") tag. 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.

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 Font Awesome icon name or simple icon("shield-halved") tag.

align

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

Details

IMPORTANT:

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,
  collapsed_text_size = NULL,
  expanded_text_size = NULL,
  collapsed_text_weight = NULL,
  expanded_text_weight = NULL,
  brand_divider = NULL,
  debug = NULL
)

Arguments

brand_text

Visible brand label shown in the navbar/sidebar. May be NULL only when both sidebar modes are "icon-only" and an icon or image logo is supplied.

app_name

Browser tab title. If NULL, defaults to brand_text, or "bs4Dashkit" when brand_text is empty.

icon

Font Awesome icon name for the brand (for example "project-diagram") or a simple icon("project-diagram") tag. 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).

collapsed_text_size

Optional CSS font-size applied only to the sidebar brand label while collapsed (for example "11px" or "0.75rem").

expanded_text_size

Optional CSS font-size applied only to the sidebar brand label while expanded.

collapsed_text_weight

Optional CSS font-weight applied only to the sidebar brand label while collapsed.

expanded_text_weight

Optional CSS font-weight applied only to the sidebar brand label while expanded.

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 = ...). In a standard bs4DashPage(), the sidebar brand mirrors the navbar brand automatically.

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(). For most apps, this should be the first element inside 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,
  collapsed_text_size = NULL,
  expanded_text_size = NULL,
  collapsed_text_weight = NULL,
  expanded_text_weight = NULL,
  debug = FALSE
)

Arguments

icon

Font Awesome icon name used in the brand, e.g. "shield-halved", or a simple icon("shield-halved") tag. 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 the current brand label already present in the DOM. When using dash_titles(), the higher-level helper usually resolves this to brand_text for visible text modes.

expanded_text

Label for expanded "icon-text" or "text-only" mode. Keep <= 30 chars. NULL falls back to the current brand label already present in the DOM. When using dash_titles(), the higher-level helper usually resolves this to brand_text for visible text modes.

collapsed_text_size

Optional CSS font-size applied to the sidebar brand label while collapsed.

expanded_text_size

Optional CSS font-size applied to the sidebar brand label while expanded.

collapsed_text_weight

Optional CSS font-weight applied to the sidebar brand label while collapsed.

expanded_text_weight

Optional CSS font-weight applied to the sidebar brand label while expanded.

debug

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

Details

Modes:

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",
  accent_soft = "#e8f1f5",
  navbar_bg = "#ffffff",
  navbar_text = "#1d1f23",
  sidebar_bg = "#ffffff",
  sidebar_text = "#1d1f23",
  sidebar_hover = "#eef4f7",
  footer_bg = "#ffffff",
  footer_text = "#6b6f76",
  success = "#2d8a56",
  warning = "#c37a14",
  danger = "#b94a48",
  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.

accent_soft

Softer accent tone used for subtle fills, hover states, and focus treatments.

navbar_bg

Navbar background color.

navbar_text

Navbar text color.

sidebar_bg

Sidebar background color.

sidebar_text

Sidebar text color.

sidebar_hover

Sidebar hover and active background color.

footer_bg

Footer background color.

footer_text

Footer text color.

success

Success accent color.

warning

Warning accent color.

danger

Danger accent color.

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.