Rich Tree View - Selection • muiTreeView

Original MUI X documentation: Rich Tree View - Selection. The examples of this page are written for R.

library(muiTreeView)
library(htmltools)

The examples of this page use a selection of the functions of the muiMaterial, muiCharts and reactRouter packages, grouped by package and topic:

to_id <- function(x) gsub("[^a-z0-9]+", "-", tolower(x))

fns <- rbind(
  data.frame(package = "muiMaterial", group = "Layout", fn = c("Box", "Stack", "Grid")),
  data.frame(package = "muiMaterial", group = "Inputs", fn = c("Button", "TextField", "Slider", "Switch")),
  data.frame(package = "muiMaterial", group = "Navigation", fn = c("Link", "Tabs", "Drawer")),
  data.frame(package = "muiMaterial", group = "Surfaces", fn = c("AppBar", "Toolbar", "Card")),
  data.frame(package = "muiCharts", group = "Charts", fn = c("BarChart", "LineChart", "PieChart", "Gauge")),
  data.frame(package = "muiCharts", group = "Building blocks", fn = c("ChartsContainer", "ChartsXAxis", "ChartsLegend", "Toolbar")),
  data.frame(package = "reactRouter", group = "Routers", fn = c("RouterProvider", "createHashRouter", "createMemoryRouter")),
  data.frame(package = "reactRouter", group = "Routes", fn = c("Route", "Outlet")),
  data.frame(package = "reactRouter", group = "Navigation", fn = c("Link", "NavLink", "Navigate")),
  data.frame(package = "reactRouter", group = "Hooks", fn = c("useParams", "useLoaderData", "useNavigate"))
)
# Stable ids, built from the path: "Navigation", "Link" and "Toolbar" exist in two packages
fns$group_id <- paste(fns$package, to_id(fns$group), sep = "-")
fns$fn_id <- paste0(fns$package, "::", fns$fn)

fn_items <- asMuiTree(
  fns,
  levels = c("package", "group", "fn"),
  levels_id = c("package", "group_id", "fn_id")
)

Single selection

By default, one item can be selected at a time: click on an item, or focus it and press Space. MUI docs

RichTreeView(items = fn_items)

Multi-selection

Use multiSelect = TRUE to select several items: hold Ctrl (⌘ Command on macOS) while clicking, or Shift to select a range. MUI docs

RichTreeView(items = fn_items, multiSelect = TRUE)

Disable selection

Use disableSelection = TRUE to prevent the selection of all items. MUI docs

RichTreeView(items = fn_items, disableSelection = TRUE)

Checkbox selection

Use checkboxSelection = TRUE to render a checkbox next to each item. Combine it with multiSelect = TRUE to check several items. MUI docs

RichTreeView(items = fn_items, checkboxSelection = TRUE)

RichTreeView(items = fn_items, checkboxSelection = TRUE, multiSelect = TRUE)

Selectable items

Use isItemSelectionDisabled to make some items unselectable; their checkbox is hidden. It is a JavaScript function that receives an item and returns TRUE to prevent its selection. Here, only the functions can be selected, not the packages and groups: MUI docs

RichTreeView(
  items = fn_items,
  checkboxSelection = TRUE,
  multiSelect = TRUE,
  defaultExpandedItems = list("muiCharts", "muiCharts-charts", "muiCharts-building-blocks"),
  isItemSelectionDisabled = JS("(item) => item.children && item.children.length > 0")
)

Default selection

Use defaultSelectedItems to select items when the tree is created. With multiSelect = TRUE, give the ids in a list(). Here, the ids are computed from the data frame: all the React hooks, whose names start with use. MUI docs

hooks <- fns$fn_id[startsWith(fns$fn, "use")]
hooks
#> [1] "reactRouter::useParams"     "reactRouter::useLoaderData"
#> [3] "reactRouter::useNavigate"

RichTreeView(
  items = fn_items,
  checkboxSelection = TRUE,
  multiSelect = TRUE,
  defaultExpandedItems = list("reactRouter", "reactRouter-hooks"),
  defaultSelectedItems = as.list(hooks)
)

Controlled selection

Use selectedItems with onSelectedItemsChange to control the selection from your app, for example from the Shiny server with renderReact(). See controlled state in Shiny. MUI docs

onSelectedItemsChange receives the ids of all the selected items. In Shiny, use onSelectedItemsChange = setInput("selected", 1) to get them in input$selected, then filter the data frame with them. On this page, a JS() function writes them below the tree:

div(
  RichTreeView(
    items = fn_items,
    checkboxSelection = TRUE,
    multiSelect = TRUE,
    onSelectedItemsChange = JS(
      "(event, itemIds) => { document.getElementById('rtv-selected').textContent = JSON.stringify(itemIds); }"
    )
  ),
  tags$pre("Selected items: ", tags$span(id = "rtv-selected", "[]"))
)

Selected items: 
[]

Track item selection change

Use onItemSelectionToggle to know which item was just selected or deselected. It receives the event, the item id and whether the item is now selected. MUI docs

div(
  RichTreeView(
    items = fn_items,
    checkboxSelection = TRUE,
    multiSelect = TRUE,
    onItemSelectionToggle = JS(
      "(event, itemId, isSelected) => {
        document.getElementById('rtv-toggle').textContent =
          itemId + (isSelected ? ' was selected' : ' was deselected');
      }"
    )
  ),
  tags$pre(tags$span(id = "rtv-toggle", "No item selection recorded"))
)

No item selection recorded

Automatic parents and children selection

With multiSelect = TRUE, use selectionPropagation to select the children of a selected parent (descendants = TRUE), and the parent when all its children are selected (parents = TRUE). MUI docs

RichTreeView(
  items = fn_items,
  checkboxSelection = TRUE,
  multiSelect = TRUE,
  defaultExpandedItems = list("reactRouter", "reactRouter-navigation"),
  selectionPropagation = list(descendants = TRUE, parents = TRUE)
)

Propagation with disabled items

Disabled items are skipped by the propagation, and they are not needed for their parent to be selected. Here, Navigate() is disabled. MUI docs

RichTreeView(
  items = fn_items,
  checkboxSelection = TRUE,
  multiSelect = TRUE,
  defaultExpandedItems = list("reactRouter", "reactRouter-navigation"),
  selectionPropagation = list(descendants = TRUE, parents = TRUE),
  isItemDisabled = JS("(item) => item.id === 'reactRouter::Navigate'")
)

Apply propagation on mount

Applying the propagation to the default selection needs a React hook, which is not available from R. Compute the full selection in R instead, as in the default selection example above. MUI docs

Imperative API

The MUI imperative API (apiRef, to select an item or read its selection status from JavaScript) relies on a React hook, which is not available from R. MUI docs