Include 'Lottie' Functionality within 'shiny'

Description

Responsible for retrieving the 'Lottie' library and initialising the necessary 'JavaScript' library. As such, this function must be included within the UI object of a shinyApp in order to enable 'shinyLottie' functionality.

Usage

include_lottie(version = "5.12.2")

Arguments

Value

A list of HTML tags to be included within the head element of a 'shiny' application.

Note

Calling this function initialises a global object "window.lottieInstances" once the DOM content is fully loaded. This is used to store the 'Lottie' animations that are created using lottie_animation.

Examples

library(shiny)
library(shinyLottie)

ui <- fluidPage(
  include_lottie(),
  lottie_animation(
    path = "shinyLottie/example.json",
    name = "my_animation"
  )
)

server <- function(input, output, session) {}

shinyApp(ui, server)

Add Event Listener to 'Lottie' Animation

Description

Adds an event listener to a 'Lottie' animation within a 'shiny' application. It is also possible to apply multiple event listeners to a single animation.

Usage

lottie_addEventListener(
  animation,
  event,
  target,
  ...,
  session = shiny::getDefaultReactiveDomain()
)

Arguments

Details

This function has several usage options:

• Supplying an animation object created by the lottie_animation function, and placing the resultant list object in the 'shiny' UI.

• Outside of a reactive context, supplying the name of the animation and placing the resultant script object in the 'shiny' UI.

• Within a reactive context, supplying the name of the animation.

When run within a reactive context, sends a custom session message "lottie_js_runJS" containing the function arguments.

Target Options

• "animation": Attaches the event listener directly to the 'Lottie' animation instance. This is necessary when using a Lottie-specific event (e.g. "onComplete"). See https://airbnb.io/lottie/#/web for further details.

• "container": Attaches the event listener to the container div of the 'Lottie' animation. This should be used when using a generic HTML event, such as "mouseenter" or "mouseleave".

Value

If used within a reactive context, the function will execute the necessary 'JavaScript'. Otherwise, it will return a script tag containing the 'JavaScript'.

Note

Using the custom_js argument, it is possible to assign 'shiny' input values when an event is triggered, see lottie_removeEventListener for an example.

Examples

library(shiny)
library(shinyLottie)

ui <- fluidPage(
  include_lottie(),
  # Create an 'animation' event listener that prints a message to the
  # browser console after each loop
  lottie_animation(
    path = "shinyLottie/example.json",
    name = "my_animation"
  ) |>
  lottie_addEventListener(
    event = "loopComplete",
    target = "animation",
    custom_js = "console.log('Animation Complete!');"
  ),
  # Create a 'container' event listener that plays an animation when
  # hovering over the button, and another that pauses the animation
  # when hovering stops
  lottie_animation(
    path = "shinyLottie/example.json",
    name = "button",
    width = "200px",
    height = "100px",
    loop = TRUE,
    autoplay = FALSE,
  ) |> lottie_button(inputId = "lottieButton", label = "Lottie",
                     height = "200px", width = "200px") |>
    lottie_addEventListener("mouseenter", "container", state = "play") |>
    lottie_addEventListener("mouseleave", "container", state = "pause")
)

server <- function(input, output, session) {}

shinyApp(ui, server)

Generate 'Lottie' Animation for a 'shiny' application

Description

Generates a 'Lottie' animation for use within a 'shiny' application.

Usage

lottie_animation(
  path,
  name,
  loop = TRUE,
  autoplay = TRUE,
  renderer = "svg",
  width = "400px",
  height = "400px",
  ...,
  session = shiny::getDefaultReactiveDomain()
)

Arguments

Value

A list containing the following elements:

div

An HTML div element serving as the 'Lottie' animation container.

script

A script tag containing the 'JavaScript' to initialise the 'Lottie' animation.

Note

When using a local file path, you may need to use addResourcePath.

Examples

library(shiny)
library(shinyLottie)

ui <- fluidPage(
  include_lottie(),
  lottie_animation(
    path = "shinyLottie/example.json",
    name = "my_animation"
  )
)

server <- function(input, output, session) {}

shinyApp(ui, server)

'Lottie' Animation Methods

Description

These functions provide methods for modifying the playback options of existing 'Lottie' animations.

Details

• lottie_setSpeed: Set the speed of the animation.

• lottie_setDirection: Set the direction of the animation.

• lottie_setLoop: Set whether the animation should loop.

• lottie_goToAndStop: Move to a specific frame or time and stop.

• lottie_goToAndPlay: Move to a specific frame or time and play.

• lottie_playSegments: Play specific segments of the animation.

• lottie_setSubframe: Set whether to use subframes when rendering the animation.

