🎇 Sparkler: Visual Delight for R

Sparkler is an R package designed to bring joy, delight, and atmosphere to your Shiny apps, RMarkdown documents, and Quarto presentations.

Sparkler solves this by providing lightweight, high-performance visual engines: Confetti, Fireworks, and Atmospheric Weather. These render as full-screen overlays on top of your Shiny apps and RMarkdown documents.

Why use Sparkler?

• Gamification: Reward users with confetti when they submit a form or hit a target.
• Storytelling: Use rain, snow, or meteors to set the mood for your data narrative.
• Zero-Footprint: The effects use a custom Overlay Architecture (Z-index 9999), meaning they float over your app without breaking your Bootstrap layout or blocking mouse clicks.

📦 Installation

You can install the package directly from R-Universe:

install.packages("sparkler", repos = c("https://codingtigertang.r-universe.dev", "https://cloud.r-project.org"))

Alternatively, you can install the development version from GitHub:

# install.packages("devtools")
devtools::install_github("CodingTigerTang/sparkler")

🎮 Interactive Demo

Option 1: Try it Online

Click the image below to launch the live demo app.

Option 2: Run Locally

library(sparkler)
sparkler::run_demo()

🖥️ Running in R Console

You don’t need Shiny to see the magic! You can run these functions directly in your R console to test them. They will render inside the RStudio Viewer pane.

1. Confetti

Best for instant feedback (buttons, success messages).

# Pop some confetti in the viewer
sparkler::confetti()

2. Fireworks

Best for major milestones. Runs for a set duration.

# Launch a fireworks show
sparkler::fireworks()

3. Atmospheric Weather

Continuous effects (snow, rain, meteors).

# Watch a meteor shower
# Note: In the console, weather renders with a dark background so particles are visible.
sparkler::weather(type = "meteor")

# Snowy day
sparkler::weather(type = "snow")

💻 How to Use in Shiny

Using Sparkler in Shiny requires a slightly different mental model than standard plots.

The Concept: You place an Output function in your UI, but unlike a plot, it takes up 0 pixels of space. It acts as an invisible “antenna.” When you send data to it from the Server, it triggers the JavaScript engine to paint over the whole screen.

Minimal Shiny Example

library(shiny)
library(sparkler)

ui <- fluidPage(
  titlePanel("Sales Dashboard"),
  
  # 1. The Trigger
  actionButton("btn_success", "Close Deal"),
  
  # 2. The Invisible Antenna (Place this anywhere in UI)
  confettiOutput("celebration_effect")
)

server <- function(input, output) {
  
  # 3. The Logic
  observeEvent(input$btn_success, {
    output$celebration_effect <- renderConfetti({
      # Triggers the effect
      confetti(particle_count = 150, spread = 100) 
    })
  })
}

shinyApp(ui, server)

📄 How to Use in RMarkdown / Quarto

Sparkler works automatically in HTML documents. There are two distinct ways to use the Weather effect in reports.

Mode 1: The “Atmospheric Overlay” (Fullscreen)

This makes the rain or snow cover the entire webpage, scrolling with the user. Perfect for immersive reports.

library(sparkler)
# The 'fullscreen = TRUE' argument forces the overlay
sparkler::weather(type = "snow", density = 2, fullscreen = TRUE)

Mode 2: The “Visual Block” (Inline)

If you leave fullscreen as NULL or FALSE, the weather renders inside a specific box, behaving like a standard plot.

# This creates a 300px box with rain inside it
sparkler::weather(type = "rain", speed = 2, height = "300px")

⚖️ Credits & Licenses

This package utilizes the following open-source assets:

JavaScript Libraries

1. canvas-confetti
   • Author: Kiril Vatev (catdad)
   • License: ISC
   • Source: https://github.com/catdad/canvas-confetti
2. fireworks-js
   • Author: Vitalij Ryndin (crashmax-dev)
   • License: MIT
   • Source: https://github.com/crashmax-dev/fireworks-js

---

Created with ❤️ using htmlwidgets.