11 Bookmarks

Table of content for chapter 11

Chapter section list

By default, Shiny does not expose the current state of the app in its URL. To share the result of a special state you need some extra work and create bookmarks.

11.1 Basic idea

Let’s take a simple app that we want to make bookmarkable. This app draws Lissajous figures, which replicate the motion of a pendulum. This app can produce a variety of interesting patterns that you might want to share.

R Code 11.1 : Lissajous’sche figures

Procedure 11.1 : Creating bookmarks of Shiny states

There are three things to make Shiny apps bookmarkable:

Add a bookmarkButton() to the UI. This generates a button that the user clicks to generate the bookmarkable URL.
Turn ui into a function. You need to do this because bookmarked apps have to replay the bookmarked values: effectively, Shiny modifies the default value for each input control. This means there’s no longer a single static UI but multiple possible UIs that depend on parameters in the URL; i.e. it has to be a function.
Add enableBookmarking = "url" to the shinyApp() call.

R Code 11.2 : Lissajous’sche figures

“Generating a bookmark” means recording the current values of the inputs in the parameters of URL.

For example:

11.1.1 Updating the URL

Instead of providing an explicit button, another option is to automatically update the URL in the browser. This allows your users to use the user bookmark command in their browser, or copy and paste the URL from the location bar.

Automatically updating the URL requires a little boilerplate in the server function:

Code

# Automatically bookmark every time an input changes
observe({
  reactiveValuesToList(input)
  session$doBookmark()
})
# Update the query string
onBookmarked(updateQueryString)

12 Automatically bookmark every time an input changes

observe({ reactiveValuesToList(input) session$doBookmark() }) # Update the query string onBookmarked(updateQueryString)

R Code 12.1 : Lissajous’sche figures with URL updating automatially

12.0.1 Storing richer state

So far we’ve used enableBookmarking = "url" which stores the state directly in the URL. This a good place to start because it’s very simple and works everywhere you might deploy your Shiny app. As you can imagine, however, the URL is going to get very long if you have a large number of inputs, and it’s obviously not going to be able to capture an uploaded file.

For these cases, you might instead want to use enableBookmarking = "server", which saves the state to an .rds file on the server. This always generates a short, opaque, URL but requires additional storage on the server.

Code

shinyApp(ui, server, enableBookmarking = "server")

shinyapps.io doesn’t currently support server side bookmarking, so you’ll need to try this out locally. If you do so, you’ll see that the bookmark button generates URLs like:

http://127.0.0.1:4087/?state_id=0d645f1b28f05c97

Which are paired with matching directories in your working directory: shiny_bookmarks/0d645f1b28f05c97

The main drawbacks with server bookmarking is that it requires files to be saved on the server, and it’s not obvious how long these need to hang around for. If you’re bookmarking complex state and you never delete these files, your app is going to take up more and more disk space over time. If you do delete the files, some old bookmarks are going to stop working.

12.1 Bookmarking challenges

Automated bookmarking relies on the reactive graph. It seeds the inputs with the saved values then replays all reactive expressions and outputs, which will yield the same app that you see, as long as your app’s reactive graph is straightforward. This section briefly covers some of the cases which need a little extra care:

If your app uses random numbers, the results might be different even if all the inputs are the same. If it’s really important to always generate the same numbers, you’ll need to think about how to make your random process reproducible. The easiest way to do this is use repeatable(); see the documentation for more details.
If you have tabs and want to bookmark and restore the active tab, make sure to supply an id in your call to tabsetPanel().
If there are inputs that should not be bookmarked, e.g. they contain private information that shouldn’t be shared, include a called to setBookmarkExclude() somewhere in your server function. For example, setBookmarkExclude(c("secret1", "secret2")) will ensure that the secret1 and secret2 inputs are not bookmarked.
If you are manually managing reactive state in your own reactiveValues() object (as we’ll discuss in Chapter Chapter 16), you’ll need to use the onBookmark() and onRestore() callbacks to manually save and load your additional state. See Advanced Bookmarking for more details.

12.2 Exercises

12.2.1 Simplex noise generator

Generate app for visualizing the results of ambient::noise_simplex(). Your app should allow the user to control the frequency, fractal, lacunarity, and gain, and be bookmarkable. How can you ensure the image looks exactly the same when reloaded from the bookmark? (Think about what the seed argument implies).

12.2.2 Explore bookmarks of uploaded files

Make a simple app that lets you upload a csv file and then bookmark it. Upload a few files and then look in shiny_bookmarks. How do the files correspond to the bookmarks? (Hint: you can use readRDS() to look inside the cache files that Shiny is generating).

12.3 Glossary Entries

#> data frame with 0 columns and 0 rows

Session Info

Code

sessioninfo::session_info()