• lottie_destroy: Destroy the specified animation instance.

Convert a 'Lottie' Animation to a Button

Description

Wraps a 'Lottie' animation within a button element for use in 'shiny' applications.

Usage

lottie_button(
  animation,
  inputId,
  label = NULL,
  width = NULL,
  height = NULL,
  ...
)

Arguments

Value

An HTML button element enclosing the animation input object.

Examples

library(shiny)
library(shinyLottie)

ui <- fluidPage(
  include_lottie(),
  lottie_animation(
    path = "shinyLottie/example.json",
    name = "my_animation",
    height = "100px",
    width = "100px"
  ) |> lottie_button(inputId = "my_button")
)

server <- function(input, output, session) {
  observeEvent(input$my_button, {
    print("Button pressed")
  })
}

shinyApp(ui, server)

Call a 'Lottie' Method

Description

Call a method for a specific 'Lottie' animation or all 'Lottie' animations.

Usage

lottie_callMethod(
  name = "all",
  method,
  argument = "",
  session = shiny::getDefaultReactiveDomain()
)

Arguments

Details

Sends a custom session message "lottie_js_callMethod" containing the function arguments.

Value

This function is called for a side effect, and so there is no return value.

Examples

library(shiny)
library(shinyLottie)

ui <- fluidPage(
  include_lottie(),
  lottie_animation(
    path = "shinyLottie/example.json",
    name = "my_animation"
  ),
  actionButton("callMethod", "Call Method (Reverse Direction)")
)

server <- function(input, output, session) {
  observeEvent(input$callMethod, {
    lottie_callMethod(name = "my_animation", method = "setDirection", argument = "-1")
  })
}
shinyApp(ui, server)

Destroy a 'Lottie' Animation

Description

Permanently destroy a specific 'Lottie' animation or all 'Lottie' animations.

Usage

lottie_destroy(name = "all", session = shiny::getDefaultReactiveDomain())

Arguments

Details

Sends a custom session message "lottie_js_destroy" containing the function arguments.

Value

This function is called for a side effect, and so there is no return value.

See Also

lottie_animation_methods for similar methods.

Examples

library(shiny)
library(shinyLottie)

ui <- fluidPage(
  include_lottie(),
  lottie_animation(
    path = "shinyLottie/example.json",
    name = "my_animation"
  ),
  actionButton("destroy", "Destroy Animation")
)

server <- function(input, output, session) {
  observeEvent(input$destroy, {
    lottie_destroy("my_animation")
  })
}

shinyApp(ui, server)

Get a Property of a 'Lottie' Animation

Description

Get a property from a specific 'Lottie' animation or all 'Lottie' animations.

Usage

lottie_getProperty(
  property,
  name = "all",
  session = shiny::getDefaultReactiveDomain()
)

Arguments

Details

Sends a custom session message "lottie_js_getProperty" containing the function arguments.

Value

The return value(s) can be retrieved from within a reactive context by accessing the input object of the 'shiny' session, where the value has been assigned as the property name. For example, if accessing the playCount property, the return value can be retrieved via input$playCount.

If name = "all" has been specified, then the return object will be a list, with named elements corresponding to the animation names.

Examples

library(shiny)
library(shinyLottie)

ui <- fluidPage(
  include_lottie(),
  lottie_animation(
    path = "shinyLottie/example.json",
    name = "my_animation"
  ),
  actionButton("getProperty", "Update Play Count"),
  textOutput("playCountOutput")
)

server <- function(input, output, session) {
  observeEvent(input$getProperty, {
    lottie_getProperty(name = "my_animation", property = "playCount")
  })

  observe({
    req(input$playCount)
    output$playCountOutput <- renderText({
      paste("Play Count:", input$playCount)
    })
  })
}

 shinyApp(ui, server)

Navigate to a Specific Animation Frame

Description

Navigate to a specific frame or time and either stop or play the animation.

Usage

lottie_goToAndStop(
  value,
  isFrame = TRUE,
  name = "all",
  session = shiny::getDefaultReactiveDomain()
)

lottie_goToAndPlay(
  value,
  isFrame = TRUE,
  name = "all",
  session = shiny::getDefaultReactiveDomain()
)

Arguments

Details

lottie_goToAndStop moves the animation to a specific frame or time, then stops it. Sends a custom session message "lottie_js_goToAndStop" containing the function arguments.

lottie_goToAndPlay moves the animation to a specific frame or time, then continues playback. Sends a custom session message "lottie_js_goToAndPlay" containing the function arguments.

Value

These functions are called for a side effect, and so there is no return value.

See Also

lottie_animation_methods for similar methods.

Examples

library(shiny)
library(shinyLottie)

