Skip to contents

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:

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:

withBones(uiOutput("kpis"),  type = "value", n = 3)
withBones(uiOutput("cards"), type = "cards", n = 4)

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, n or skeleton. 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:
withBones(uiOutput("summary"), 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")
})