#> ─ Session info ───────────────────────────────────────────────────────────────
#>  setting  value
#>  version  R version 4.5.1 (2025-06-13)
#>  os       macOS Sequoia 15.5
#>  system   aarch64, darwin20
#>  ui       X11
#>  language (EN)
#>  collate  en_US.UTF-8
#>  ctype    en_US.UTF-8
#>  tz       Europe/Vienna
#>  date     2025-07-17
#>  pandoc   3.7.0.2 @ /opt/homebrew/bin/ (via rmarkdown)
#>  quarto   1.8.4 @ /usr/local/bin/quarto
#> 
#> ─ Packages ───────────────────────────────────────────────────────────────────
#>  package     * version    date (UTC) lib source
#>  cli           3.6.5      2025-04-23 [1] CRAN (R 4.5.0)
#>  curl          6.4.0      2025-06-22 [1] CRAN (R 4.5.0)
#>  digest        0.6.37     2024-08-19 [1] CRAN (R 4.5.0)
#>  evaluate      1.0.4      2025-06-18 [1] CRAN (R 4.5.0)
#>  fastmap       1.2.0      2024-05-15 [1] CRAN (R 4.5.0)
#>  glossary    * 1.0.0.9003 2025-06-08 [1] local
#>  htmltools     0.5.8.1    2024-04-04 [1] CRAN (R 4.5.0)
#>  htmlwidgets   1.6.4      2023-12-06 [1] CRAN (R 4.5.0)
#>  jsonlite      2.0.0      2025-03-27 [1] CRAN (R 4.5.0)
#>  knitr         1.50       2025-03-16 [1] CRAN (R 4.5.0)
#>  rlang         1.1.6      2025-04-11 [1] CRAN (R 4.5.0)
#>  rmarkdown     2.29       2024-11-04 [1] CRAN (R 4.5.0)
#>  rstudioapi    0.17.1     2024-10-22 [1] CRAN (R 4.5.0)
#>  rversions     2.1.2      2022-08-31 [1] CRAN (R 4.5.0)
#>  sessioninfo   1.2.3      2025-02-05 [1] CRAN (R 4.5.0)
#>  xfun          0.52       2025-04-02 [1] CRAN (R 4.5.0)
#>  xml2          1.3.8      2025-03-14 [1] CRAN (R 4.5.0)
#>  yaml          2.3.10     2024-07-26 [1] CRAN (R 4.5.0)
#> 
#>  [1] /Library/Frameworks/R.framework/Versions/4.5-arm64/library
#>  [2] /Library/Frameworks/R.framework/Versions/4.5-arm64/Resources/library
#>  * ── Packages attached to the search path.
#> 
#> ──────────────────────────────────────────────────────────────────────────────