ui <- fluidPage(
  include_lottie(),
  lottie_animation(
    path = "shinyLottie/example.json",
    name = "my_animation"
  ),
  actionButton("goToAndStop", "Go To Frame 10 And Stop"),
  actionButton("goToAndPlay", "Go To Frame 10 And Play")
)

server <- function(input, output, session) {
  observeEvent(input$goToAndStop, {
    lottie_goToAndStop(value = 10, isFrame = TRUE, name = "my_animation")
  })

  observeEvent(input$goToAndPlay, {
    lottie_goToAndPlay(value = 10, isFrame = TRUE, name = "my_animation")
  })
}

shinyApp(ui, server)

Play Specific Segments of a 'Lottie' Animation

Description

Play specific segments of a 'Lottie' animation.

Usage

lottie_playSegments(
  segments,
  forceFlag = TRUE,
  name = "all",
  session = shiny::getDefaultReactiveDomain()
)

Arguments

Details

Sends a custom session message "lottie_js_playSegments" containing the function arguments.

Value

This function is called for a side effect, and so there is no return value.

Note

To play a single segment, segments should be a numeric vector of length 2 that represents the start and end frames. To play multiple segments, provide a list containing multiple numeric vectors of length 2. Note that if the animation is set to be looped, only the final segment will be repeated.

See Also

lottie_animation_methods for similar methods.

Examples

library(shiny)
library(shinyLottie)

ui <- fluidPage(
  include_lottie(),
  lottie_animation(
    path = "shinyLottie/example.json",
    name = "my_animation",
    loop = FALSE,
    speed = 0.5 # Slowed to make effects clearer
  ),
  actionButton("playSegments1", "Play Frames 1 - 10"),
  # Will not work if animation has less than 40 frames
  actionButton("playSegments2", "Play Frames 1 - 10 and 30 - 40")
)

server <- function(input, output, session) {
  observeEvent(input$playSegments1, {
    lottie_playSegments(segments = c(1, 10), forceFlag = TRUE,
      name = "my_animation")
  })

  observeEvent(input$playSegments2, {
    lottie_playSegments(segments = list(c(1, 10), c(30, 40)),
      forceFlag = TRUE, name = "my_animation")
  })
}

shinyApp(ui, server)

Control Playback of 'Lottie' Animations

Description

Control the playback of 'Lottie' animations within a 'shiny' application.

Usage

lottie_play(name = "all", session = shiny::getDefaultReactiveDomain())

lottie_pause(name = "all", session = shiny::getDefaultReactiveDomain())

lottie_stop(name = "all", session = shiny::getDefaultReactiveDomain())

Arguments

Details

Each function sends a corresponding custom session message containing the function arguments:

• Play: "lottie_js_play"

• Pause: "lottie_js_pause"

• Stop: "lottie_js_stop"

Value

These functions are called for a side effect, and so there is no return value.

Examples

library(shiny)
library(shinyLottie)

ui <- fluidPage(
  include_lottie(),
  lottie_animation(
    path = "shinyLottie/example.json",
    name = "my_animation"
  ),
  actionButton("play", "Play Animation"),
  actionButton("pause", "Pause Animation"),
  actionButton("stop", "Stop Animation")
)

server <- function(input, output, session) {
  observeEvent(input$play, {
    lottie_play(name = "my_animation")
  })

  observeEvent(input$pause, {
    lottie_pause(name = "my_animation")
  })

  observeEvent(input$stop, {
    lottie_stop(name = "my_animation")
  })
}

shinyApp(ui, server)

Remove Event Listener from 'Lottie' Animation

Description

Removes an event listener from a 'Lottie' animation within a 'shiny' application.

Usage

lottie_removeEventListener(
  name,
  event,
  target,
  functionName = NULL,
  session = shiny::getDefaultReactiveDomain()
)

Arguments

Details

When run within a reactive context, sends a custom session message "lottie_js_runJS" containing the function arguments.

Value

This function is called for a side effect, and so there is no return value.

Examples

library(shiny)
library(shinyLottie)

ui <- fluidPage(
  include_lottie(),
  # Create an 'animation' event that updates the 'playCount' input value
  # value after each loop
  lottie_animation(
    path = "shinyLottie/example.json",
    name = "my_animation"
  ) |>
    lottie_addEventListener(
      event = "loopComplete",
      target = "animation",
      custom_js = "Shiny.setInputValue('playCount',
      lottieInstances.my_animation.playCount, {priority: 'event'});"
    ),
  actionButton("removeEventListener", "Remove Event Listener")
)

