Package 'dashboardr'

Description

S3 method for combining content_collection objects using +. Preserves all attributes including lazy loading settings.

Usage

## S3 method for class 'content_collection'
e1 + e2

Arguments

Value

Combined content_collection

Description

S3 method that allows combining two viz_collection objects using the + operator. This is a convenient shorthand for combine_content. Preserves all attributes including lazy loading settings.

Usage

## S3 method for class 'viz_collection'
e1 + e2

Arguments

Details

The + operator provides an intuitive way to combine visualization collections:

• All visualizations from both collections are merged

• Tabgroup labels are combined (e2 labels take precedence for duplicates)

• Insertion indices are renumbered to maintain proper ordering

• All attributes (lazy loading, etc.) are preserved

Value

A new viz_collection containing all visualizations from both collections, with merged tabgroup labels and renumbered insertion indices.

See Also

combine_content for the underlying function.

Examples

## Not run: 
# Create two separate visualization collections
viz1 <- create_viz() %>%
  add_viz(type = "histogram", x_var = "age", title = "Age Distribution")

viz2 <- create_viz() %>%
  add_viz(type = "histogram", x_var = "income", title = "Income Distribution")

# Combine using + operator
combined <- viz1 + viz2

# Equivalent to:
combined <- combine_content(viz1, viz2)

## End(Not run)

Description

Add collapsible accordion/details section

Usage

add_accordion(
  content,
  title,
  text,
  open = FALSE,
  tabgroup = NULL,
  show_when = NULL
)

Arguments

Value

Updated content_collection

Description

Add a status badge

Usage

add_badge(content, text, color = "primary", tabgroup = NULL, show_when = NULL)

Arguments

Description

Add callout box

Usage

add_callout(
  x,
  text,
  type = c("note", "tip", "warning", "caution", "important"),
  title = NULL,
  icon = NULL,
  collapse = FALSE,
  tabgroup = NULL,
  show_when = NULL
)

Arguments

Value

Updated content_collection

Description

Add callout boxes directly to a page object.

Usage

add_callout.page_object(
  page,
  text,
  type = "note",
  title = NULL,
  tabgroup = NULL,
  show_when = NULL
)

Arguments

Value

The updated page_object

Description

Add card

Usage

add_card(
  content,
  text,
  title = NULL,
  footer = NULL,
  tabgroup = NULL,
  show_when = NULL
)

Arguments

Value

Updated content_collection

Description

Add code block

Usage

add_code(
  content,
  code,
  language = "r",
  caption = NULL,
  filename = NULL,
  tabgroup = NULL,
  show_when = NULL
)

Arguments

Value

Updated object (same type as input)

Description

Add one or more pre-built content collections (from create_viz/create_content) to a page. Use this when you have complex content built separately.

Usage

add_content(page, ...)

Arguments

Value

The updated page_object

Examples

## Not run: 
# Add a single collection
page %>% add_content(my_viz)

# Add multiple collections at once
page %>% add_content(viz1, viz2, viz3)

## End(Not run)

Description

Universal function for adding any type of page to the dashboard. Can create landing pages, analysis pages, about pages, or any combination of text and visualizations. All content is markdown-compatible.

Usage

add_dashboard_page(
  proj,
  name,
  data = NULL,
  data_path = NULL,
  template = NULL,
  params = list(),
  visualizations = NULL,
  content = NULL,
  text = NULL,
  icon = NULL,
  is_landing_page = FALSE,
  show_in_nav = TRUE,
  tabset_theme = NULL,
  tabset_colors = NULL,
  navbar_align = c("left", "right"),
  overlay = FALSE,
  overlay_theme = c("light", "glass", "dark", "accent"),
  overlay_text = "Loading",
  overlay_duration = 2200,
  lazy_load_charts = NULL,
  lazy_load_margin = NULL,
  lazy_load_tabs = NULL,
  lazy_debug = NULL,
  pagination_separator = NULL,
  time_var = NULL,
  slug = NULL
)

Arguments

Value

The updated dashboard_project object

Examples

## Not run: 
# Landing page
dashboard <- create_dashboard("test") %>%
  add_page("Welcome", text = "# Welcome\n\nThis is the main page.", is_landing_page = TRUE)

# Analysis page with data and visualizations
dashboard <- dashboard %>%
  add_page("Demographics", data = survey_data, visualizations = demo_viz)

# Text-only about page
dashboard <- dashboard %>%
  add_page("About", text = "# About This Study\n\nThis dashboard shows...")

# Mixed content page
dashboard <- dashboard %>%
  add_page("Results", text = "# Key Findings\n\nHere are the results:",
           visualizations = results_viz, icon = "ph:chart-line")

# Page with explicit time variable for metric switching
dashboard <- dashboard %>%
  add_page("Trends", data = trend_data, visualizations = trend_viz, time_var = "decade")

## End(Not run)

Description

Add horizontal divider

Usage

add_divider(content, style = "default", tabgroup = NULL, show_when = NULL)

Arguments

Value

Updated object (same type as input)

Description

Add DT datatable

Usage

add_DT(
  content,
  table_data,
  options = NULL,
  tabgroup = NULL,
  filter_vars = NULL,
  show_when = NULL,
  ...
)

Arguments

Value

Updated content_collection

Examples

## Not run: 
# Option 1: Pass a styled DT object
my_dt <- DT::datatable(
  mtcars,
  options = list(pageLength = 10),
  filter = 'top',
  rownames = FALSE
)

content <- create_content() %>%
  add_DT(my_dt)
  
# Option 2: Pass a data frame with options
content <- create_content() %>%
  add_DT(mtcars, options = list(pageLength = 5, scrollX = TRUE))

## End(Not run)

Description

Convenience wrapper around add_widget for echarts4r objects.

Usage

add_echarts(
  content,
  chart,
  title = NULL,
  height = NULL,
  tabgroup = NULL,
  filter_vars = NULL,
  show_when = NULL
)

Arguments

Value

Updated content object

Description

A convenience wrapper around add_input for common filtering use cases. Options are automatically derived from the data column specified by filter_var. All values are selected by default.

Usage

add_filter(
  content,
  filter_var,
  label = NULL,
  type = c("checkbox", "select", "radio"),
  ...
)

Arguments

Value

Updated content_collection

Examples

