Pick a path through nested options – a region, then a country, then a city – from a dropdown of side-by-side columns.
Usage
el_cascader(
id = NULL,
options = list(),
value = NULL,
placeholder = "Please select",
props = NULL,
clearable = FALSE,
filterable = FALSE,
disabled = FALSE,
size = NULL,
show_all_levels = TRUE,
collapse_tags = FALSE,
separator = " / ",
debounce = 300,
popper_class = NULL,
filter_method = NULL,
before_filter = NULL,
label = NULL,
label_position = c("top", "left", "right"),
label_width = NULL,
label_suffix = NULL,
required = FALSE,
error = NULL,
show_message = TRUE,
inline_message = FALSE,
clear_icon = NULL,
collapse_tags_tooltip = NULL,
effect = NULL,
empty_values = NULL,
fallback_placements = NULL,
fit_input_width = NULL,
height = NULL,
item_size = NULL,
max_collapse_tags = NULL,
max_collapse_tags_tooltip_height = NULL,
persistent = NULL,
placement = NULL,
popper_append_to_body = NULL,
popper_style = NULL,
show_checked_strategy = NULL,
tag_effect = NULL,
tag_type = NULL,
teleported = NULL,
validate_event = NULL,
value_on_clear = NULL,
virtual_scroll = NULL,
width = NULL,
slots = NULL,
level_inputs = NULL,
events = NULL,
on = NULL,
session = NULL
)
update_el_cascader(
session = shiny::getDefaultReactiveDomain(),
id,
options = NULL,
value = NULL,
placeholder = NULL,
clearable = NULL,
filterable = NULL,
disabled = NULL,
label = NULL,
error = NULL,
props = NULL,
size = NULL,
show_all_levels = NULL,
collapse_tags = NULL,
separator = NULL,
debounce = NULL,
popper_class = NULL,
filter_method = NULL,
before_filter = NULL,
clear_icon = NULL,
collapse_tags_tooltip = NULL,
effect = NULL,
empty_values = NULL,
fallback_placements = NULL,
fit_input_width = NULL,
height = NULL,
item_size = NULL,
max_collapse_tags = NULL,
max_collapse_tags_tooltip_height = NULL,
persistent = NULL,
placement = NULL,
popper_append_to_body = NULL,
popper_style = NULL,
show_checked_strategy = NULL,
tag_effect = NULL,
tag_type = NULL,
teleported = NULL,
validate_event = NULL,
value_on_clear = NULL,
virtual_scroll = NULL
)Arguments
- id
Cascader ID (auto-generated if NULL)
- options
Nested options, each
list(value =, label =, children =).df_to_cascader_options()builds them from a data.frame.- value
Initially selected path, as a vector of values from the top level down – or a list of paths with
props = list(multiple = TRUE).- placeholder
Placeholder text
- props
Element's
props, as a named list:multiple,checkStrictly,expandTrigger("click"or"hover"),lazy,lazyLoad, and the field namesvalue,label,children,disabled,leaf. Withlazy = TRUEand nolazyLoadof your own, the server loads each column: see "Shiny inputs".- clearable
Whether clearable
- filterable
Whether filterable (searchable)
- disabled
Whether disabled
- size
Size of cascader:
"large","default"or"small".- show_all_levels
Whether to show all levels in input
Whether to collapse tags in multiple mode
- separator
Separator for display
- debounce
Debounce delay for filter
- popper_class
Extra class name for the dropdown panel.
- filter_method
JS()function filtering the options as the user types.- before_filter
JS()function called before filtering; returningfalsecancels it.- label
A label shown with the component, as Shiny's inputs have: text or a tag.
NULL, the default, shows none. It is the component's accessible name too – tied to it withforwhere the component has a native input that takes the id<id>-input, else witharia-labelledby.- label_position
Where the label sits, as
el_form()'slabel_position:"top"(the default, as Shiny's labels sit), or beside the component, its text aligned"left"or"right"– which shows oncelabel_widthgives the labels a common width.- label_width
Width of a label beside the component, as a CSS unit, so that several line up. Element's
label-width.- label_suffix
Text after the label, such as
":". Element'slabel-suffix.- required
Draw Element's red asterisk before the label. It marks the field; it does not check it – shinyvalidate or
el_form()does that.- error
An error message shown under the component in Element's style, the field framed in red. Element's
error.- show_message, inline_message
Whether
error's message is shown, and whether beside the component rather than under it. Element'sshow-messageandinline-message.- clear_icon
Custom clear icon component. Element Plus's
clear-icon(string / Component). An icon's name, such as"Search".Whether show all selected tags when mouse hover text of collapse-tags. To use this,
collapse-tagsmust be true. Element Plus'scollapse-tags-tooltip(boolean).- effect
Tooltip theme, built-in theme:
dark/light. Element Plus'seffect('dark' | 'light' / string).- empty_values
Empty values of component, see config-provider. Element Plus's
empty-values(array).- fallback_placements
List of possible positions for Tooltip popper.js. Element Plus's
fallback-placements(Placement[]).- fit_input_width
Whether the width of the suggestion panel is the same as the input, if the value is
number, then the width is fixed. Element Plus'sfit-input-width(boolean / number).- height
Menu height for virtual scrolling (px). Element Plus's
height(number).- item_size
Node height for virtual scrolling (px). Element Plus's
item-size(number).The max tags number to be shown. To use this,
collapse-tagsmust be true. Element Plus'smax-collapse-tags(number).Max height of collapse-tags tooltip. Element Plus's
max-collapse-tags-tooltip-height(string / number).- persistent
When dropdown is inactive and
persistentisfalse, dropdown will be destroyed. Element Plus'spersistent(boolean).- placement
Position of dropdown. Element Plus's
placement(enum).- popper_append_to_body
Whether to append the popper menu to body. If the positioning of the popper is wrong, you can try to set this prop to false. Element Plus's
popper-append-to-body(boolean).- popper_style
Custom style for Cascader's dropdown and tags' tooltip. Element Plus's
popper-style(string / object).- show_checked_strategy
Strategy for displaying checked nodes in multiple selection mode. Use
parentwhen you want things tidy. Usechildwhen every single item matters. Element Plus'sshow-checked-strategy('parent' | 'child').- tag_effect
Tag effect. Element Plus's
tag-effect('light' | 'dark' | 'plain').- tag_type
Tag type. Element Plus's
tag-type('success' | 'info' | 'warning' | 'danger').- teleported
Whether cascader popup is teleported. Element Plus's
teleported(boolean).- validate_event
Whether to trigger form validation. Element Plus's
validate-event(boolean).- value_on_clear
Clear return value, see config-provider. Element Plus's
value-on-clear(string / number / boolean / Function, ornull, which its documentation names): a value as it is, a function asJS(),nullasJS("null").NULLleaves Element's default.- virtual_scroll
Whether to enable virtual scrolling for large data. Element Plus's
virtual-scroll(boolean).- width
Component width, as a CSS unit –
"200px","50%", or a number taken as pixels. Element's own markup carries it, so it behaves like thewidthargument of a Shiny input.- slots
Named list of Element slot contents, such as
list(title = shiny::tags$b("Bold")). A shiny.element component given here is absorbed rather than nested. For a scoped slot, write the template withtemplate().- level_inputs
Each level of the path as an input of its own, beside
input$<id>: input ids, one per level from the top, such asc("compound", "study", "analysis")forinput$compound,input$studyandinput$analysis.NULL, the default, reports the path alone. See "Shiny inputs".- events
Element's events to report besides those reported unasked, by name:
events = "node_drop"reportsinput$<id>_node_drop. The component's are listed under "Shiny inputs", and byel_events(); a name it does not have is an error.- on
Handlers of your own, for an event not reported or to send something else: a named list of
JS()functions, one per event – Element's, or a DOM event with Vue's modifiers ("keyup.enter"). Each is called withreportand the event's arguments;report(name, value)setsinput$<id>_<name>. Seeel_widget().- session
In
el_cascader(), deprecated: inside a module, wrapidinns(), as for any Shiny input; a session given here namespacesidonce more, with a warning. Inupdate_el_cascader(), the Shiny session, the current one by default, as forshiny::updateTextInput().
Shiny inputs
| Input | Reported | Value |
input$<id> | unasked | the selected path |
input$<id>_lazy_load | unasked | with props = list(lazy = TRUE), a column to load; answer with el_load_children() |
input$<id>_expand_change | events = "expand_change" | triggers when expand option changes |
input$<id>_blur | events = "blur" | triggers when Cascader blurs |
input$<id>_focus | events = "focus" | triggers when Cascader focuses |
input$<id>_visible_change | events = "visible_change" | triggers when the dropdown appears/disappears |
input$<id>_remove_tag | events = "remove_tag" | triggers when remove tag in multiple selection mode |
input$<id>_clear | events = "clear" | triggers when the clear icon is clicked in a clearable Select |
The same list as el_events("el_cascader"), which says how an event's arguments travel.
With level_inputs, each level of the path is an input too, named as
given – not prefixed with the cascader's id, as the levels are the
cascader's value in parts rather than something it does. Each holds
that level's value, NULL where the path stops short (nothing
selected, or checkStrictly), and follows the path wherever it
changes: on load, when the user picks, when update_el_cascader() sets
it. Like any input, it notifies its observers only when its value
changes, so an observer of input$compound does not run again when
only the study changes. The ids are the page's: in a module, give them
through ns(), level_inputs = ns(c("compound", "study")), as the
cascader's own id. It needs the value to be one path, so not with
props = list(multiple = TRUE) or emitPath = FALSE.
input$<id>_lazy_load carries level (0 for the first column), value
and path of the option opened, and request. Answer with
el_load_children(), passing the input back; each child is list(value =, label =, leaf = TRUE) for one with nothing below.
Binding
Every argument can follow v_bind() or v_model() except label, label_position, label_width, label_suffix, required, error, show_message, inline_message (the form item around the component, drawn by R); width (the mount point's style); level_inputs (names inputs of the server's).
Updating from the server
update_el_cascader() changes the component from the server.
Every other argument of el_cascader() that can change once it is
drawn is an argument here too, under the same name. One left NULL
stays as it is; NA returns it to Element's default.
update_el_cascader() is called for its side effect and returns NULL invisibly.
Examples
# Basic cascader usage
cascader_options <- list(
list(
value = "guide",
label = "Guide",
children = list(
list(value = "principle", label = "Principle"),
list(value = "navigation", label = "Navigation")
)
),
list(
value = "component",
label = "Component",
children = list(
list(value = "basic", label = "Basic"),
list(value = "form", label = "Form", disabled = TRUE)
)
)
)
if (interactive()) {
library(shiny)
library(shiny.element)
ui <- el_page(
el_cascader(
id = "cascader1",
options = cascader_options,
placeholder = "Please select",
clearable = TRUE
),
verbatimTextOutput("selected")
)
server <- function(input, output, session) {
output$selected <- renderPrint(input$cascader1)
}
shinyApp(ui, server)
}
# Advanced: custom props and update
custom_props <- list(
expandTrigger = "hover",
multiple = FALSE,
checkStrictly = FALSE,
emitPath = TRUE,
lazy = FALSE,
value = "value",
label = "label",
children = "children"
)
# Update cascader options in server:
# update_el_cascader(session, "cascader1", options = new_options)
if (interactive()) {
# inside a server function
observeEvent(input$go, {
update_el_cascader(session, "region", value = list("zj", "hz"))
})
}