waiter R Package

The scope of the loading overlay is determined by the id passed to Waiter$new():

• Partial Overlay: Pass the id of a specific HTML element (e.g., Waiter$new("my-div-id")). The loading screen will only cover that specific element.
• Full Screen Overlay: Call Waiter$new() without an id argument. The loading screen will cover the entire application window.

# Partial: covers only the element with id "hello"
w1 <- Waiter$new("hello")

# Full screen: covers the whole app
w2 <- Waiter$new()

The waiter package uses different 'staff' abstractions depending on the type of loading indicator you want to display:

• waiter: Ideal for displaying a spinner.
• waitress and hostess: Designed to show progress (e.g., progress bars).

The waiter package provides different components depending on your UI needs:

The Waitress can be applied to specific elements or the entire page by providing a CSS selector during initialization.

• Whole Page: If no selector is provided to Waitress$new(), it applies to the entire page.
• Specific Elements: Provide a CSS selector like #plotId to target a specific element.
• Custom Ranges: You can define a custom range for the progress bar using min and max arguments. For example, if min = 0 and max = 10, calling inc(1) will increase the progress by 10% of the total range.

In use_waitress(), you can also customize the color of the loading bar.

# Target a specific element with a custom range
waitress <- Waitress$new("nav", theme = "overlay", min = 0, max = 10)

# Target the whole page with a custom color in UI
ui <- fluidPage(useWaitress(color = "#7F7FFF"))

The waiter package fires Shiny input events when a loading screen is shown or hidden. This allows you to trigger side effects in your R server code based on the waiter's state.

When a waiter is associated with an element id, the following input IDs are generated:

• input$<id>_waiter_shown
• input$<id>_waiter_hidden

If the waiter is used in full-screen mode (not overlaying a specific element), the events are simply input$waiter_shown and input$waiter_hidden.

# Example of observing waiter events
server <- function(input, output){
  w <- Waiter$new(id = "plot")

  # ... logic to show/hide waiter ...

  observeEvent(input$plot_waiter_hidden, {
    print(input$plot_waiter_hidden)
  })

  observeEvent(input$plot_waiter_shown, {
    print(input$plot_waiter_shown)
  })
}

If you cannot compute specific progress increments, use an infinite loading bar by setting infinite = TRUE in Hostess$new().

Important: When using infinite = TRUE, you must manually call hostess$start() to begin the animation and hostess$close() when the computation ends to stop it.

server <- function(input, output){
  hostess <- Hostess$new("loader", infinite = TRUE)
  
  hostess$start()
  
  # ... computation ...
  Sys.sleep(5)
  
  hostess$close()
  waiter_hide()
}

The Attendant family of functions allows you to display progress bars using Bootstrap's built-in progress bars. Unlike other waiter functions, the Attendant is permanently in the DOM (though it can be hidden) rather than being an overlay. This makes it ideal for progress reporting that shouldn't block the entire UI.

To use it, you must:

1. Include dependencies using useAttendant() in your UI.
2. Place attendantBar(id) in your UI where you want the bar to appear.
3. Create an Attendant object in your server using the same id to control its state.

ui <- fluidPage(
  useAttendant(),
  attendantBar("progress-bar")
)

server <- function(input, output){
  att <- Attendant$new("progress-bar")

  for(i in 1:10){
    Sys.sleep(runif(1))
    att$set(i * 10)
  }
}

To show a loading screen immediately when the app launches (before the Shiny session is fully established), use waiterShowOnLoad().

Important:

1. You must place waiterShowOnLoad() after useWaiter() in your UI.
2. Because this is not programmatically launched by the server, you must manually call waiter_hide() in your server logic to remove it once the app is ready.

ui <- fluidPage(
  useWaiter(), 
  waiterShowOnLoad(html = spin_fading_circles()),
  h3("Content visible after loading")
)

server <- function(input, output, session){
  Sys.sleep(3)
  waiter_hide()
}

The steward package allows you to animate the background of your loading screen.

To use it:

1. Include useSteward() in your Shiny UI.
2. Use waiterShowOnLoad() to define the initial loading state.

Example usage:

ui <- fluidPage(
  useWaiter(), 
  useSteward(),
  h3("Content you will only see after loading screen has disappeared"),
  waiterShowOnLoad(spin_fading_circles()) 
)

library(shiny)
library(waiter)
 
ui <- fluidPage(
  useWaiter(), 
  useSteward(),
  h3("Content you will only see after loading screen has disappeared"),
  waiterShowOnLoad(spin_fading_circles()) 
)

server <- function(input, output, session){
  Sys.sleep(10) # do something that takes time
  waiter_hide()
}

shinyApp(ui, server)