## Not run: 
# Simplest usage - just specify the column!
content <- create_content(data = mydata) %>%
  add_sidebar() %>%
    add_filter(filter_var = "education") %>%
    add_filter(filter_var = "gender") %>%
  end_sidebar() %>%
  add_viz(type = "stackedbar", x_var = "region", stack_var = "outcome")

## End(Not run)

Description

Convenience wrapper around add_widget for ggiraph objects.

Usage

add_ggiraph(
  content,
  plot,
  title = NULL,
  height = NULL,
  tabgroup = NULL,
  filter_vars = NULL,
  show_when = NULL
)

Arguments

Value

Updated content object

Description

Embed a ggplot2 object directly into a dashboard page. The plot is rendered as a static image via Quarto's built-in knitr graphics device.

Usage

add_ggplot(
  content,
  plot,
  title = NULL,
  height = NULL,
  width = NULL,
  tabgroup = NULL,
  show_when = NULL
)

Arguments

Value

Updated content object

Description

Add gt table

Usage

add_gt(content, gt_object, caption = NULL, tabgroup = NULL, show_when = NULL)

Arguments

Value

Updated content_collection

Examples

## Not run: 
# Option 1: Pass a styled gt object
my_table <- gt::gt(mtcars) %>%
  gt::tab_header(title = "Cars") %>%
  gt::fmt_number(columns = everything(), decimals = 1)

content <- create_content() %>%
  add_gt(my_table)
  
# Option 2: Pass a data frame (auto-converted)
content <- create_content() %>%
  add_gt(mtcars, caption = "Motor Trend Cars")

## End(Not run)

Description

Add a pre-built highcharter chart to your dashboard. This allows you to create complex, customized highcharter visualizations and include them directly without using dashboardr's viz_* functions.

Usage

add_hc(
  content,
  hc_object,
  height = NULL,
  tabgroup = NULL,
  filter_vars = NULL,
  show_when = NULL
)

Arguments

Value

Updated content object

Examples

## Not run: 
library(highcharter)

# Create a custom highcharter chart
my_chart <- hchart(mtcars, "scatter", hcaes(x = wt, y = mpg, group = cyl)) %>%
  hc_title(text = "Custom Scatter Plot") %>%
  hc_subtitle(text = "Made with highcharter") %>%
  hc_add_theme(hc_theme_smpl())

# Add it to a page
page <- create_page("Charts") %>%
  add_hc(my_chart) %>%
  add_hc(another_chart, height = "500px", tabgroup = "My Charts")

## End(Not run)

Description

Add raw HTML content

Usage

add_html(content, html, tabgroup = NULL, show_when = NULL)

Arguments

Description

Add iframe

Usage

add_iframe(
  content,
  src,
  height = "500px",
  width = "100%",
  style = NULL,
  tabgroup = NULL,
  show_when = NULL
)

Arguments

Value

Updated content_collection

Description

Adds an image block to a content collection. Can be used standalone or in a pipe. Supports viz_collection as first argument for seamless piping.

Usage

add_image(
  content_collection = NULL,
  src,
  alt = NULL,
  caption = NULL,
  width = NULL,
  height = NULL,
  align = c("center", "left", "right"),
  link = NULL,
  class = NULL,
  tabgroup = NULL,
  show_when = NULL
)

Arguments

Value

Updated content_collection object

Examples

## Not run: 
# Standalone
img <- add_image(src = "logo.png", alt = "Logo")

# Pipe with content
content <- create_content() %>%
  add_text("Welcome!") %>%
  add_image(src = "chart.png", alt = "Chart")

# With tabgroup
content <- create_content() %>%
  add_image(src = "chart.png", alt = "Chart", tabgroup = "Gallery")

# Pipe directly from viz
content <- create_viz() %>%
  add_viz(type = "bar", x_var = "category") %>%
  add_image(src = "logo.png", alt = "Logo")

## End(Not run)

Description

Adds an input widget that filters Highcharts visualizations on the page. Supports various input types: dropdowns, checkboxes, radio buttons, switches, sliders, text search, number inputs, and button groups.

Usage

add_input(
  content,
  input_id,
  label = NULL,
  type = c("select_multiple", "select_single", "checkbox", "radio", "switch", "slider",
    "text", "number", "button_group", "date", "daterange"),
  filter_var,
  options = NULL,
  options_from = NULL,
  default_selected = NULL,
  placeholder = "Select...",
  width = "300px",
  min = 0,
  max = 100,
  step = 1,
  value = NULL,
  default_value = NULL,
  show_value = TRUE,
  inline = TRUE,
  stacked = FALSE,
  stacked_align = c("center", "left", "right"),
  group_align = c("left", "center", "right"),
  ncol = NULL,
  nrow = NULL,
  columns = NULL,
  toggle_series = NULL,
  override = FALSE,
  labels = NULL,
  size = c("md", "sm", "lg"),
  help = NULL,
  disabled = FALSE,
  add_all = FALSE,
  add_all_label = "All",
  mt = NULL,
  mr = NULL,
  mb = NULL,
  ml = NULL,
  tabgroup = NULL,
  icons = NULL,
  show_when = NULL,
  .linked_parent_id = NULL,
  .options_by_parent = NULL
)

Arguments

Value

Updated content_collection or input_row_container

Examples

## Not run: 
# Dropdown (multi-select)
content <- create_content() %>%
  add_input(
    input_id = "country_filter",
    label = "Select Countries:",
    type = "select_multiple",
    filter_var = "country",
    options_from = "country",
    help = "Select one or more countries to compare"
  )

# Grouped select options
content <- create_content() %>%
  add_input(
    input_id = "country_filter",
    label = "Select Countries:",
    type = "select_multiple",
    filter_var = "country",
    options = list(
      "Europe" = c("Germany", "France", "UK"),
      "Asia" = c("China", "Japan", "India")
    )
  )

# Checkbox group
content <- create_content() %>%
  add_input(
    input_id = "metrics",
    label = "Metrics:",
    type = "checkbox",
    filter_var = "metric",
    options = c("Revenue", "Users", "Growth"),
    inline = TRUE
  )

# Radio buttons
content <- create_content() %>%
  add_input(
    input_id = "chart_type",
    label = "Chart Type:",
    type = "radio",
    filter_var = "chart_type",
    options = c("Line", "Bar", "Area")
  )

