# Branding and Sidebar Modes

    library(bs4Dashkit)

## `dash_titles()` — full argument reference

`dash_titles()` is the single constructor for all branding and sidebar behaviour. It returns a list you destructure into the three placement slots described below.

    ttl <- dash_titles(
      brand_text     = "My App",       # primary navbar label and default expanded sidebar label
      app_name       = NULL,            # browser tab title; defaults to brand_text
      icon           = icon("shield-halved"), # or a Font Awesome name like "shield-halved"
      icon_img       = NULL,            # image path — overrides icon when set
      icon_shape     = "circle",        # "circle" | "rounded" | "square"
      icon_size      = NULL,            # CSS size e.g. "22px"
      icon_color     = NULL,            # CSS color for FA icon e.g. "#2f6f8f"
      weight         = 700,             # CSS font-weight
      spacing        = "-0.02em",       # CSS letter-spacing
      size           = NULL,            # CSS font-size for label e.g. "13px"
      italic         = FALSE,
      font_family    = NULL,            # CSS font-family string
      color          = NULL,            # solid label colour; ignored when gradient set
      gradient       = NULL,            # c("#hex1", "#hex2") — sets gradient effect
      effect         = "none",          # "none" | "glow" | "shimmer" | "emboss"
      glow_color     = NULL,            # colour for glow / shimmer
      collapsed      = "icon-only",     # brand mode when sidebar is collapsed
      expanded       = "icon-text",     # brand mode when sidebar is expanded
      collapsed_text = NULL,            # optional short label for collapsed icon-text/text-only
      expanded_text  = NULL             # optional expanded override; defaults to brand_text
    )

### Return value

Slot | Type | Placement
--- | --- | ---
`ttl$app_name` | `character` | `bs4DashPage(title = ttl$app_name)`
`ttl$brand` | `tagList` | `bs4DashNavbar(title = ttl$brand)`; the sidebar brand mirrors this automatically in a standard `bs4DashPage()`
`ttl$deps` | `tagList` | inside `bs4DashBody(...)` — handled by `use_bs4Dashkit_core()`

## Icon options

### Font Awesome icon

    ttl <- dash_titles(
      brand_text = "My App",
      icon       = icon("chart-line"),
      icon_color = "#2f6f8f",
      icon_size  = "20px"
    )

### Image logo

`icon_img` overrides `icon`. The path is relative to your app’s `www/` folder.

    ttl <- dash_titles(
      brand_text = "My App",
      icon_img   = "logo.png",    # served from www/logo.png
      icon_shape = "rounded",     # "circle" | "rounded" | "square"
      icon_size  = "28px"
    )

## Label effects

    # No effect (plain text)
    ttl <- dash_titles(brand_text = "My App", effect = "none")

    # Glow
    ttl <- dash_titles(brand_text = "My App", effect = "glow", glow_color = "#2f6f8f")

    # Shimmer (animated gradient sweep)
    ttl <- dash_titles(brand_text = "My App", effect = "shimmer", glow_color = "#5ba3c9")

    # Emboss (subtle relief shadow)
    ttl <- dash_titles(brand_text = "My App", effect = "emboss")

    # Two-colour gradient (effect argument is ignored when gradient is set)
    ttl <- dash_titles(brand_text = "My App", gradient = c("#2f6f8f", "#5ba3c9"))

## Sidebar modes

The sidebar brand area can show different content depending on whether the sidebar is collapsed or expanded. There are three modes, combinable independently for each state.

Mode | What renders
--- | ---
`"icon-only"` | Icon or image only — no text
`"icon-text"` | Icon plus a text label
`"text-only"` | Text label only — no icon

`brand_text` is the default expanded sidebar label. Reach for `collapsed_text` when the narrow sidebar needs a shorter label, and use `expanded_text` only when the expanded sidebar should differ from `brand_text`. In practice, collapsed labels work best at about 3 characters or fewer. When `collapsed = "text-only"`, the text is centered in the collapsed brand strip.

### Common combinations

    # Compact when collapsed, full when expanded (recommended default)
    ttl <- dash_titles(
      brand_text     = "Test Dashboard",
      icon           = icon("project-diagram"),
      collapsed      = "icon-only",
      expanded       = "icon-text"
    )

    # Show abbreviated text when collapsed
    ttl <- dash_titles(
      brand_text     = "OLTCR Dashboards",
      icon           = icon("project-diagram"),
      collapsed      = "icon-text",
      expanded       = "icon-text",
      collapsed_text = "OLT",            # about 3 chars works best
      expanded_text  = "OLTCR Dashboards"
    )

    # Icon only in both states
    ttl <- dash_titles(
      brand_text = "OLTCR Dashboards",
      icon       = icon("project-diagram"),
      collapsed  = "icon-only",
      expanded   = "icon-only"
    )

    # Textless icon brand in both states
    ttl <- dash_titles(
      brand_text = NULL,
      app_name   = "Icon Lab",
      icon       = icon("cloud"),
      collapsed  = "icon-only",
      expanded   = "icon-only"
    )

## Hover-expand sidebar

`use_bs4Dashkit_core()` includes hover-expand sidebar behavior by default. When the sidebar is collapsed on desktop, it expands temporarily on mouse hover.

Configure it with the sizing arguments:

    body = bs4DashBody(
      use_bs4Dashkit_core(
        ttl,
        topbar_h = 56,
        collapsed_w = 4.2,
        expanded_w = 250
      ),
      # ...
    )

If you are not using use_bs4Dashkit_core(), you can enable hover-expand directly:

    body = bs4DashBody(
      use_bs4Dashkit(),
      ttl$deps,
      use_dash_sidebar_behavior(),
      # ...
    )

## Brand divider

A subtle horizontal rule between the brand mark and the sidebar menu:

    ttl <- dash_titles(
      brand_text    = "My App",
      icon          = icon("chart-line"),
      brand_divider = TRUE           # default TRUE (can be disabled)
    )

    # Or control it independently
    use_dash_sidebar_brand_divider()

## Global options

Set defaults for your whole project in `global.R` or `app.R` before calling `dash_titles()`:

    options(
      bs4Dashkit.sidebar.collapsed = "icon-only",
      bs4Dashkit.sidebar.expanded  = "icon-text",
      bs4Dashkit.brand_divider     = TRUE
    )

`dash_titles()` reads these options when the corresponding arguments are `NULL`, so individual apps only need to specify what differs from the project default.

## Putting it together

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

    ttl <- dash_titles(
      brand_text     = "Test Dashboard",
      icon           = icon("project-diagram"),
      weight         = 700,
      effect         = "shimmer",
      glow_color     = "#2f6f8f",
      size           = "20px",
      collapsed      = "icon-text",
      expanded       = "icon-text",
      collapsed_text = "DT",
      expanded_text  = "Dashboard",
      brand_divider  = TRUE
    )

    ui <- bs4DashPage(
      title  = ttl$app_name,
      header = bs4DashNavbar(title = ttl$brand, skin = "light"),
      sidebar = bs4DashSidebar(
        skin = "light",
        bs4SidebarMenu(
          bs4SidebarMenuItem("Dashboard", tabName = "dash", icon = icon("gauge-high")),
          bs4SidebarMenuItem("Projects",  tabName = "proj", icon = icon("folder-open"))
        )
      ),
      body = bs4DashBody(
        bs4TabItems(
          bs4TabItem(tabName = "dash", h3("Dashboard")),
          bs4TabItem(tabName = "proj", h3("Projects"))
        )
      )
    )

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