Skip to contents

Give a plotly chart the KIT look (chart)

Source: R/plotly.R
kit_plotly_style.Rd

Makes plotly charts look like part of the same app: typeface, text sizes, and colors all use KIT's design variables. Only the look changes, not the data (points, lines, axis ranges, tick positions, and hover text stay the same).

Usage

kit_plotly_style(
  p,
  legend = c("auto", "bottom", "right", "keep"),
  colorscale = TRUE,
  fonts = TRUE,
  filename = "kit-chart",
  font_size = 15,
  brand = kit_current_brand()
)

Arguments

p

A plotly chart (plotly::plot_ly(), kits' plot(); one already passed through plotly::plotly_build() also works).

legend

Where the legend goes:

  • "auto" (default): with more than 4 entries, or when the longest entry is wider than 20 columns (a Chinese character counts as 2), the legend goes below the chart, horizontal, left-aligned; otherwise on the right. When the chart is narrower than 600px (phones) it also moves below, and returns to the right when the chart gets wider (decided in the browser).

  • "bottom": always below; "right": always on the right.

  • "keep": leave the legend position alone (only change the font).

colorscale

When TRUE (default), heatmap-type traces switch to kit_chart_sequential(); when FALSE, the original color scale is kept.

fonts

When TRUE (default), attaches the rounded typeface from Google Fonts (kit_plotly_fonts()), so a downloaded single HTML file also uses the app's typeface.

filename

The file name (without extension) for the toolbar's "download PNG" and "download SVG".

font_size

Body text size (px); the other sizes are derived from it.

brand

The brand (kit_brand()): the heatmap color scale comes from it (kit_chart_sequential()). Defaults to kit_current_brand() (KIT when not set). Text, axis lines, and background keep the design language's ink and white.

Value

A plotly chart (passed through plotly_build()).

Details

What changes:

  • Typeface: everything uses the app's rounded typeface "Chiron GoRound TC", sans-serif; text is nb-ink (#141414), ticks are text-hint (#5a5a5a). Sizes: body font_size (default 15px), legend and hover box 1px smaller, ticks 2px smaller, title about h5 (1.2 times font_size).

  • Title: left-aligned, bold. When the chart is too narrow, it wraps in the browser (breaking between Chinese characters or at spaces).

  • Every axis (xaxis, xaxis2…, yaxis…, including side-by-side small charts such as a Wright map): axis line nb-ink 1.5px, grid lines line-soft (#e3ded2), zero line line (#d9d4c5), ticks outside; no frame on four sides (mirror = FALSE, and the black frame kits draws around each small chart is removed; KIT design language: no frames inside frames). When axis titles and ticks do not fit, the margins widen automatically (automargin).

  • Background: white (the chart sits in a white card); downloaded PNGs and SVGs also have a white background.

  • Colors: colorway is Okabe–Ito (kit_chart_colors()). plotly's own default colors are replaced with the Okabe–Ito color in the same position; colors set by kits or kitsUI stay unchanged (kitsUI's role colors and category recoloring are kept).

  • Color scale (colorscale = TRUE): heatmap-type traces (heatmap, contour, histogram2d) switch to kit_chart_sequential() (very light lime → light lime → KIT green); the color bar's text and outline always get the new look.

  • Hover box: white background, nb-ink border, the app's typeface.

  • Legend: the app's typeface, no border. For position, see legend.

  • Toolbar: no plotly logo; only "download PNG", "download SVG", zoom in, zoom out, and reset to the original range remain; interface text is Traditional Chinese (zh-TW). The PNG is always 2100 pixels wide (7 inches at 300 dpi; the aspect ratio is the one on screen) and the file says 300 dpi, so it is 7 inches wide when inserted in Word. The SVG is a vector image for journals that want 600 dpi or more, EPS or PDF; its text uses the fonts on the computer that opens it (the rounded typeface is a web font). Both are made in the browser, not by R, and also work in a downloaded HTML file.

  • Margins: equally small on all sides; plotly widens them automatically when axes, legend, or color bar do not fit, so no text is cut off.

What does not change: data, axis ranges and ticks, trace colors (other than plotly's default colors), marker shapes, line widths and dashes, opacity, hover text, legend text, the text of titles and axis titles (only bold is added), chart height and width, and shapes (other than kits' small-chart frames; for example, the gray band in fit plots).

Order when used with kits and kitsUI: kits' plot() → kitsUI recoloring (kit_chart_categorical(), kit_chart_role()) → kitsUI Chinese labels (kit_chart_zh()) → kit_plotly_style(). Recoloring and this function can be swapped (this function does not touch set colors), but Chinese labels must come first: this function wraps the title in <b>, after which kit_chart_zh() no longer recognizes the original English title. Applying it twice to the same chart is the same as applying it once.

See also

kit_plotly_fonts(), kit_chart_colors(), kit_chart_sequential()

Examples

if (requireNamespace("plotly", quietly = TRUE)) {
  d <- data.frame(wave = rep(c(3, 6, 12), 2), score = c(8, 11, 15, 7, 10, 13),
                  cohort = rep(c("M03", "M36"), each = 3))
  p <- plotly::plot_ly(d, x = ~wave, y = ~score, split = ~cohort,
                       type = "scatter", mode = "lines+markers")
  p <- plotly::layout(p, title = "各世代的分數中位數")
  kit_plotly_style(p)
}