# Switch/toggle to show/hide a specific series
content <- create_content() %>%
  add_input(
    input_id = "show_average",
    label = "Show Global Average",
    type = "switch",
    filter_var = "country",
    toggle_series = "Global Average",  # Name of the series to toggle
    override = TRUE,                   # Don't let other filters hide this series
    value = TRUE                       # Start with switch ON
  )

# Slider with custom labels
content <- create_content() %>%
  add_input(
    input_id = "decade_filter",
    label = "Decade:",
    type = "slider",
    filter_var = "decade",
    min = 1,
    max = 6,
    step = 1,
    value = 1,
    labels = c("1970s", "1980s", "1990s", "2000s", "2010s", "2020s")
  )

# Text search input
content <- create_content() %>%
  add_input(
    input_id = "search",
    label = "Search:",
    type = "text",
    filter_var = "name",
    placeholder = "Type to search...",
    size = "lg"
  )

# Button group (segmented control)
content <- create_content() %>%
  add_input(
    input_id = "period",
    label = "Time Period:",
    type = "button_group",
    filter_var = "period",
    options = c("Day", "Week", "Month", "Year")
  )

## End(Not run)

Description

Creates a container for input widgets that will be displayed in a horizontal row. The inputs will wrap responsively on smaller screens. Use with end_input_row().

Usage

add_input_row(
  content,
  tabgroup = NULL,
  style = c("boxed", "inline"),
  align = c("center", "left", "right")
)

Arguments

Value

An input_row_container for piping

Examples

## Not run: 
content <- create_content() %>%
  add_input_row() %>%
    add_input(input_id = "country", filter_var = "country", options_from = "country") %>%
    add_input(input_id = "metric", filter_var = "metric", options_from = "metric") %>%
  end_input_row()

# Place inputs inside a tabgroup
content <- create_content() %>%
  add_input_row(tabgroup = "trends", style = "inline") %>%
    add_input(input_id = "country", filter_var = "country", options = c("A", "B")) %>%
  end_input_row()

## End(Not run)

Description

Creates a column container for explicit Quarto dashboard layout control. Use with add_layout_row() and end_layout_column().

Usage

add_layout_column(
  content,
  width = NULL,
  class = NULL,
  tabgroup = NULL,
  show_when = NULL
)

Arguments

Value

A layout_column_container for piping.

Examples

## Not run: 
content <- create_content() %>%
  add_layout_column(width = 60) %>%
  add_layout_row() %>%
    add_text("### Row content") %>%
  end_layout_row() %>%
end_layout_column()

## End(Not run)

Description

Start a manual layout row inside a layout column

Usage

add_layout_row(
  column_container,
  class = NULL,
  style = NULL,
  tabgroup = NULL,
  show_when = NULL
)

Arguments

Value

A layout_row_container for piping.

Description

Convenience wrapper around add_widget for leaflet objects.

Usage

add_leaflet(
  content,
  map,
  title = NULL,
  height = NULL,
  tabgroup = NULL,
  filter_vars = NULL,
  show_when = NULL
)

Arguments

Value

Updated content object

Description

Creates two linked select inputs where the child's available options depend on the parent's current selection. Can be used inside a sidebar (after add_sidebar()), inside an input row (after add_input_row()), or directly in a content collection.

Usage

add_linked_inputs(x, parent, child, type = "select")

Arguments

Value

The modified container for piping.

Examples

## Not run: 
# Inside a sidebar
add_sidebar() %>%
  add_linked_inputs(
    parent = list(id = "dimension", label = "Dimension",
                  options = c("AI", "Safety", "Digital Health")),
    child = list(id = "question", label = "Question",
                 options_by_parent = list(
                   "AI" = c("Overall", "Using AI Tools"),
                   "Safety" = c("Overall", "Passwords", "Phishing"),
                   "Digital Health" = c("Overall", "Screen Time")
                 ))
  ) %>%
  end_sidebar()

# Inside main content (no sidebar needed)
create_content(data = my_data) %>%
  add_linked_inputs(
    parent = list(id = "category", label = "Category",
                  options = c("Overall", "By Age", "By Gender")),
    child = list(id = "value", label = "Value",
                 options_by_parent = list(
                   "Overall" = c("All"),
                   "By Age" = c("18-34", "35-54", "55+"),
                   "By Gender" = c("Male", "Female")
                 ))
  )

## End(Not run)

Description

Add a metric/value box

Usage

add_metric(
  content,
  value,
  title,
  icon = NULL,
  color = NULL,
  bg_color = NULL,
  text_color = NULL,
  gradient = TRUE,
  gradient_intensity = 0.45,
  value_prefix = NULL,
  value_suffix = NULL,
  border_radius = NULL,
  subtitle = NULL,
  tabgroup = NULL,
  show_when = NULL,
  aria_label = NULL
)

Arguments

Description

Adds a modal definition to your content collection. Use markdown links with {.modal-link} class to trigger the modal.

Usage

add_modal(
  x,
  modal_id,
  title = NULL,
  modal_content = NULL,
  image = NULL,
  image_width = "100%",
  ...
)

Arguments

Value

Updated content_collection with modal added

Examples

## Not run: 
# Pipeable syntax (RECOMMENDED)
content <- create_content() %>%
  add_text("## Results") %>%
  add_text("[View details](#details){.modal-link}") %>%
  add_modal(
    modal_id = "details",
    title = "Full Results",
    modal_content = "Detailed analysis here..."
  )

# With image (custom width)
content <- create_viz() %>%
  add_viz(type = "column", x_var = "x", y_var = "y") %>%
  add_modal(
    modal_id = "chart-details",
    title = "Chart Details",
    image = "chart.png",
    image_width = "70%",  # Control image width
    modal_content = "This chart shows..."
  )

# With data.frame (auto-converts to table)
content <- create_content() %>%
  add_text("[View data](#data){.modal-link}") %>%
  add_modal(
    modal_id = "data",
    title = "Raw Data",
    modal_content = head(mtcars, 10)
  )

# Works with page objects too
page <- create_page("Results", data = my_data, type = "bar") %>%
  add_text("[View details](#info){.modal-link}") %>%
  add_modal(
    modal_id = "info",
    title = "More Info",
    modal_content = "Additional details..."
  )

## End(Not run)

Description

Adds a custom link or element to the navbar. Can include text, icons, and external links. Elements are added to the right side of the navbar by default but can be positioned left.

Usage

