Create a Shiny Tree — shinyTree • shinyTree

This creates a spot in your Shiny UI for a shinyTree which can then be filled in using renderTree.

Usage

shinyTree(
  outputId,
  checkbox = FALSE,
  search = FALSE,
  searchtime = 250,
  searchplaceholder = "",
  dragAndDrop = FALSE,
  types = NULL,
  theme = "default",
  themeIcons = TRUE,
  themeDots = TRUE,
  sort = FALSE,
  unique = FALSE,
  wholerow = FALSE,
  stripes = FALSE,
  multiple = TRUE,
  animation = 200,
  contextmenu = FALSE,
  three_state = TRUE,
  whole_node = TRUE,
  tie_selection = TRUE,
  state = FALSE,
  state_priority = c("saved", "code")
)

Arguments

outputId: The ID associated with this element
checkbox: If TRUE, will enable checkboxes next to each node to make the selection of multiple nodes in the tree easier.
search: If TRUE, will enable search functionality in the tree by adding a search box above the produced tree. Alternatively, you can set the parameter to the ID of the text input you wish to use as the search field.
searchtime: How long to wait, in milliseconds, after the user stops typing before searching. Default is 250ms.
searchplaceholder: Add a placeholder value to the search box. Only used when search = TRUE, since a search field given by its id has its own.
dragAndDrop: If TRUE, will allow the user to rearrange the nodes in the tree.
types: A JavaScript object literal, as a string, giving jsTree's types settings: each type's icon, valid children and so on. Nodes are given a type with the sttype attribute. It is written into the page as JavaScript, not parsed as JSON, so single quotes work; see the 12-types example and https://www.jstree.com/plugins/.
theme: jsTree theme, one of default, default-dark, or proton.
themeIcons: If TRUE, will show theme icons for each item.
themeDots: If TRUE, will include level dots.
sort: If TRUE, will sort the nodes in alphabetical/numerical order.
unique: If TRUE, will ensure that no node name exists more than once.
wholerow: If TRUE, will highlight the whole selected row.
stripes: If TRUE, the tree background is striped.
multiple: If TRUE, multiple nodes can be selected.
animation: The open / close animation duration in milliseconds. Set this to FALSE to disable the animation (default is 200).
contextmenu: If TRUE, will enable a contextmenu to create/rename/delete/cut/copy/paste nodes. jsTree cannot show checkboxes and the contextmenu together, so checkbox is then turned off, with a warning.
three_state: If TRUE, checking a node cascades to its children, and a parent is shown checked only while all of its children are (and as undetermined while some are).
whole_node: If TRUE, clicking anywhere on a node toggles its checkbox, as if the box itself were clicked. If FALSE, only the box does; clicking the label behaves as it would without checkboxes.
tie_selection: If TRUE, checked and selected are the same thing: ticking a box selects the node and selecting a node ticks its box, so get_checked and get_selected report the same nodes. If FALSE, checking is kept separate from the selection, so a node can be checked without being selected. With whole_node = TRUE as well, every click toggles a checkbox and nothing can be selected by clicking.
state: If TRUE, the browser remembers which nodes were open, selected and checked, and restores them when the page is reloaded. A string does the same and is used as the key the state is stored under, instead of the default "shinyTree-<outputId>". FALSE (the default) turns it off. See Remembering state below.
state_priority: Only used with state. When the remembered state disagrees with the stopened, stselected or stchecked attributes the tree was rendered with: "saved" (the default) restores what the user had; "code" keeps the app's attributes and restores the rest around them.

Value

A tag list holding the tree and the scripts and stylesheets it needs, for the app's UI.

Details

A shinyTree is an output and an input element at the same time. While you can fill it via renderTree you can access its content via input$tree (for example after the user rearranged some nodes). By default, input$tree will return a list similar to the one you use to fill the tree. This behaviour is controlled by getOption("shinyTree.defaultParser"). It defaults to "list", but can be set to "tree", in which case a data.tree is returned (see Options).

Any valid Shiny id can be used, including one containing . or -, as Shiny modules produce.

Checked and selected nodes

Without checkboxes, clicking a node selects it and get_selected reports the selection. With checkbox = TRUE, tie_selection decides whether a checked node counts as selected; see its description above. The 04-selected example shows get_selected and get_checked side by side and can switch between every combination of tie_selection, whole_node and three_state.

Remembering state

With state set, the browser remembers how the user left the tree and puts it back that way when the page is reloaded:


shinyTree("tree", checkbox = TRUE, state = TRUE)

What is remembered: Which nodes are open, which are selected and, with tie_selection = FALSE, which are checked. It is saved each time one of these changes.
When it is restored: Once, the first time the tree is filled after the page loads. A tree sent later by updateTree or by the render function running again is shown exactly as the server sent it, since it may be a different tree.
How nodes are matched: By their path of names from the root, such as Europe / France / Paris. A remembered node is restored only if a node with that path still exists, so a node that has been renamed, moved or removed is simply not restored, and a remembered state can never be applied to an unrelated node. Where siblings share a name, each of them matches.
Which wins: When the remembered state disagrees with the stopened, stselected or stchecked attributes the tree was rendered with, state_priority = "saved" (the default) restores what the user had, and state_priority = "code" keeps the app's attributes and restores the rest of the remembered state around them. With "code" a node the app opens or selects is always open or selected after a reload; with "saved" the user can close or deselect it and that is remembered.
What the server sees: The restored state is reported in input$tree like any change the user makes, in a single update.

The state is kept in the browser's localStorage, so it is per browser and per user, survives closing the browser, and is never sent to the server. It is stored under "shinyTree-<outputId>" unless state is a string, which is used as the key instead. Pages from the same server share localStorage, so two apps there whose trees have the same id should pass different keys. To forget a remembered state, use a new key, or run localStorage.removeItem("<key>") in the browser.

Options

shinyTree.defaultParser: What input$tree holds: "list" (the default), a nested list like the one passed to renderTree, or "tree", a data.tree Node, which needs the data.tree package. A data.tree cannot hold siblings with the same name, so the "tree" parser warns if the tree has any. It can be set before or after the package is loaded.
shinyTree.refresh: TRUE to report refresh.jstree events. Default FALSE.
shinyTree.setState: TRUE to report set_state.jstree events. Default FALSE.

The last two must be set before the UI is built, as they are written into the page. They only matter for refreshes started in the browser, e.g. by the app's own JavaScript: a tree sent by renderTree or updateTree is reported once it has loaded either way, and the refresh that loads it is not reported again – that caused a feedback loop in apps that call updateTree from an observer watching input$tree.

Examples

if (interactive()) {
  library(shiny)

  # The tree comes back the way the user left it when the page is reloaded.
  # Europe starts open and Paris selected; with state_priority = "code" they
  # stay that way after every reload, and anything else the user opened or
  # selected is restored as well.
  ui <- fluidPage(
    shinyTree("tree", state = TRUE, state_priority = "code")
  )
  server <- function(input, output, session) {
    output$tree <- renderTree(list(
      Europe = structure(list(
        France = list(Paris = structure("", stselected = TRUE), Lyon = ""),
        Spain = list(Madrid = "")
      ), stopened = TRUE),
      Asia = list(Japan = list(Tokyo = ""))
    ))
  }
  shinyApp(ui, server)
}

# See also the 26-state example:
if (interactive()) {
  shiny::runApp(system.file("examples/26-state", package = "shinyTree"))
}