A spinner tells the user to wait. A skeleton shows the user what is coming: bars for a bar chart, rows for a table, lines for text. The page does not look empty, and the eye of the user can go to the place where the content will be.
Install
Install bones from CRAN:
install.packages("bones")To get the development version from GitHub:
# install.packages("remotes")
remotes::install_github("tenmeh/bones")Wrap an output
Put withBones() around an output in the UI. That is
all:
library(shiny)
library(bones)
ui <- fluidPage(
withBones(plotOutput("chart")),
withBones(tableOutput("results"), rows = 8)
)bones finds the shape from the output. A
plotOutput() gets columns on an axis, a
tableOutput() gets a header row and body rows, and a
textOutput() gets lines of text. A table from DT,
reactable, gt or rhandsontable gets a shape that copies that package.
The Shapes page shows each one.
Wrap every output at once
bones_auto() looks through a UI and puts each output in
withBones(). Give it the whole page, or only a part of
it:
ui <- bones_auto(fluidPage(
plotOutput("chart"),
tableOutput("results"),
withBones(plotOutput("trend"), type = "line")
))Each output gets the shape of its kind. An output that is in
withBones() already keeps its own wrapper, so wrap one
output yourself to give it a type or other options.
Arguments after the UI go to each wrapper, and exclude
names outputs to leave alone:
ui <- bones_auto(
fluidPage(plotOutput("chart"), plotOutput("small")),
stale = FALSE,
exclude = "small"
)An inline output, such as
textOutput("n", inline = TRUE), is left alone, because a
wrapper would break its line. A renderUI() makes its
outputs later, so bones_auto() does not see them. Call
bones_auto() on the UI inside that renderUI()
too.
Name the shape when bones cannot find it
A plotOutput() only says that a plot will be there.
renderPlot() decides the kind of chart later, on the
server. So name the kind with type:
withBones(plotOutput("trend"), type = "line")
withBones(plotOutput("fit"), type = "scatter")A uiOutput() can hold anything, so give it a
type too:
The page does not move
Until the content arrives, the placeholder keeps the height of the
output. If the output sets a height, as plotOutput() does,
the placeholder uses it. If not, the height comes from
rows, lines or n, or from
height:
withBones(uiOutput("summary"), type = "text", lines = 5)
withBones(uiOutput("map"), type = "plot", height = 500)When the content arrives, the content sets the height, and no gap stays under it.
The browser also stores the real height of the content. On the next
visit, the placeholder keeps that height in place of the estimate, so
the page does not move at all. Turn this off with
remember = FALSE.
Learned shapes
On the first visit, the shape comes from the type of the output. After that, each output learns the shape of its content. When the content arrives, the browser stores the place and the size of each line of text, each image and each card. On the next visit, the skeleton has that shape: a table with a title and 12 rows gets a title and 12 rows of bars.
- It applies only when you do not set the shape yourself: no
type,rows,cols,lines,norskeleton. It does not apply to charts, which keep their chart shapes. - A stored shape is used only when the output is within 10% of the width at which it was stored. On a narrower screen, the built-in shape comes back.
- Only numbers are stored, in the browser of the user. No text from the app is stored.
- Turn it off for one output with
learn = FALSE:
A fast load does not flicker
The skeleton waits for 300 ms before it appears, so a load that ends
sooner shows nothing. Once it has appeared, it stays for at least 500
ms, so it never flashes for one frame. Change the times with
delay and min_time:
withBones(plotOutput("chart"), delay = 150, min_time = 400)The second load keeps the old content
On the first load, the user sees a skeleton. When the output calculates again, the old content stays on the screen, dimmed, until the new content arrives. The user is possibly in the middle of reading it, and grey boxes in its place would remove information.
To show the skeleton again on each load, set
stale = FALSE:
withBones(plotOutput("chart"), stale = FALSE)Retry a failed output
Give retry an input id. The error panel adds a “Try
again” button after its content, including with a custom
bones_error() panel. The output must read that input so a
click runs it again:
withBones(plotOutput("chart"), retry = "chart_retry")
output$chart <- renderPlot({
input$chart_retry
make_chart(data())
})Use ns("chart") and ns("chart_retry") in a
module UI. Read input$chart_retry in its server. Several
outputs can share one retry id. retry = NULL adds no
button. retry with error = FALSE gives an
error. If the output does not start calculating, the next Shiny idle
event restores the error panel.
Show a skeleton before an output starts
Give hold one or more input ids. The skeleton appears as
soon as an input changes, even if the app waits before it updates the
output:
ui <- fluidPage(
actionButton("refresh", "Refresh"),
withBones(textOutput("result"), hold = "refresh")
)
server <- function(input, output, session) {
value <- reactiveVal("Ready")
observeEvent(input$refresh, {
Sys.sleep(1) # Stand-in for work before the output is invalidated.
value(paste("Refresh", input$refresh))
})
output$result <- renderText(value())
}Use hold = c("refresh", "filter") for several inputs. In
modules, pass each id through ns().
bones_auto() accepts both retry and
hold. If this output does not start calculating, the hold
releases when Shiny is idle. A delay that crosses an idle event
therefore needs an explicit hold.
App JavaScript can call Bones.hold("result") to start a
hold and Bones.release("result") to end it. The argument
can also be the output element or its wrapper element. An explicit hold
survives idle events until it is released or the next load finishes. An
unknown id does nothing.
Use this when the output changes after Shiny is idle, for example
after later::later() or a poll. Shiny is idle in the gap,
so hold would let the skeleton go. Start the hold in the
browser when the button is clicked:
ui <- fluidPage(
actionButton("refresh", "Refresh"),
withBones(textOutput("result")),
tags$script(HTML(
"$(document).on('click', '#refresh', function () { Bones.hold('result'); });"
))
)
server <- function(input, output, session) {
value <- reactiveVal("Ready")
observeEvent(input$refresh, {
n <- input$refresh
# The server is idle while it waits. The hold keeps the skeleton.
later::later(function() value(paste("Refresh", n)), 2)
})
output$result <- renderText(value())
}The hold ends when result gets its new value.
A hold hides the content but keeps its space. It shows the current
skeleton, including a learned shape, at once. It overrides
stale and delay. After a value,
min_time is measured from the start of the hold. An error
clears the hold and shows the error panel at once. An explicit release
or idle recovery does not wait for min_time.
Set the look for the whole app
bones_defaults() sets the animation, the colours and the
speed for the session. Call it before you build the UI, for example in
global.R. The options are read when the UI is built. An
argument to withBones() is stronger than a default:
bones_defaults(
animation = "pulse", # "wave" (the default), "pulse", "cascade", "sweep" or "none"
radius = "0.5rem",
speed = 2,
stale = FALSE
)The default colours come from the theme of the page: the text colour of the bslib theme, made faint. A skeleton thus takes the tint of a branded theme, and turns light in a dark theme, with no configuration. With no Bootstrap 5 theme, the colours come from the text colour where the skeleton is. Users who ask their system to reduce motion get no animation.
Set the colours in CSS
An app with its own CSS, with or without Bootstrap, can set the
colours with CSS custom properties. Set them on :root for
the whole page, or on a container for one part of it:
:root {
--bones-text: #1d3557; /* the other colours are made from this one */
--bones-surface: #ffffff; /* the page background: the sweep band, the error panel */
--bones-radius: 6px;
}
.dark-panel {
--bones-text: #f1faee;
--bones-surface: #1d3557;
}| Property | Sets | Default |
|---|---|---|
--bones-text |
The colour that the others are made from | The Bootstrap text colour, else the text colour |
--bones-surface |
The page background | The Bootstrap background, else white |
--bones-color |
The bars |
--bones-text at 10% |
--bones-highlight |
Borders and the moving part of the animation |
--bones-text at 19% |
--bones-stripe |
The stripes and headers of a table, and the background of a map |
--bones-text at 4% |
--bones-sweep |
The band of the sweep animation |
--bones-surface at 55% |
--bones-radius |
The rounding of the bars | 75% of the Bootstrap rounding |
--bones-speed |
The length of one animation cycle | 1.4s |
bones_defaults() and the color and
speed arguments of withBones() write the same
properties on each output. They are stronger than a value from your CSS.
The delay before a skeleton appears is set in R only, with the
delay argument or bones_defaults().
On a dark page with no Bootstrap, set --bones-surface to
a light colour, or set --bones-sweep. Otherwise the sweep
band is the dark page colour, and it looks like a shadow.
To change one output only, give speed or
color to withBones():
withBones(plotOutput("chart"), animation = "pulse", speed = 0.8, color = "#dbeafe")bones_animations() lists the animations, and
bones_shapes() the shapes.
A placeholder with no output
bones_skeleton() makes a skeleton on its own, for a
place where there is no Shiny output:
output$panel <- renderUI({
if (is.null(data())) return(bones_skeleton("table", rows = 5))
tableOutput("results")
})