add_navbar_element(
  proj,
  text = NULL,
  icon = NULL,
  href,
  align = c("right", "left")
)

Arguments

Value

Modified dashboard project object

Examples

## Not run: 
# Add a "Powered by X" link with icon
dashboard <- create_dashboard("my_dashboard", "My Dashboard") %>%
  add_page("Home", text = "# Welcome", is_landing_page = TRUE) %>%
  add_navbar_element(
    text = "Powered by X",
    icon = "ph:lightning-fill",
    href = "https://example.com",
    align = "right"
  )

# Add multiple elements
dashboard <- create_dashboard("my_dashboard", "Dashboard") %>%
  add_page("Home", ...) %>%
  add_navbar_element(
    text = "Documentation",
    icon = "ph:book-open",
    href = "https://docs.example.com"
  ) %>%
  add_navbar_element(
    text = "Sponsor",
    icon = "ph:star-fill",
    href = "https://sponsor.com"
  )

# Icon only (no text)
dashboard %>%
  add_navbar_element(
    icon = "ph:github-logo",
    href = "https://github.com/user/repo"
  )

## End(Not run)

Description

Convenient alias for add_dashboard_page. Adds a new page to a dashboard project.

Usage

add_page(
  proj,
  name,
  data = NULL,
  data_path = NULL,
  template = NULL,
  params = list(),
  visualizations = NULL,
  content = NULL,
  text = NULL,
  icon = NULL,
  is_landing_page = FALSE,
  show_in_nav = TRUE,
  tabset_theme = NULL,
  tabset_colors = NULL,
  navbar_align = c("left", "right"),
  overlay = FALSE,
  overlay_theme = c("light", "glass", "dark", "accent"),
  overlay_text = "Loading",
  overlay_duration = 2200,
  lazy_load_charts = NULL,
  lazy_load_margin = NULL,
  lazy_load_tabs = NULL,
  lazy_debug = NULL,
  pagination_separator = NULL,
  time_var = NULL,
  slug = NULL
)

Arguments

Value

Modified dashboard project with the new page added.

See Also

add_dashboard_page for full parameter documentation.

Description

Adds one or more page objects to a dashboard.

Usage

add_pages(proj, ...)

Arguments

Value

The updated dashboard_project object

Examples

## Not run: 
home <- create_page("Home", is_landing_page = TRUE) %>%
  add_text("# Welcome!")

analysis <- create_page("Analysis", data = gss, type = "bar") %>%
  add_viz(x_var = "degree", title = "Education") %>%
  add_viz(x_var = "race", title = "Race")

create_dashboard(title = "My Dashboard") %>%
  add_pages(home, analysis) %>%
  generate_dashboard()

## End(Not run)

Description

Insert a pagination marker that splits the visualization collection into separate HTML pages. Each section will be rendered as its own page file (e.g., analysis.html, analysis_p2.html, analysis_p3.html) with automatic Previous/Next navigation between them.

Usage

add_pagination(viz_collection, position = NULL)

add_pagination.page_object(viz_collection, position = NULL)

Arguments

Details

This provides TRUE performance benefits - each page loads independently, dramatically reducing initial render time and file size for large dashboards.

Value

Updated viz_collection object

Examples

## Not run: 
# Split 150 charts into 3 pages of 50 each
vizzes <- create_viz()

# Page 1: Charts 1-50
for (i in 1:50) vizzes <- vizzes %>% add_viz(type = "bar", x_var = "cyl")

vizzes <- vizzes %>% add_pagination()  # Split here

# Page 2: Charts 51-100
for (i in 51:100) vizzes <- vizzes %>% add_viz(type = "bar", x_var = "gear")

vizzes <- vizzes %>% add_pagination()  # Split here

# Page 3: Charts 101-150
for (i in 101:150) vizzes <- vizzes %>% add_viz(type = "bar", x_var = "hp")

# Use in dashboard
dashboard %>%
  add_page("Analysis", visualizations = vizzes)

## End(Not run)

Description

Convenience wrapper around add_widget for plotly objects.

Usage

add_plotly(
  content,
  plot,
  title = NULL,
  height = NULL,
  tabgroup = NULL,
  filter_vars = NULL,
  show_when = NULL
)

Arguments

Value

Updated content object

Description

Adds a subtle, sleek "Powered by dashboardr" badge with logo to the bottom-right of the page footer. Integrates seamlessly with existing footer content.

Usage

add_powered_by_dashboardr(dashboard, size = "small", style = "default")

Arguments

Value

Updated dashboard project with dashboardr branding in footer

Examples

## Not run: 
dashboard <- create_dashboard("my_dash", "My Dashboard") %>%
  add_page(name = "Home", text = "Welcome!") %>%
  add_powered_by_dashboardr()

# With custom size
dashboard <- create_dashboard("my_dash") %>%
  add_powered_by_dashboardr(size = "medium", style = "badge")

## End(Not run)

Description

Add a blockquote

Usage

add_quote(
  content,
  quote,
  attribution = NULL,
  cite = NULL,
  tabgroup = NULL,
  show_when = NULL
)

Arguments

Description

Add reactable table

Usage

add_reactable(
  content,
  reactable_object,
  tabgroup = NULL,
  filter_vars = NULL,
  show_when = NULL
)

Arguments

Value

Updated content_collection

Examples

## Not run: 
# Option 1: Pass a styled reactable object
my_table <- reactable::reactable(
  mtcars,
  columns = list(mpg = reactable::colDef(name = "MPG")),
  searchable = TRUE,
  striped = TRUE
)

content <- create_content() %>%
  add_reactable(my_table)
  
# Option 2: Pass a data frame (auto-converted with defaults)
content <- create_content() %>%
  add_reactable(mtcars)

## End(Not run)

Description

Creates a button that resets specified inputs to their default values. Can be used inside a sidebar pipeline (pass a sidebar_container as the first argument) or standalone to generate the raw HTML.

Usage

add_reset_button(
  sidebar_container = NULL,
  targets = NULL,
  label = "Reset Filters",
  size = "md"
)

Arguments

Value

Modified sidebar_container when piped, or HTML string when standalone.

Description

Creates a sidebar container that can hold inputs, text, images, and other content. Use with end_sidebar() to close the sidebar and return to main content.

Usage

add_sidebar(
  content,
  width = "250px",
  position = c("left", "right"),
  title = NULL,
  background = NULL,
  padding = NULL,
  border = TRUE,
  open = TRUE,
  class = NULL
)