# Bookmarks {#sec-chap11} ```{r} #| label: setup #| results: hold #| include: false base::source(file = "R/helper.R") library(glossary) glossary::glossary_path("../glossary-pb/glossary.yml") ``` ## Table of content for chapter 11 {.unnumbered} ::::: {#obj-chap03} :::: {.my-objectives} ::: {.my-objectives-header} Chapter section list ::: ::: {.my-objectives-container} ::: :::: ::::: By default, Shiny does not expose the current state of the app in its URL. To share the result of a special state you need some extra work and create bookmarks. ## Basic idea Let’s take a simple app that we want to make bookmarkable. This app draws [Lissajous figures](https://en.wikipedia.org/wiki/Lissajous_curve), which replicate the motion of a pendulum. This app can produce a variety of interesting patterns that you might want to share. :::{.column-page-inset} :::::{.my-r-code} :::{.my-r-code-header} :::::: {#cnj-11-lissajous-without-bookmarking} : Lissajous'sche figures :::::: ::: ::::{.my-r-code-container} ```{shinylive-r} #| standalone: true #| viewerHeight: 850 #| components: [editor, viewer] ## file: app.R {{< include apps_11/01-lissajous-figures/app.R >}} ``` :::: ::::: ::: :::::{.my-procedure} :::{.my-procedure-header} :::::: {#prp-11-creating-shiny-bookmarks} : Creating bookmarks of Shiny states :::::: ::: ::::{.my-procedure-container} There are three things to make Shiny apps bookmarkable: 1. Add a `bookmarkButton()` to the UI. This generates a button that the user clicks to generate the bookmarkable URL. 2. Turn ui into a function. You need to do this because bookmarked apps have to replay the bookmarked values: effectively, Shiny modifies the default `value` for each input control. This means there’s no longer a single static UI but multiple possible UIs that depend on parameters in the URL; i.e. it has to be a function. 3. Add `enableBookmarking = "url"` to the `shinyApp()` call. :::: ::::: :::{.column-page-inset} :::::{.my-r-code} :::{.my-r-code-header} :::::: {#cnj-11-lissajous-with-bookmarking} : Lissajous'sche figures :::::: ::: ::::{.my-r-code-container} ```{shinylive-r} #| standalone: true #| viewerHeight: 850 #| components: [editor, viewer] ## file: app.R {{< include apps_11/02-lissajous-with-bookmark/app.R >}} ``` :::: ::::: ::: “Generating a bookmark” means recording the current values of the inputs in the parameters of URL. For example: - <https://hadley.shinyapps.io/ms-bookmark-url/?_inputs_&damping=0.997&delta=1.37&length=500&omega=-0.9> or - <http://127.0.0.1:4087/?_inputs_&damping=0.997&delta=1.37&length=500&omega=-0.9> ### Updating the URL Instead of providing an explicit button, another option is to automatically update the URL in the browser. This allows your users to use the user bookmark command in their browser, or copy and paste the URL from the location bar. Automatically updating the URL requires a little boilerplate in the server function: ```{r} #| label: boilerplate-updating-url #| eval: false # Automatically bookmark every time an input changes observe({ reactiveValuesToList(input) session$doBookmark() }) # Update the query string onBookmarked(updateQueryString) ``` # Automatically bookmark every time an input changes observe({ reactiveValuesToList(input) session$doBookmark() }) # Update the query string onBookmarked(updateQueryString) :::{.column-page-inset} :::::{.my-r-code} :::{.my-r-code-header} :::::: {#cnj-11-lissajous-updating-url} : Lissajous'sche figures with URL updating automatially :::::: ::: ::::{.my-r-code-container} ```{shinylive-r} #| standalone: true #| viewerHeight: 850 #| components: [editor, viewer] ## file: app.R {{< include apps_11/03-lissajous-updating-url/app.R >}} ``` :::: ::::: ::: ### Storing richer state So far we’ve used `enableBookmarking = "url"` which stores the state directly in the URL. This a good place to start because it’s very simple and works everywhere you might deploy your Shiny app. As you can imagine, however, the URL is going to get very long if you have a large number of inputs, and it’s obviously not going to be able to capture an uploaded file. For these cases, you might instead want to use `enableBookmarking = "server"`, which saves the state to an `.rds` file on the server. This always generates a short, opaque, URL but requires additional storage on the server. ```{r} #| label: bookmarking-server #| eval: false shinyApp(ui, server, enableBookmarking = "server") ``` `shinyapps.io` doesn’t currently support server side bookmarking, so you’ll need to try this out locally. If you do so, you’ll see that the bookmark button generates URLs like: http://127.0.0.1:4087/?_state_id_=0d645f1b28f05c97 Which are paired with matching directories in your working directory: shiny_bookmarks/0d645f1b28f05c97 The main drawbacks with server bookmarking is that it requires files to be saved on the server, and it’s not obvious how long these need to hang around for. If you’re bookmarking complex state and you never delete these files, your app is going to take up more and more disk space over time. If you do delete the files, some old bookmarks are going to stop working. ## Bookmarking challenges Automated bookmarking relies on the reactive graph. It seeds the inputs with the saved values then replays all reactive expressions and outputs, which will yield the same app that you see, as long as your app’s reactive graph is straightforward. This section briefly covers some of the cases which need a little extra care: - If your app uses random numbers, the results might be different even if all the inputs are the same. If it’s really important to always generate the same numbers, you’ll need to think about how to make your random process reproducible. The easiest way to do this is use `repeatable()`; see the documentation for more details. - If you have tabs and want to bookmark and restore the active tab, make sure to supply an id in your call to `tabsetPanel()`. - If there are inputs that should not be bookmarked, e.g. they contain private information that shouldn’t be shared, include a called to `setBookmarkExclude()` somewhere in your server function. For example, `setBookmarkExclude(c("secret1", "secret2"))` will ensure that the `secret1` and `secret2` inputs are not bookmarked. - If you are manually managing reactive state in your own `reactiveValues()` object (as we’ll discuss in Chapter @sec-chap16), you’ll need to use the `onBookmark()` and `onRestore()` callbacks to manually save and load your additional state. See [Advanced Bookmarking](https://shiny.posit.co/r/articles/share/advanced-bookmarking/) for more details. ## Exercises {#sec-11-exercises} ### Simplex noise generator Generate app for visualizing the results of `ambient::noise_simplex()`. Your app should allow the user to control the frequency, fractal, lacunarity, and gain, and be bookmarkable. How can you ensure the image looks exactly the same when reloaded from the bookmark? (Think about what the seed argument implies). ### Explore bookmarks of uploaded files Make a simple app that lets you upload a csv file and then bookmark it. Upload a few files and then look in shiny_bookmarks. How do the files correspond to the bookmarks? (Hint: you can use readRDS() to look inside the cache files that Shiny is generating). ## Glossary Entries {#unnumbered} ```{r} #| label: glossary-table #| echo: false glossary_table() ``` ------------------------------------------------------------------------ ## Session Info {.unnumbered} ::: my-r-code ::: my-r-code-header Session Info ::: ::: my-r-code-container ```{r} #| label: session-info sessioninfo::session_info() ``` ::: :::