Create Bar Chart — viz_bar • dashboardr

Creates horizontal or vertical bar charts showing counts, percentages, or means. Supports simple bars or grouped bars (when group_var is provided). Can display error bars (standard deviation, standard error, or confidence intervals) when showing means via value_var.

Usage

viz_bar(
  data,
  x_var,
  group_var = NULL,
  value_var = NULL,
  title = NULL,
  subtitle = NULL,
  x_label = NULL,
  y_label = NULL,
  horizontal = FALSE,
  bar_type = "count",
  color_palette = NULL,
  group_order = NULL,
  x_order = NULL,
  sort_by_value = FALSE,
  sort_desc = TRUE,
  x_breaks = NULL,
  x_bin_labels = NULL,
  include_na = FALSE,
  na_label = "(Missing)",
  weight_var = NULL,
  error_bars = "none",
  ci_level = 0.95,
  error_bar_color = "black",
  error_bar_width = 50,
  tooltip = NULL,
  tooltip_prefix = "",
  tooltip_suffix = "",
  x_tooltip_suffix = "",
  data_labels_enabled = TRUE,
  complete_groups = TRUE,
  y_var = NULL
)

Arguments

data: A data frame containing the survey data.
x_var: Character string. Name of the categorical variable for the x-axis.
group_var: Optional character string. Name of grouping variable to create separate bars (e.g., score ranges, categories). Creates grouped/clustered bars.
value_var: Optional character string. Name of a numeric variable to aggregate. When provided, bars show the mean of this variable per category (instead of counts). Required for error bars with "sd", "se", or "ci".
title: Optional main title for the chart.
subtitle: Optional subtitle for the chart.
x_label: Optional label for the x-axis. Defaults to x_var name.
y_label: Optional label for the y-axis.
horizontal: Logical. If TRUE, creates horizontal bars. Defaults to FALSE.
bar_type: Character string. Type of bar chart: "count", "percent", or "mean". Defaults to "count". When value_var is provided, automatically switches to "mean".
color_palette: Optional character vector of colors for the bars.
group_order: Optional character vector specifying the order of groups (for group_var).
x_order: Optional character vector specifying the order of x categories.
sort_by_value: Logical. If TRUE, sort categories by their value (highest on top for horizontal bars).
sort_desc: Logical. If sort_by_value = TRUE, sort descending (default) or ascending.
x_breaks: Optional numeric vector for binning continuous x variables.
x_bin_labels: Optional character vector of labels for x bins.
include_na: Logical. Whether to include NA values as a separate category. Defaults to FALSE.
na_label: Character string. Label for NA category if include_na = TRUE. Defaults to "(Missing)".
weight_var: Optional character string. Name of a weight variable to use for weighted aggregation. When provided, counts are computed as the sum of weights instead of simple counts.
error_bars: Character string. Type of error bars to display: "none" (default), "sd" (standard deviation), "se" (standard error), or "ci" (confidence interval). Requires value_var to be specified.
ci_level: Numeric. Confidence level for confidence intervals. Defaults to 0.95 (95% CI). Only used when error_bars = "ci".
error_bar_color: Character string. Color for error bars. Defaults to "black".
error_bar_width: Numeric. Width of error bar whiskers as percentage (0-100). Defaults to 50.
tooltip: A tooltip configuration created with tooltip(), OR a format string with {placeholders}. Available placeholders: {category}, {value}, {percent}, {series}. For simple cases, use tooltip_prefix and tooltip_suffix instead. See tooltip for full customization options.
tooltip_prefix: Optional string prepended to tooltip values (simple customization).
tooltip_suffix: Optional string appended to tooltip values (simple customization).
x_tooltip_suffix: Optional string appended to x-axis category in tooltips.
data_labels_enabled: Logical. If TRUE, show value labels on bars. Default TRUE.
complete_groups: Logical. When TRUE (default), ensures all x_var/group_var combinations are present in the output, filling missing combinations with 0. This prevents bar misalignment when some groups have no observations for certain categories. Set to FALSE to show only observed combinations. Only applies when group_var is specified.
y_var: Optional character string. Name of a column containing pre-aggregated counts or values. When provided, skips aggregation and uses these values directly. Useful when working with already-aggregated data (e.g., Column 1: Group, Column 2: Count).

Value

A highcharter plot object.

Examples

# Simple bar chart showing counts (default)
plot1 <- viz_bar(
  data = survey_data,
  x_var = "category"
)
#> Error: object 'survey_data' not found
plot1
#> Error: object 'plot1' not found

# Horizontal bars with percentages
plot2 <- viz_bar(
  data = survey_data,
  x_var = "category",
  horizontal = TRUE,
  bar_type = "percent"
)
#> Error: object 'survey_data' not found
plot2
#> Error: object 'plot2' not found

# Grouped bars
plot3 <- viz_bar(
  data = survey_data,
  x_var = "question",
  group_var = "score_range",
  color_palette = c("#D2691E", "#4682B4", "#228B22"),
  group_order = c("Low (1-9)", "Middle (10-19)", "High (20-29)")
)
#> Error: object 'survey_data' not found
plot3
#> Error: object 'plot3' not found

# Bar chart with means and error bars (95% CI)
plot4 <- viz_bar(
  data = mtcars,
  x_var = "cyl",
  value_var = "mpg",
  error_bars = "ci",
  title = "Mean MPG by Cylinders",
  y_label = "Miles per Gallon"
)
plot4


# Grouped means with standard error bars
plot5 <- viz_bar(
  data = mtcars,
  x_var = "cyl",
  group_var = "am",
  value_var = "mpg",
  error_bars = "se",
  title = "Mean MPG by Cylinders and Transmission"
)
plot5