Arguments

Details

Sidebars are collapsible vertical panels that appear alongside the main content. They're ideal for placing filter controls, navigation, or supplementary information.

Value

A sidebar_container for piping

Important - Heading Levels

When using a sidebar, the page is rendered in Quarto dashboard format where heading levels have special meaning:

• ## creates new rows/columns (avoid in main content)

• ### creates cards/sections (safe to use)

To avoid layout issues, use ### headings or plain text in the main content area after the sidebar. For advanced layouts, prefer explicit add_layout_column() / add_layout_row() APIs instead of heading-based layout shaping.

Examples

## Not run: 
# Basic sidebar with filters
content <- create_content() %>%
  add_sidebar(width = "300px") %>%
    add_text("### Filters") %>%
    add_input(input_id = "country", filter_var = "country", options = countries) %>%
    add_divider() %>%
    add_image(src = "logo.png") %>%
  end_sidebar() %>%
  add_viz(viz_bar(...))

# Right-positioned sidebar
content <- create_content() %>%
  add_sidebar(position = "right", title = "Options") %>%
    add_input(input_id = "metric", filter_var = "metric", type = "radio",
              options = c("Revenue", "Users", "Growth")) %>%
  end_sidebar() %>%
  add_viz(viz_timeline(...))

# Styled sidebar with custom background and no border
content <- create_content() %>%
  add_sidebar(width = "300px", background = "#f8f9fa", 
              padding = "1.5rem", border = FALSE) %>%
    add_text("### Settings") %>%
  end_sidebar()

## End(Not run)

Description

Add vertical spacer

Usage

add_spacer(content, height = "2rem", tabgroup = NULL, show_when = NULL)

Arguments

Value

Updated object (same type as input)

Description

Add generic table (data frame)

Usage

add_table(
  content,
  table_object,
  caption = NULL,
  tabgroup = NULL,
  filter_vars = NULL,
  show_when = NULL
)

Arguments

Value

Updated content_collection

Description

Adds a text block to a content collection. Can be used standalone or in a pipe. Supports viz_collection as first argument for seamless piping.

Usage

add_text(x = NULL, text, ..., tabgroup = NULL, show_when = NULL)

Arguments

Value

Updated content_collection object

Examples

## Not run: 
# Standalone
text_block <- add_text("# Welcome")

# Pipe with content
content <- create_content() %>%
  add_text("## Introduction")

# With tabgroup
content <- create_content() %>%
  add_text("## Section 1", tabgroup = "Overview")

# Pipe directly from viz
content <- create_viz() %>%
  add_viz(type = "histogram", x_var = "age") %>%
  add_text("Analysis complete")

## End(Not run)

Description

Add markdown text content directly to a page object.

Usage

add_text.page_object(page, text, ..., tabgroup = NULL, show_when = NULL)

Arguments

Value

The updated page_object

Description

Creates a modern value box with optional logo, custom background color, and optional collapsible description. Perfect for displaying KPIs and metrics with additional context.

Usage

add_value_box(
  content,
  title,
  value,
  logo_url = NULL,
  logo_text = NULL,
  bg_color = "#2c3e50",
  description = NULL,
  description_title = "About this source",
  tabgroup = NULL,
  show_when = NULL,
  aria_label = NULL
)

Arguments

Details

Can be used standalone or within a value box row:

• Standalone: create_content() %>% add_value_box(...)

• In row: create_content() %>% add_value_box_row() %>% add_value_box(...) %>% add_value_box(...)

Examples

## Not run: 
# Standalone value box
content <- create_content() %>%
  add_value_box(
    title = "Total Revenue",
    value = "EUR 1,234,567",
    logo_text = "$",
    bg_color = "#2E86AB"
  )

# Row of value boxes (pipeable!)
content <- create_content() %>%
  add_value_box_row() %>%
    add_value_box(title = "Users", value = "1,234") %>%
    add_value_box(title = "Revenue", value = "EUR 56K")

## End(Not run)

Description

Creates a container for value boxes that will be displayed in a horizontal row. The boxes will wrap responsively on smaller screens. Use pipeable syntax with end_value_box_row():

Usage

add_value_box_row(content, tabgroup = NULL, show_when = NULL)

Arguments

Examples

## Not run: 
content <- create_content() %>%
  add_value_box_row() %>%
    add_value_box(title = "Users", value = "1,234", bg_color = "#2E86AB") %>%
    add_value_box(title = "Revenue", value = "EUR 56K", bg_color = "#F18F01") %>%
    add_value_box(title = "Growth", value = "+23%", bg_color = "#A23B72") %>%
  end_value_box_row()

## End(Not run)

Description

Add video

Usage

add_video(
  content,
  src,
  caption = NULL,
  width = NULL,
  height = NULL,
  tabgroup = NULL,
  show_when = NULL
)

Arguments

Value

Updated content_collection

Description

Adds a single visualization specification to an existing collection. Visualizations with the same tabgroup value will be organized into tabs on the generated page. Supports nested tabsets through hierarchy notation.

Usage

add_viz(
  x,
  type = NULL,
  ...,
  tabgroup = NULL,
  title = NULL,
  title_tabset = NULL,
  text = NULL,
  icon = NULL,
  text_position = NULL,
  text_before_tabset = NULL,
  text_after_tabset = NULL,
  text_before_viz = NULL,
  text_after_viz = NULL,
  height = NULL,
  filter = NULL,
  data = NULL,
  drop_na_vars = FALSE,
  show_when = NULL
)

Arguments

Value

The updated viz_collection object

Examples

## Not run: 
# Simple tabgroup
page1_viz <- create_viz() %>%
  add_viz(type = "stackedbar", x_var = "education", stack_var = "gender",
          title = "Education by Gender", tabgroup = "demographics")

# Nested tabgroups using slash notation
page2_viz <- create_viz() %>%
  add_viz(type = "stackedbar", title = "Overview",
          tabgroup = "demographics") %>%
  add_viz(type = "stackedbar", title = "Details",
          tabgroup = "demographics/details")

# Nested tabgroups using named numeric vector
page3_viz <- create_viz() %>%
  add_viz(type = "stackedbar", title = "Regional Details",
          tabgroup = c("1" = "demographics", "2" = "details", "3" = "regional"))

