shadshiny does not draw charts. It gives you the shell around them –
shad_value_box() and shad_chart_container() –
and the palette inside them, so a ggplot2, plotly, or echarts4r figure
matches the page instead of fighting it.
KPI cards
library(shiny)
library(shadshiny)
shad_value_box(
value = "$48,120",
label = "Revenue",
delta = "+12.4%",
delta_direction = "up", # "auto", "up", "down", "neutral"
icon = "activity",
caption = "vs. last month"
)delta_direction = "auto" reads the sign off the
delta string: a leading - or −
renders the down/destructive chip, anything else renders up. Set it
explicitly whenever “up” isn’t the good direction – churn going up is
not a win.
sparkline takes any tag. Reach for
shad_sparkline() before a plotOutput(): it is
inline SVG with no plotting stack and, more usefully, its marks are
painted with the theme’s chart tokens, so a dark-mode toggle or a preset
switch restyles it in CSS – no re-render, no server
round-trip.
shad_value_box("1,204", "Sessions", delta = "-3.1%",
sparkline = shad_sparkline(sessions, type = "area"))size is "sm", "md", or
"lg"; href turns the whole card into a
link.
Lay them out with shad_grid() – min_width
fits as many equal columns as will fit, with no breakpoints to
maintain:
shad_grid(
shad_value_box("$48,120", "Revenue", delta = "+12.4%"),
shad_value_box("1,204", "Sessions", delta = "-3.1%"),
shad_value_box("2.4%", "Conversion", delta = "0.0%", delta_direction = "neutral"),
min_width = "12rem"
)Sparklines and donuts
shad_sparkline() draws "line",
"area", "bar", or "step" from a
numeric vector, with no axes and no labels. It stretches to fill
whatever box it is dropped into – a value box strip, a table cell, an
item row:
shad_sparkline(c(31, 40, 28, 51, 42, 62), type = "area")
shad_sparkline(c(-4, -1, 2, 5, -3), type = "bar", color = 2) # bars hang off zeroNon-finite values break the series rather than being interpolated across, so a gap in the data reads as a gap in the line.
shad_mini_donut() shows a few parts of a whole, with
optional content in the middle:
shad_mini_donut(c(62, 24, 14), center = "62%")
shad_mini_donut(c(3, 1), thickness = 1) # thickness = 1 is a piecolor (and the donut’s colors) take a
chart-token index 1–5, or any CSS colour when
you need to step outside the palette. Both charts are decorative by
default and hidden from screen readers – the number they illustrate is
normally right next to them. Pass label when the chart is
the only carrier of the information.
The chart card
shad_chart_container(
plotOutput("trend", height = "260px"),
title = "Revenue by region",
description = "Last 6 months",
legend = TRUE,
aspect = "video" # "video", "square", "wide", or "auto"
)aspect locks the card’s ratio. Use "auto"
when you set an explicit height on the plot yourself – otherwise the two
fight and you get letterboxing. plain = TRUE drops the card
chrome and keeps only the sizing wrapper, which is what you want when
the container already sits inside a shad_card().
legend_labels renders a legend strip in the chart
palette, in order, so you can label a plot whose own legend you
suppressed:
shad_chart_container(
plotOutput("stack"),
title = "Channel mix",
legend_labels = c("Online", "Retail", "Partner")
)The palette
shad_chart_colors(n, preset, dark) returns
n hex colours from the active theme’s
--shad-chart-1 … --shad-chart-6 ramp,
interpolating past six:
shad_chart_colors(3) # default preset, light
shad_chart_colors(8, "blue", dark = TRUE) # 8 colours, blue preset, dark modeshad_tokens(preset, dark) gives you the whole token set
as OKLCH strings if you need something the chart ramp doesn’t cover
(background, border,
muted-foreground, …).
Following the live theme
This is the part that matters. page_shad() themes are
switched at runtime – by update_shad_theme() or
the user’s dark-mode toggle – and a plot rendered in R has no idea.
shad_current_theme() is the bridge: a reactive read of the
browser’s current theme that returns
list(preset = , dark = ). Touch it inside
renderPlot() and the plot re-renders whenever the theme
changes.
output$trend <- renderPlot({
th <- shad_current_theme() # reactive dependency on the live theme
ggplot2::ggplot(sales, ggplot2::aes(month, amount, colour = region)) +
ggplot2::geom_line(linewidth = 1) +
shad_scale_color_shad(th$preset, th$dark) +
shad_theme_ggplot2(th$preset, th$dark)
}, bg = "transparent") # let the card show through in dark modeForget shad_current_theme() and your chart keeps its old
colours until some unrelated reactive happens to invalidate it. Forget
bg = "transparent" and renderPlot() paints a
white PNG behind the plot, so dark-mode text lands on white.
ggplot2
The plot adapters in this and the next section are experimental: their behavior also depends on the third-party plotting packages, so they may change before shadshiny 1.0.
| Helper | Does |
|---|---|
shad_theme_ggplot2(preset, dark, base_size) |
A theme() matching the page: background, grid, text,
and border colours. |
shad_scale_color_shad(preset, dark, ...) |
Discrete colour scale from the chart ramp. |
shad_scale_fill_shad(preset, dark, ...) |
The same, for fill. |
Extra ... pass through to
ggplot2::discrete_scale(), so name,
labels, and guide work as usual.
ggplot2::ggplot(agg, ggplot2::aes(region, amount, fill = region)) +
ggplot2::geom_col() +
shad_scale_fill_shad(th$preset, th$dark, guide = "none") +
shad_theme_ggplot2(th$preset, th$dark, base_size = 13) +
ggplot2::labs(x = NULL, y = NULL)plotly and echarts4r
These take the widget and return it, so they pipe:
output$p <- plotly::renderPlotly({
th <- shad_current_theme()
plotly::plot_ly(sales, x = ~month, y = ~amount, color = ~region,
type = "scatter", mode = "lines") |>
shad_theme_plotly(th$preset, th$dark)
})
output$e <- echarts4r::renderEcharts4r({
th <- shad_current_theme()
sales |>
echarts4r::e_charts(month) |>
echarts4r::e_line(amount) |>
shad_theme_echarts4r(th$preset, th$dark)
})Both plotly and echarts4r are Suggests –
the helpers error with a clear message if the package isn’t
installed.
Base graphics
There is no theme helper, but the palette is just hex, so:
output$bar <- renderPlot({
th <- shad_current_theme()
ink <- if (th$dark) "#A1A1A1" else "#737373" # axis text for either card
op <- par(fg = ink, col.axis = ink)
on.exit(par(op), add = TRUE)
barplot(values, col = shad_chart_colors(length(values), th$preset, th$dark),
border = NA)
}, bg = "transparent")Timelines
For event feeds rather than figures:
shad_timeline(
shad_timeline_item("Order placed", time = "09:12", icon = "check",
description = "Payment authorised"),
shad_timeline_item("Shipped", time = "14:40", status = "active"),
shad_timeline_item("Delivered", time = "–", status = "muted", last = TRUE),
align = "left" # or "alternate"
)See also
-
vignette("theming")for presets, custom palettes, and runtime switching. -
vignette("data-tables")for the table these dashboards usually sit above. -
shad_run_example("07-data-explorer")for all of it in one app.