server <- function(input, output, session) {
  # Notifications demonstrate that eventListener is active
  observeEvent(input$playCount, {
    showNotification(paste("Animation played", input$playCount, "times"), duration = 1)
  })

  # Removing the event listener ceases the notifications
  observeEvent(input$removeEventListener, {
    lottie_removeEventListener(name = "my_animation", event = "loopComplete",
                               target = "animation")
  })
}

shinyApp(ui, server)

Adjust 'Lottie' Animation Direction

Description

Adjust the playback direction of an existing 'Lottie' animation.

Usage

lottie_setDirection(
  direction = 1,
  name = "all",
  session = shiny::getDefaultReactiveDomain()
)

Arguments

Details

Sends a custom session message "lottie_js_setDirection" containing the function arguments.

Value

This function is called for a side effect, and so there is no return value.

See Also

lottie_animation_methods for similar methods.

Examples

library(shiny)
library(shinyLottie)

ui <- fluidPage(
  include_lottie(),
  lottie_animation(
    path = "shinyLottie/example.json",
    name = "my_animation"
  ),
  actionButton("forwards", "Play Forwards"),
  actionButton("backwards", "Play Backwards")
)

server <- function(input, output, session) {
  observeEvent(input$forwards, {
    lottie_setDirection(direction = 1, name = "my_animation")
  })

  observeEvent(input$backwards, {
    lottie_setDirection(direction = -1, name = "my_animation")
  })
}

shinyApp(ui, server)

Adjust 'Lottie' Animation Looping

Description

Adjust the looping behaviour of a 'Lottie' animation.

Usage

lottie_setLoop(flag, name = "all", session = shiny::getDefaultReactiveDomain())

Arguments

Details

Sends a custom session message "lottie_js_setLoop" containing the function arguments.

Value

This function is called for a side effect, and so there is no return value.

See Also

lottie_animation_methods for similar methods.

Examples

library(shiny)
library(shinyLottie)

ui <- fluidPage(
  include_lottie(),
  lottie_animation(
    path = "shinyLottie/example.json",
    name = "my_animation"
  ),
  actionButton("play", "Play"),
  actionButton("loopOn", "Loop On"),
  actionButton("loopOff", "Loop Off")
)

server <- function(input, output, session) {
  observeEvent(input$play, {
    # Non-looped animations can not be resumed without first being stopped
    lottie_stop(name = "my_animation")
    lottie_play(name = "my_animation")
  })

  observeEvent(input$loopOn, {
    lottie_setLoop(flag = TRUE, name = "my_animation")
  })

  observeEvent(input$loopOff, {
    lottie_setLoop(flag = FALSE, name = "my_animation")
  })
}

shinyApp(ui, server)

Adjust 'Lottie' Animation Speed

Description

Adjust the speed of an existing 'Lottie' animation.

Usage

lottie_setSpeed(
  speed = 1,
  name = "all",
  session = shiny::getDefaultReactiveDomain()
)

Arguments

Details

Sends a custom session message "lottie_js_setSpeed" containing the function arguments.

Value

This function is called for a side effect, and so there is no return value.

Note

A speed of 1 will apply the default animation speed. Use a value between 0 and 1 for a slower animation speed. Applying a negative speed will also reverse the playback direction.

See Also

lottie_animation_methods for similar methods.

Examples

library(shiny)
library(shinyLottie)

ui <- fluidPage(
  include_lottie(),
  lottie_animation(
    path = "shinyLottie/example.json",
    name = "my_animation"
  ),
  numericInput("speed", "Speed", value = 1),
  actionButton("updateSpeed", "Update Speed")
)

server <- function(input, output, session) {
  observeEvent(input$updateSpeed, {
    lottie_setSpeed(speed = input$speed, name = "my_animation")
  })
}

shinyApp(ui, server)

Set 'Lottie' Animation Subframe Rendering

Description

Adjust the subframe rendering of a 'Lottie' animation.

Usage

lottie_setSubframe(
  flag,
  name = "all",
  session = shiny::getDefaultReactiveDomain()
)

Arguments

Details

Sends a custom session message "lottie_js_setSubframe" containing the function arguments.

Value

This function is called for a side effect, and so there is no return value.

See Also

lottie_animation_methods for similar methods.

Examples

library(shiny)
library(shinyLottie)

ui <- fluidPage(
  include_lottie(),
  lottie_animation(
    path = "shinyLottie/example.json",
    name = "my_animation"
  ),
  actionButton("subframeOn", "Subframe On"),
  actionButton("subframeOff", "Subframe Off")
)

server <- function(input, output, session) {
  observeEvent(input$subframeOn, {
    lottie_setSubframe(flag = TRUE, name = "my_animation")
  })

  observeEvent(input$subframeOff, {
    lottie_setSubframe(flag = FALSE, name = "my_animation")
  })
}

shinyApp(ui, server)