# Filter data per visualization
page4_viz <- create_viz() %>%
  add_viz(type = "histogram", x_var = "response",
          title = "Wave 1", filter = ~ wave == 1) %>%
  add_viz(type = "histogram", x_var = "response",
          title = "Wave 2", filter = ~ wave == 2) %>%
  add_viz(type = "histogram", x_var = "response",
          title = "All Waves", filter = ~ wave %in% c(1, 2, 3))

# Multiple datasets
page5_viz <- create_viz() %>%
  add_viz(type = "histogram", x_var = "age", data = "demographics") %>%
  add_viz(type = "histogram", x_var = "response", data = "survey") %>%
  add_viz(type = "histogram", x_var = "outcome", data = "outcomes")

# Separate tab label from visualization title
page6_viz <- create_viz() %>%
  add_viz(
    type = "histogram",
    x_var = "age",
    tabgroup = "demographics",
    title_tabset = "Age",  # Short tab label
    title = "Age Distribution of Survey Respondents by Gender and Region"  # Long viz title
  )

## End(Not run)

Description

Convenience function to add multiple visualizations in a loop by expanding vector parameters. Automatically detects which parameters should be expanded to create multiple visualizations. This is useful when creating many similar visualizations that differ only in one or two parameters.

Usage

add_vizzes(
  viz_collection,
  ...,
  .tabgroup_template = NULL,
  .title_template = NULL
)

Arguments

Details

The function identifies "expandable" parameters (y_var, x_var, y_var, stack_var, questions) and creates one visualization per value. Other parameters are applied to all visualizations. All expandable vector parameters must have the same length.

Templates use glue syntax:

• {i} is replaced with the iteration number (1, 2, 3, ...)

• {param_name} is replaced with the current value of that parameter

Value

The updated viz_collection object with multiple visualizations added

Examples

## Not run: 
# Basic expansion - create 3 timeline visualizations
viz <- create_viz(type = "timeline", time_var = "wave", chart_type = "line") |>
  add_vizzes(
    y_var = c("SInfo1", "SInfo2", "SInfo3"),
    group_var = "AgeGroup",  # Same for all
    .tabgroup_template = "skills/age/item{i}"
  )

# Parallel expansion - titles match the variables
viz <- create_viz(type = "stackedbar") |>
  add_vizzes(
    x_var = c("Age", "Gender", "Education"),
    title = c("By Age", "By Gender", "By Education"),
    .tabgroup_template = "demographics/demo{i}"
  )

# Use variable names in template
viz <- create_viz(type = "timeline") |>
  add_vizzes(
    y_var = c("SInfo1", "SInfo2", "SInfo3"),
    .tabgroup_template = "skills/{y_var}"
  )

# Helper function pattern
add_all_questions <- function(viz, vars, group_var, tbgrp, demographic, wave) {
  wave_path <- tolower(gsub(" ", "", wave))
  viz |> add_vizzes(
    y_var = vars,
    group_var = group_var,
    .tabgroup_template = glue::glue("{tbgrp}/{wave_path}/{demographic}/item{{i}}")
  )
}

viz <- create_viz(type = "timeline", time_var = "wave") |>
  add_all_questions(
    vars = c("var1", "var2", "var3"),
    group_var = "AgeGroup",
    tbgrp = "skills",
    demographic = "age",
    wave = "Over Time"
  )

## End(Not run)

Description

Embed any htmlwidget object (plotly, leaflet, echarts4r, DT, etc.) directly into a dashboard page. The widget will be rendered as-is.

Usage

add_widget(
  content,
  widget,
  title = NULL,
  height = NULL,
  tabgroup = NULL,
  filter_vars = NULL,
  show_when = NULL
)

Arguments

Value

Updated content object

Description

Applies a theme to an existing dashboard_project object or returns theme parameters for use in create_dashboard(). Supports piping for easy theme application. You can override any theme parameter by passing it as an additional argument.

Usage

apply_theme(proj = NULL, theme, ...)

Arguments

Value

If proj is provided, returns the modified dashboard_project object. If proj is NULL, returns the theme list.

Examples

## Not run: 
# Method 1: Pipe theme directly into dashboard (EASIEST!)
dashboard <- create_dashboard("my_dashboard", "My Research") %>%
  apply_theme(theme_ascor()) %>%
  add_page("Home", text = "# Welcome", is_landing_page = TRUE)

# Method 2: Override specific theme parameters
dashboard <- create_dashboard("tech_dash", "Tech Dashboard") %>%
  apply_theme(theme_modern("purple"), mainfont = "Roboto", fontsize = "18px") %>%
  add_page("Data", visualizations = my_viz)

# Method 3: Get theme parameters only
ascor_params <- apply_theme(theme = theme_ascor())

# Method 4: Customize multiple parameters
dashboard <- create_dashboard("custom", "Custom Dashboard") %>%
  apply_theme(
    theme_clean(),
    mainfont = "Inter",
    fontsize = "18px",
    linkcolor = "#8B0000",
    max_width = "1400px"
  )

## End(Not run)

Description

This function creates and renders a professional dashboard with ASCoR (Amsterdam School of Communication Research) and University of Amsterdam branding. The dashboard showcases the dashboardr package with UvA colors, styling, and branding.

Usage

ascor_dashboard(directory = "ascor_dashboard")

Arguments

Details

The ASCoR dashboard features:

• UvA red (#CB0D0D) as primary branding color

• Professional typography with Inter font

• ASCoR logo in the navbar (if logo file is provided)

• Clean, academic styling appropriate for research communication

• Example visualizations using General Social Survey data

Value

Invisibly returns the dashboard_project object.

Examples

## Not run: 
# Run the ASCoR dashboard (requires Quarto CLI and 'gssr' package)
ascor_dashboard()

# Specify custom directory
ascor_dashboard(directory = "my_ascor_dashboard")

## End(Not run)

Description

Helper function to create Bootstrap card components for displaying content in a structured way. Useful for author profiles, feature highlights, or any content that benefits from card layout.

Usage

card(
  content,
  title = NULL,
  image = NULL,
  image_alt = NULL,
  footer = NULL,
  class = NULL,
  style = NULL
)

Arguments

Value

HTML div element with Bootstrap card classes

Examples

## Not run: 
# Simple text card
card("This is a simple card with just text content")

# Card with title and image
card(
  content = "This is the card body content",
  title = "Card Title",
  image = "https://example.com/image.jpg",
  image_alt = "Description of image"
)

# Author card
card(
  content = "Dr. Jane Smith is a researcher specializing in data science and visualization.",
  title = "Dr. Jane Smith",
  image = "https://example.com/jane.jpg",
  footer = "Website: janesmith.com"
)

## End(Not run)

Description

Helper function to display multiple cards in a responsive Bootstrap row layout.

Usage

card_row(..., cols = 2, class = NULL)

Arguments

Value

HTML div element with Bootstrap row classes containing the cards

Examples

## Not run: 
# Display two cards in a row
card_row(card1, card2)

# Display three cards in a row (3 columns)
card_row(card1, card2, card3, cols = 3)

## End(Not run)

Description

Universal function to combine content_collection or viz_collection objects. Preserves all content types (visualizations, pagination markers, text blocks) and collection-level attributes (lazy loading, etc.).

Usage

combine_content(...)

Arguments

Value

Combined content_collection

Examples

## Not run: 
# Combine multiple collections
all_viz <- demo_viz %>%
  combine_content(analysis_viz) %>%
  combine_content(summary_viz)

# With pagination
paginated <- section1_viz %>%
  combine_content(section2_viz) %>%
  add_pagination() %>%
  combine_content(section3_viz)

# Using + operator
combined <- viz1 + viz2 + viz3

## End(Not run)

Description

This function has been superseded by combine_content(). It still works but we recommend using combine_content() for new code as it handles all content types and attributes more reliably.

Usage

combine_viz(...)

Arguments

Value

A combined viz_collection

Examples

## Not run: 
viz1 <- create_viz() %>% add_viz(type = "histogram", x_var = "age")
viz2 <- create_viz() %>% add_viz(type = "histogram", x_var = "income")
combined <- combine_viz(viz1, viz2)  # Combines both

## End(Not run)

Description

Creates a custom-styled blockquote with customizable colors, borders, and styling. Useful for highlighting questions, quotes, or important text in dashboards.

Usage

create_blockquote(
  text,
  preset = NULL,
  class_name = "custom-blockquote",
  font_size = "1em",
  text_color = "#333",
  border_width = "5px",
  border_color = "#0056b3",
  background_color = "#f0f8ff",
  padding = "10px 20px",
  margin = "20px 0",
  line_height = "1.6",
  return_css = FALSE,
  use_class = FALSE
)

Arguments

Value

If use_class = FALSE: HTML blockquote with inline styles. If use_class = TRUE: List with html and css elements. If return_css = TRUE: Only the CSS string.

Examples

# Basic usage with defaults
create_blockquote("This is an important question about data quality.")

# Using built-in presets (as strings)
create_blockquote("How do you rate our service?", preset = "question")
create_blockquote("Please check your input.", preset = "warning")
create_blockquote("Operation completed!", preset = "success")

# Using custom presets (as lists) - pass directly!
algosoc_style <- list(
  border_color = "#0056b3",
  background_color = "#e3f2fd",
  text_color = "#1565c0"
)
create_blockquote("AlgoSoc question here", preset = algosoc_style)

# Define multiple custom styles and reuse
survey_style <- list(border_color = "#6f42c1", background_color = "#f8f5ff")
important_style <- list(
  border_color = "#e74c3c",
  background_color = "#ffebee",
  border_width = "8px"
)

create_blockquote("Survey question 1", preset = survey_style)
create_blockquote("Survey question 2", preset = survey_style)
create_blockquote("IMPORTANT!", preset = important_style)

# Custom styling (overriding preset)
create_blockquote(
  "Warning: Please review the data before proceeding.",
  preset = "warning",
  border_width = "8px",  # Override preset border width
  font_size = "1.2em"     # Override preset font size
)

# Fully custom (no preset)
create_blockquote(
  "How satisfied are you with our service?",
  border_color = "#6f42c1",
  background_color = "#f8f5ff",
  font_size = "1.1em",
  padding = "15px 25px"
)

# Using class-based approach (for multiple blockquotes)
result <- create_blockquote(
  "Question 1: What is your opinion?",
  preset = "question",
  use_class = TRUE
)
# View the CSS component (an htmltools tag)
result$css
# View the HTML component
result$html

Description

This is an alias for create_viz - both functions are identical. Use whichever name makes more sense for your use case. The returned collection can be built up with any combination of add_viz(), add_text(), and add_image().

Usage

create_content(
  data = NULL,
  tabgroup_labels = NULL,
  shared_first_level = TRUE,
  ...
)

Arguments

Details

Note: Both names return the same object with both "content_collection" and "viz_collection" classes for backward compatibility.

Value

A content_collection (also a viz_collection for compatibility)

Examples

## Not run: 
# Create content with inline data for preview
content <- create_content(data = mtcars) %>%
  add_text("# MPG Analysis") %>%
  add_viz(type = "histogram", x_var = "mpg") %>%
  preview()

# Set shared defaults like type - all add_viz() calls inherit these
content <- create_content(
  data = survey_df,
  type = "stackedbar",
  stacked_type = "percent",
  horizontal = TRUE
) %>%
  add_viz(x_var = "age", stack_var = "response", tabgroup = "Age") %>%
  add_viz(x_var = "gender", stack_var = "response", tabgroup = "Gender")

# These are equivalent:
content <- create_content() %>%
  add_text("# Title") %>%
  add_viz(type = "histogram", x_var = "age")

content <- create_viz() %>%
  add_text("# Title") %>%
  add_viz(type = "histogram", x_var = "age")

## End(Not run)

Description

Initializes a dashboard project object that can be built up using the piping workflow with add_landingpage() and add_page().

Usage

create_dashboard(
  output_dir = "site",
  title = "Dashboard",
  logo = NULL,
  favicon = NULL,
  github = NULL,
  twitter = NULL,
  linkedin = NULL,
  email = NULL,
  website = NULL,
  search = TRUE,
  theme = NULL,
  custom_css = NULL,
  custom_scss = NULL,
  tabset_theme = "minimal",
  tabset_colors = NULL,
  author = NULL,
  description = NULL,
  page_footer = NULL,
  date = NULL,
  sidebar = FALSE,
  sidebar_style = "docked",
  sidebar_background = "light",
  sidebar_foreground = NULL,
  sidebar_border = TRUE,
  sidebar_alignment = "left",
  sidebar_collapse_level = 2,
  sidebar_pinned = FALSE,
  sidebar_tools = NULL,
  sidebar_contents = NULL,
  breadcrumbs = TRUE,
  page_navigation = FALSE,
  back_to_top = FALSE,
  reader_mode = FALSE,
  repo_url = NULL,
  repo_actions = NULL,
  navbar_style = NULL,
  navbar_bg_color = NULL,
  navbar_text_color = NULL,
  navbar_text_hover_color = NULL,
  navbar_brand = NULL,
  navbar_toggle = NULL,
  max_width = NULL,
  mainfont = "Fira Sans",
  fontsize = "16px",
  fontcolor = NULL,
  linkcolor = NULL,
  monofont = "Fira Code",
  monobackgroundcolor = NULL,
  linestretch = NULL,
  backgroundcolor = NULL,
  margin_left = NULL,
  margin_right = NULL,
  margin_top = NULL,
  margin_bottom = NULL,
  math = NULL,
  code_folding = NULL,
  code_tools = NULL,
  toc = NULL,
  toc_depth = 3,
  google_analytics = NULL,
  plausible = NULL,
  gtag = NULL,
  value_boxes = FALSE,
  metrics_style = NULL,
  page_layout = "full",
  mobile_toc = FALSE,
  viewport_width = NULL,
  viewport_scale = NULL,
  viewport_user_scalable = TRUE,
  self_contained = FALSE,
  code_overflow = NULL,
  html_math_method = NULL,
  shiny = FALSE,
  observable = FALSE,
  jupyter = FALSE,
  publish_dir = NULL,
  github_pages = NULL,
  netlify = NULL,
  allow_inside_pkg = FALSE,
  warn_before_overwrite = TRUE,
  sidebar_groups = NULL,
  navbar_sections = NULL,
  lazy_load_charts = FALSE,
  lazy_load_margin = "200px",
  lazy_load_tabs = NULL,
  lazy_debug = FALSE,
  pagination_separator = "of",
  pagination_position = "bottom",
  powered_by_dashboardr = TRUE,
  chart_export = FALSE,
  backend = "highcharter",
  contextual_viz_errors = FALSE,
  url_params = FALSE,
  cross_tab_data_mode = c("inline", "asset"),
  min_cell_size = 0L,
  rds_bundle_threshold = 5L,
  deferred_charts = FALSE
)

Arguments

Value

A dashboard_project object

Examples

## Not run: 
# Basic dashboard
dashboard <- create_dashboard("my_dashboard", "My Analysis Dashboard")

# Comprehensive dashboard with all features
dashboard <- create_dashboard(
  "my_dashboard",
  "My Analysis Dashboard",
  logo = "logo.png",
  github = "https://github.com/username/repo",
  twitter = "https://twitter.com/username",
  theme = "cosmo",
  author = "Dr. Jane Smith",
  description = "Comprehensive data analysis dashboard",
  page_footer = "(c) 2024 Company Name",
  sidebar = TRUE,
  toc = "floating",
  google_analytics = "GA-XXXXXXXXX",
  value_boxes = TRUE,
  shiny = TRUE
)

# Dashboard with lazy loading for better performance
dashboard <- create_dashboard(
  "fast_dashboard",
  "High Performance Dashboard",
  lazy_load_charts = TRUE,
  lazy_load_margin = "300px",
  lazy_load_tabs = TRUE
)

# Professional styling with modern fonts (Google Fonts work great!)
dashboard <- create_dashboard(
  "styled_dashboard",
  "Beautifully Styled Dashboard",
  navbar_bg_color = "#1e40af",     # Deep blue navbar
  mainfont = "Fira Sans",           # Smooth, modern (default choice)
  fontsize = "16px",
  fontcolor = "#1f2937",            # Dark gray for readability
  linkcolor = "#2563eb",            # Vibrant blue links
  monofont = "Fira Code",           # Code font with ligatures
  monobackgroundcolor = "#f8fafc",  # Light gray code background
  linestretch = 1.6,                # Comfortable line spacing
  backgroundcolor = "#ffffff"
)

# Alternative professional font combinations:
# Option 1: Warm & Friendly
dashboard <- create_dashboard(
  "friendly_dashboard",
  title = "Friendly Dashboard",
  mainfont = "Lato",                # Warm, approachable
  monofont = "JetBrains Mono"       # Excellent for code
)

# Option 2: Elegant & Refined
dashboard <- create_dashboard(
  "elegant_dashboard",
  title = "Elegant Dashboard",
  mainfont = "Source Sans Pro",     # Elegant, highly readable
  monofont = "Source Code Pro"      # Matching code font
)

# Option 3: Technical Feel
dashboard <- create_dashboard(
  "tech_dashboard",
  title = "Tech Dashboard",
  mainfont = "Roboto",              # Technical, clean
  monofont = "JetBrains Mono"       # Excellent for code
)

## End(Not run)

Description

Creates an animated loading overlay that appears when the page loads and automatically fades out after a specified duration. Useful for providing visual feedback while charts and visualizations are rendering.

Usage

create_loading_overlay(
  text = "Loading",
  timeout_ms = 2200,
  theme = c("light", "glass", "dark", "accent")
)

Arguments

Value

An htmltools tag object containing the overlay HTML, CSS, and JavaScript

Examples

## Not run: 
# In a Quarto document R chunk:
dashboardr::create_loading_overlay("Loading Dashboard...", 2000, "glass")

## End(Not run)

Description

Creates a standalone page object that can be populated with content and later added to a dashboard. Pages can have visualizations added directly (without creating separate content objects), making this the simplest way to build dashboards.

Usage

create_page(
  name,
  data = NULL,
  data_path = NULL,
  type = NULL,
  color_palette = NULL,
  icon = NULL,
  is_landing_page = FALSE,
  navbar_align = c("left", "right"),
  tabset_theme = NULL,
  tabset_colors = NULL,
  overlay = FALSE,
  overlay_theme = c("light", "glass", "dark", "accent"),
  overlay_text = "Loading",
  overlay_duration = 2200,
  lazy_load_charts = NULL,
  lazy_load_margin = NULL,
  lazy_load_tabs = NULL,
  lazy_debug = NULL,
  pagination_separator = NULL,
  time_var = NULL,
  weight_var = NULL,
  filter = NULL,
  drop_na_vars = NULL,
  shared_first_level = TRUE,
  ...
)

Arguments