Package {shiny.element}

shiny.element: 'Element Plus' Components for 'shiny'

Description

'Element Plus' ('Vue' 3) components for 'shiny': forms, tables, trees, menus, dialog boxes and the rest, each reporting to the server and updated from it like any other 'shiny' input. 'Element Plus' and 'Vue' are bundled, so applications work offline.

Author(s)

Maintainer: Kaiping Yang 1260146556@qq.com

Authors:

• Kaiping Yang 1260146556@qq.com

Other contributors:

• Element Plus team (Element Plus and its icons, bundled in inst/element-plus, MIT licence) [contributor, copyright holder]

• Evan You (Vue library bundled in inst/vue3, MIT licence) [contributor, copyright holder]

See Also

Useful links:

• https://kaipingyang.github.io/shiny.element/

• https://github.com/kaipingyang/shiny.element

• Report bugs at https://github.com/kaipingyang/shiny.element/issues

Take a component apart so it can be rendered inside another

Description

A component that wraps markup – tooltip, popover, popconfirm – compiles that markup into its own Vue instance. Vue builds fresh DOM when it compiles, and Element's tooltip keeps only the first node it is given, so a component dropped in whole loses its mount point and its instance: the inner component disappears, its inputs never report, and nothing is logged.

Usage

.el_absorb(ui)

Arguments

Details

Rather than refusing that, the inner component is taken apart and folded into the outer one, so the two become a single Vue instance holding both sets of markup, data and methods. Everything then works as it would standalone – including Shiny.setInputValue() calls, which name their ids outright.

The wrapper's own fields are prefixed, so nothing it declares can collide with the absorbed component's.

Value

A list with markup, the Vue options to merge (data, methods, watch, mounted, computed), and dependencies. Plain markup comes back as markup with everything else empty.

Merge what several absorbed components contribute

Description

Merge what several absorbed components contribute

Usage

.el_absorb_merge(...)

Arguments

Value

One set of Vue options, the dependencies to attach, and each part's markup as it now stands – renaming rewrites it, so the caller must render markups rather than what it passed in.

Take an argument given under either of its two names

Description

The choice components take Shiny's names, choices and selected, and Element's, options and value. Given both, the two must agree: letting one silently win, as colour <- color %||% colour does, hides a call that says two different things.

Usage

.el_alias(main, alias, main_name, alias_name)

Arguments

Value

Whichever was given; main when neither was.

Append children to a tag

Description

Append children to a tag

Usage

.el_append_children(tag, children)

Arguments

Value

The tag, with the children appended.

Props Element Plus takes only as arrays

Description

From its API tables: those typed Array with no string, number or boolean alternative. .el_props() keeps a length-one vector given for one of them an array.

Usage

.el_array_props

An id for a component given none

Description

Drawn at random, and marked as such: render_vue() does not take a new one, each render, for another component, as it does an id the author gave.

Usage

.el_auto_id(prefix)

Arguments

Value

The id, with attribute generated.

Normalise autocomplete suggestions

Description

Element reads each suggestion's value field, so a character vector is turned into one object per entry.

Usage

.el_autocomplete_suggestions(suggestions)

Arguments

Value

A list of objects, each with at least a value.

A calendar's events, as rows for the browser

Description

A calendar's events, as rows for the browser

Usage

.el_calendar_events(events, arg = NULL)

Arguments

Value

Rows, each with an id (the row's number when none is given), days as "YYYY-MM-DD" and times as "YYYY-MM-DD HH:MM".

Convert snake_case argument names to the camelCase Vue expects

Description

Convert snake_case argument names to the camelCase Vue expects

Usage

.el_camel(x)

Arguments

Value

The names in camelCase.

Turn a snake_case name into camelCase

Description

Arguments are snake_case throughout this package, while Vue reads its props in camelCase. Where a user writes the name themselves – a key in a column definition, say – both spellings have to work, or the snake_case one sits in the object doing nothing.

Usage

.el_camel_case(x)

Arguments

Value

The same name in camelCase.

Each level of a cascader's path as an input of its own

Description

A watcher of the value, run at once: it sets each level's input on load – once Shiny is connected – and whenever the value changes, whoever changes it. A Vue event would miss the value given at first and the one update_el_cascader() sets, which Element emits nothing for.

Usage

.el_cascader_levels(level_inputs, props)

Arguments

Value

A watch list for el_widget(), or NULL.

Refuse a value Element does not accept

Description

Called first thing by every component with an enumerated argument: a typo – type = "primry" – is an error naming the values that work, rather than a component Element quietly draws in its default style. Exact matching, unlike match.arg(): "prim" is not "primary" to Element either.

Usage

.el_check_choices(fn, env)

Arguments

Value

NULL, invisibly; or an error.

Check that items are a list of lists

Description

Components built from items – tabs, panels, menu entries – read each item's fields with $, which on a string or a vector fails with R's own "$ operator is invalid for atomic vectors". Saying what was expected is more use.

Usage

.el_check_items(x, arg, fields)

Arguments

Value

x, invisibly.

Check a server function was given a session

Description

Every server function takes the session first, defaulting to the current one, as Shiny's update*Input() do – so update_el_input("name", ...) passes the id as the session. Shiny stops that with a message naming the function; so does this, rather than failing on $ inside.

Usage

.el_check_session(session, fn = NULL)

Arguments

Value

session, invisibly.

The values Element accepts for its enumerated props

Description

Generated by tools/ep-choices.py from Element Plus 2.14.7's API tables: every argument that is an enumerated prop upstream, with no free-form alternative (an effect that also takes any string is not checked). A prop that also takes a number – an avatar's size – is checked only when given a string.

Usage

.el_choices

Element Plus's close icon, as its components draw it

Description

Icons are SVG components in Element Plus. A panel drawn as markup – a dialog, a drawer – draws the same SVG itself.

Usage

.el_close_icon(class)

Arguments

Value

An ⁠<i>⁠ tag holding the SVG.

Add gutter padding to a column

Description

Element Plus's Col reads gutter off its parent Row and emits the padding inline, so the same has to happen here rather than through a CSS class.

Usage

.el_col_gutter(child, half)

Arguments

Value

The child with padding merged into its style.

A component's specification

Description

A component's specification

Usage

.el_component(fn, args, class)

Arguments

Value

An object of class class and el_component.

Element's global config

Description

Element reads Vue.prototype.$ELEMENT for the size a component takes when it is given none, and for the z-index its popups start from. Element sets it when it installs itself; this runs after and overrides it.

Usage

.el_config_dependency(size = NULL, z_index = NULL)

Arguments

Value

A list holding one htmlDependency, or NULL when there is nothing to set.

Build one of the Element Plus container parts

Description

Build one of the Element Plus container parts

Usage

.el_container_part(
  class,
  children,
  size = NULL,
  size_prop = NULL,
  style = NULL,
  extra_class = NULL
)

Arguments

Value

A Shiny UI element.

Corrections to Element's own stylesheet

Description

Carried in the dependency's head, so they apply whether Element is served from the package or from the CDN. None are needed for Element Plus 2.14.7; the hook stays for the next one.

Usage

.el_css_fixes()

Value

A ⁠<style>⁠ element, as text, or NULL.

A date format in day.js's tokens

Description

Element Plus formats dates with day.js (YYYY-MM-DD, x for a timestamp); Element UI used its own tokens (yyyy-MM-dd, timestamp). The year and day tokens are the ones that differ.

Usage

.el_dayjs_format(x)

Arguments

Value

x in day.js's tokens.

Normalise descriptions items

Description

A named list or vector is the quick form: names are the labels. Keys written in snake_case are turned to camelCase, as for table columns.

Usage

.el_descriptions_items(items)

Arguments

Value

A list of items, each with label and content.

The Element variables a theme sets

Description

From a bslib::bs_theme(): its primary, success, warning, danger and info, which follow Bootstrap's CSS variables, and whatever was given to el_theme()'s element. A plain named list is taken as Element variables directly.

Usage

.el_element_vars(theme)

Arguments

Value

A named character vector, names without the ⁠--el-⁠ prefix.

Forward Element Plus events to Shiny inputs

Description

The component's entry in el_events() – the events on by default, and those the user asked for with events – forwarded by the Vue layer (.vue_event_bindings()), with the user's own handlers, on.

Usage

.el_event_bindings(
  ns_id,
  fn,
  asked = NULL,
  on = NULL,
  shapes = list(),
  throttle = character(),
  bound = character()
)

Arguments

Value

A list with attrs (to merge into the tag) and methods (to merge into the Vue options).

Empty value for a field type

Description

Picked so the initial model round-trips as the right JSON type, and so resetFields() has something sensible to reset to.

Usage

.el_form_empty_value(type)

Arguments

Value

The type's empty value.

The fields of a form, with those of each el_form_item() in place

Description

The fields of a form, with those of each el_form_item() in place

Usage

.el_form_flatten(fields)

Arguments

Value

A flat list of the fields.

The class sizing a form item

Description

The class sizing a form item

Usage

.el_form_item_size_class(size_field)

Arguments

Value

A Vue class binding.

Add a label or error to an update

Description

The form item a labelled input is drawn in has no Vue field of its own: its label and message are markup around the component. They travel as the bridge's own keys, .label and .error, which el-events.js draws.

Usage

.el_form_item_update(msg, label = NULL, error = NULL)

Arguments

Value

The message.

Shape choices for a control's option tag

Description

el-option takes the display text as its label attribute, while el-radio and el-checkbox take the display text as their default slot. Normalising here keeps one template able to render all three.

Usage

.el_form_options(choices, option_tag)

Arguments

Value

A list of list(label=, value=, text=) items, label only for el-option.

The fields given report = TRUE, as inputs and the paths they report

Description

The fields given report = TRUE, as inputs and the paths they report

Usage

.el_form_reported(fields, ns_id)

Arguments

Value

A named character vector: ⁠model.<prop>⁠ named ⁠<id>_<prop>⁠.

Element Plus control tags by field type

Description

option is the child tag for the choice-based controls.

Usage

.el_form_tags

Watchers reporting the fields given report = TRUE

Description

Watchers reporting the fields given report = TRUE

Usage

.el_form_watch(fields, ns_id)

Arguments

Value

A named list of watchers, or NULL.

Does this child carry one of the given layout classes?

Description

Does this child carry one of the given layout classes?

Usage

.el_has_class(x, classes)

Arguments

Value

TRUE when x is a tag carrying one of classes.

A colour, as hex

Description

A colour, as hex

Usage

.el_hex(x)

Arguments

Value

"#rrggbb".

Inline style for a component's Vue mount point

Description

Vue mounts onto the ⁠<div id="<id>_container">⁠ each component renders, but it does not remove that div: it stays in the document as a block-level box. Every component therefore started on its own line, so two buttons or two tags could never sit side by side without wrapping them in a grid.

Usage

.el_host_style()

Details

display: contents makes the box itself generate no layout, leaving the component to take part in the surrounding flow with its own display – inline for a button, block for an alert. The style is inline rather than in a stylesheet so it cannot be switched off with el_page(theme_css = NULL).

Value

A CSS declaration string.

Markup as a string, for a v-html field

Description

A field read by v-html travels as JSON, where a tag would arrive as its serialised object and show as text. Tags and tag lists are rendered to their HTML first; a character value is taken as markup already.

Usage

.el_html_string(x, arg = "html")

Arguments

Value

A single string, or NULL.

An icon, as Element Plus names it

Description

Icons are components in Element Plus, given by name – "Search", "ArrowRight" – where Element UI took a class, "el-icon-search". A class in Element UI's form is turned into the name, so code written for either works; anything else is passed through.

Usage

.el_icon_name(x)

Arguments

Value

The Element Plus name, or x unchanged.

An icon name in Element Plus's PascalCase

Description

An icon name in Element Plus's PascalCase

Usage

.el_icon_pascal(name)

Arguments

Value

"Search", "ArrowRight".

An item, as a constructor returns it

Description

An item, as a constructor returns it

Usage

.el_item(kind, fields)

Arguments

Value

The list, of class kind and el_item.

One mounted hook running several in turn

Description

When every hook is only reporting – what .el_mounted_init() writes – the result says so, with every field each reports: el_widget() then binds the component's own value to Shiny, as it does for any other, and reports the folded components' under their ids.

Usage

.el_join_mounted(mounts)

Arguments

Value

One hook, or NULL.

jQuery, for the package's scripts

Description

Every handler and binding script is written against jQuery, which a Shiny page always has. A page without Shiny – R Markdown, Quarto, the package's own website – may not, and the scripts stopped at their first line. The dependency is jquerylib's, under the name Shiny's own uses, so a Shiny page still loads one copy, the newer.

Usage

.el_jquery_dependency()

Value

An htmlDependency object.

Where the JavaScript is in a list

Description

The paths, dot-separated, of every JS() value, for the page to evaluate. A dot in a name is escaped.

Usage

.el_js_paths(x)

Arguments

Value

A character vector of paths.

Turn a camelCase name into kebab-case

Description

Turn a camelCase name into kebab-case

Usage

.el_kebab_case(x)

Arguments

Value

The same name in kebab-case.

Element Plus's theme variables, by name

Description

Element Plus's theme variables, by name

Usage

.el_known_vars()

Value

Names, without the ⁠--el-⁠ prefix.

Tie a component's Element tag to its label

Description

A component whose Element tag hands an id on to a native input – an input, a select, a picker – is labelled with for; any other, with aria-labelledby on its root.

Usage

.el_label_attrs(attrs, id, label, native = FALSE)

Arguments

Value

The attributes, with the tie added.

Lay a component out under (or beside) a label

Description

Element's own form-item markup – .el-form-item__label and .el-form-item__content – so the label looks as it does in an el_form(), laid out with flexbox rather than Element's floats, which assume an enclosing form. It is the template's root, inside the host: hiding or removing the component by its id takes the label with it.

Usage

.el_labelled(
  container_id,
  id,
  label,
  position,
  markup,
  width = NULL,
  suffix = NULL,
  required = FALSE,
  error = NULL,
  show_message = TRUE,
  inline_message = FALSE,
  size_field = FALSE
)

Arguments

Value

A tag.

The loader a lazy tree or tree table uses when none is given

Description

The loader a lazy tree or tree table uses when none is given

Usage

.el_lazy_load_method(ns_id, kind = c("tree", "table"))

Arguments

Value

A JS function, a method of the component.

A component's props, with the server answering lazyLoad

Description

el-cascader and el-cascader-panel take their loader inside props, so a computed property adds one that asks the server – unless the user gave their own, or the cascader is not lazy.

Usage

.el_lazy_props(ns_id)

Arguments

Value

A JS function, the computed property.

Element's element-loading-* attributes

Description

Element's element-loading-* attributes

Usage

.el_loading_attrs(options)

Arguments

Value

A named list of attributes.

Where a locale's file is

Description

The locales used most are files in dist/locale; the rest are packed in dist/locale/more.tar.gz, which keeps the installed package small – 56 files of 4KB each take far more room on disk than their bytes – and one is taken out into the session's temporary directory the first time it is asked for.

Usage

.el_locale_dir(code)

Arguments

Value

The directory holding ⁠<code>.min.js⁠, or NULL for a locale Element Plus does not ship.

A locale's file alone, English's included

Description

el_locale_dependency() also makes the locale the page's; a config provider needs only the object the file defines, ElementPlusLocaleZhCn.

Usage

.el_locale_file(code)

Arguments

Value

An htmlDependency.

The locale files packed in more.tar.gz

Description

Listed once a session.

Usage

.el_locales_packed()

Value

File names, "af.min.js".

Bind the per-item props a menu item or submenu was given

Description

Bind the per-item props a menu item or submenu was given

Usage

.el_menu_item_props(item, fields)

Arguments

Value

A list of ⁠:kebab-case⁠ bindings, one per field present.

Build the nested tags inside an el-menu

Description

Menus nest arbitrarily deep, so the tree is generated in R rather than with ⁠v-for⁠: a template can only repeat one level, and a menu's shape is fixed at render time anyway.

Usage

.el_menu_nodes(items)

Arguments

Value

A list of tags.

A colour mixed with another, as Sass's mix()

Description

A colour mixed with another, as Sass's mix()

Usage

.el_mix(hex, with, weight)

Arguments

Value

"#rrggbb".

Build a Vue mounted hook that reports initial values to Shiny

Description

Element Plus components only emit ⁠@change⁠ on user interaction, and Vue watch handlers do not fire on mount. Without this hook the corresponding ⁠input$<id>⁠ stays NULL until the user first touches the component, unlike standard Shiny inputs which report their value immediately.

Usage

.el_mounted_init(bindings)

Arguments

Details

The send is deferred until shiny:connected when the socket is not up yet: a component on a static page, or one mounted before Shiny connects, would otherwise call Shiny.setInputValue() into nothing.

Value

A JS() function, the Vue mounted option.

Element components that render no element of their own

Description

A config provider renders its slot alone: an attribute on it reaches nothing, and Vue warns.

Usage

.el_no_root

Normalise choices into option configs

Description

Accepts a named vector (c(Label = value)), an unnamed vector, or a list already shaped as list(value = , label = ) items, and returns the list form that el-option / el-radio / el-checkbox iterate over.

Usage

.el_normalize_choices(choices)

Arguments

Details

The named branch deliberately does not require a character vector. It used to, so c(Beijing = 1, Shanghai = 2) fell through to the unnamed branch: the labels were lost (rendered as "1" and "2") and the surviving names turned the serialised JSON into an object rather than the array ⁠v-for⁠ expects.

Value

An unnamed list of list(value = , label = ) items.

Normalise one or several validation rules into a list of rules

Description

Normalise one or several validation rules into a list of rules

Usage

.el_normalize_rules(rules)

Arguments

Value

An unnamed list of rules, or NULL.

Vue binding for a prop that may be unset

Description

Element Plus's props fall back to their own defaults when passed undefined, but treat null as a value: an el-select bound to a null placeholder renders an empty one instead of its "Select". R has no way to send undefined through JSON, so an unsupplied field arrives as null and the expression has to map it back.

Usage

.el_optional_bind(field)

Arguments

Details

A conditional is used rather than ⁠??⁠ because a template expression is evaluated at runtime, where a polyfill cannot help with syntax.

Value

A template expression yielding the field, or undefined when unset.

Placeholder for an unset optional prop

Description

A field left out of the Vue instance's data is not reactive, so ⁠update_el_*()⁠ can never set it later. Unset optional props are therefore declared as NA, which serialises to null, and read back through .el_optional_bind(), which turns that null into undefined so Element applies its own default.

Usage

.el_or_na(x)

Arguments

Value

x, or NA when x is NULL.

An overlay's content, kept for re-creation when it is destroyed on close

Description

With destroy_on_close, the content lives in an inert ⁠<template>⁠ and is instantiated each time the overlay opens – so its inputs start from their initial values – then unbound and removed when it closes. Shown from the start, a live copy is rendered as well.

Usage

.el_overlay_content(content, destroy, visible)

Arguments

Value

Markup.

An overlay's settings for its update message

Description

The dialog's and drawer's behaviours, Element's props all reactive there: given ones as their camelCase fields, logical ones as TRUE/FALSE.

Usage

.el_overlay_flags(values)

Arguments

Value

A list of fields.

Element Plus, and the Vue its script needs before it

Description

For the containers – tabs, collapse, dialog, drawer, row, container – which are Element's markup and classes, not Vue apps: they need its stylesheet, not the bridge.

Usage

.el_plus_dependencies()

Value

A list of htmlDependency objects.

Rename an absorbed component's Vue fields

Description

Two components folded into the same instance share one set of field names, and most of them declare a label, a type or a disabled. Prefixing one side's fields keeps them apart – but the markup and the methods refer to those fields by name, so they have to be rewritten to match.

Usage

.el_prefix_absorbed(absorbed, prefix)

Arguments

Details

Only whole identifiers are renamed, and never inside a string literal: ⁠:class="data.isSelected ? 'is-selected' : ''"⁠ names a CSS class, not a field.

Value

The same list, with every field renamed.

Props' values as the component's fields hold them

Description

NULL is NA, the placeholder that falls back to Element's default; a prop Element Plus takes only as an array stays one when R gives a single value (jsonlite would write "1" for c(1), and a tree-v2 handed a string for its default-expanded-keys fails to mount); a data.frame is rows.

Usage

.el_prop_values(values)

Arguments

Value

The list, values prepared.

Optional props, bound and given their data

Description

Element Plus's props that keep its own default unless given: each is bound as ⁠:kebab-name⁠ to a field of the same camelCase name, through .el_optional_bind(), and the field holds the value or NA (read back as undefined, Element's default).

Usage

.el_props(values, prefix = NULL, rename = NULL)

Arguments

Value

A list of attrs (for the tag) and data (for the Vue data).

Rename identifiers all at once

Description

One pass over every name: renamed one after another, a field renamed to el3_label would be renamed again by a rule for el3_label – two buttons in one popover, absorbed twice over, then showed the second one's label on both.

Usage

.el_rename_all(x, rename, before)

Arguments

Value

x, renamed.

Rename the fields of record options, as Element Plus's props does

Description

Rename the fields of record options, as Element Plus's props does

Usage

.el_rename_option_fields(choices, props)

Arguments

Value

The choices, with the fields .el_select_choices() reads.

Rename a component's ref in its own functions

Description

Rename a component's ref in its own functions

Usage

.el_rename_ref(options, old, new)

Arguments

Value

The options, ⁠$refs.<old>⁠ read as ⁠$refs.<new>⁠ throughout.

A render function for a component drawn in an output of its own id

Description

What render_el_table() and render_el_calendar() share: the component drawn under the output's id, its data kept on the server for its inputs and el_table_data(), only what changed sent after the first render, a promise waited for, and shiny::bindCache() keeping the output as it stands while each page still gets only what changed for it.

Usage

.el_render_component(expr, env, class, what, data_arg, output_fn, label)

Arguments

Value

A render function, of class el_render_output.

Components inside UI, drawn: what code that reads tags expects

Description

Components inside UI, drawn: what code that reads tags expects

Usage

.el_resolve(x)

Arguments

Value

x, every component in it replaced by its tags.

A value as a bookmarked session left it

Description

shiny::restoreInput(), keeping the shape the component expects: a field that is an array stays one, so a restored one-item selection is not unboxed to a string, and an empty selection comes back as an empty array rather than NULL.

Usage

.el_restore(id, default)

Arguments

Value

The restored value, or default.

Rewrite the field names a template expression refers to

Description

Rewrite the field names a template expression refers to

Usage

.el_rewrite_expr(expr, rename)

Arguments

Value

The expression, rewritten.

Rewrite field names in markup written as a string

Description

Rewrite field names in markup written as a string

Usage

.el_rewrite_html(html, rename)

Arguments

Value

The markup, its binding values and interpolations rewritten.

Rewrite field names inside a JS function body

Description

Rewrite field names inside a JS function body

Usage

.el_rewrite_js(js, rename)

Arguments

Value

The function, rewritten.

Rewrite field names throughout a tag tree

Description

Rewrite field names throughout a tag tree

Usage

.el_rewrite_markup(ui, rename)

Arguments

Value

The markup, rewritten.

Split a select's choices into loose options and option groups

Description

Groups are written the way shiny::selectInput() takes them – a named list whose elements are vectors, list(East = c("NY", "NJ")) – or as list(label =, disabled =, options =) when a group needs its own disabled. Anything else is an ungrouped choice.

Usage

.el_select_choices(choices)

Arguments

Value

A list of options and groups.

Send an update of a component's props

Description

For the components whose props are all bound through .el_props(): the fields are named as the component's own, prefix and renames included, so an update reaches what the UI declared.

Usage

.el_send_props_update(session, id, fn, values, prefix = NULL, rename = NULL)

Arguments

Value

NULL, invisibly.

Send an update to a component

Description

One message type for every component, handled by shiny-vue.js: the fields a component declares are assigned, one it does not is refused with a warning, and a component with more to do – move a carousel, validate a form – does it in its shinyVueReceive method. .action names such an operation.

Usage

.el_send_update(session, msg, immediate = FALSE)

Arguments

Value

NULL, invisibly.

A service's options, as Element Plus names them

Description

The arguments a call to a service – message, notification, message box, loading – was given, in camelCase, without those left NULL. Icons are turned into Element Plus's names; JS() functions travel as source and are listed in .functions, for the browser to turn back into functions.

Usage

.el_service_options(args, skip)

Arguments

Value

A named list.

Set a width on a tag, replacing any width it already declares

Description

htmltools joins repeated attributes with a space, so appending a second style turns ⁠width: 100%⁠ and ⁠width: 200px⁠ into style="width: 100% width: 200px" – neither of which a browser reads. The existing declarations are parsed instead, the width among them dropped, and the new one appended.

Usage

.el_set_width(tag, width)

Arguments

Value

The tag, with the width set.

A slot's content, in Vue 3's syntax

Description

⁠<template v-slot:name>⁠ – Vue 3 has no slot="name" attribute, and an element carrying one is rendered into the default slot instead.

Usage

.el_slot(name, ..., scope = NULL)

Arguments

Value

A template tag.

Turn named slot contents into markup, absorbing any components

Description

Turn named slot contents into markup, absorbing any components

Usage

.el_slot_markup(slots, taken = character(0))

Arguments

Value

A list of markup plus the Vue options its components contribute.

Turn a camelCase method name into the snake_case input it reports to

Description

Turn a camelCase method name into the snake_case input it reports to

Usage

.el_snake_case(x)

Arguments

Value

The same name in snake_case.

Merge inline style fragments

Description

htmltools::tagAppendAttributes() joins repeated style attributes with a space, producing invalid CSS ("color:red padding-left:10px"), so style fragments are assembled here instead.

Usage

.el_style(...)

Arguments

Value

A single ⁠;⁠-separated style string, or NULL if nothing was given.

One tab's header item

Description

One tab's header item

Usage

.el_tab_item(ns_id, t, active, closable, pos_class)

Arguments

Value

A tag.

One tab's pane

Description

A lazy tab that is not showing keeps its content in a ⁠<template>⁠, which the browser leaves inert: nothing in it renders, binds or runs until the binding instantiates it the first time the tab is selected.

Usage

.el_tab_pane(ns_id, t, active)

Arguments

Value

A tag.

Accept the pre-0.1.0 el_table(data, columns, id) argument order

Description

el_table() used to take data first, which put it out of step with every other component. Positional calls written against the old order land a data.frame in id, so shift them back one slot and warn, rather than letting the data be used as an element id.

Usage

.el_table_args(id, data, columns)

Arguments

Value

A list with elements id, data and columns.

Take the cell templates out of a table's columns

Description

A column's cell is markup, rendered once per row with scope – row, column, ⁠$index⁠ – in reach. It cannot travel in the column object, which is JSON in the Vue data, so it is lifted out into the template and the column keeps a cellKey naming its branch there. slot decides whether the column gets a default slot at all: a column without one must have none, or Element's own rendering – index numbers, formatters, the tree's expand arrow – would be replaced by an empty slot.

Usage

.el_table_cells(columns)

Arguments

Details

The key is built from the column's prop or label, so that update_el_table() given the same columns finds the same template.

Value

A list: columns, without cell, cells, a named list of markup keyed by cellKey, and depths, the nesting level of each.

The cell template of an editable column

Description

The value as text; double-clicked, Element's editor for it, which Enter or leaving it commits, Escape abandons and Tab commits, moving to the next editable cell. The table's startEdit(), commitEdit() and cancelEdit() do the rest.

Usage

.el_table_editor(prop, editable, editor = NULL)

Arguments

Value

Markup, the column's cell.

What each table event reports

Description

Element hands most table events the row object and its internal column object. Sent as they are they reach R flattened into one character vector, so each event is shaped into a named list instead: the 1-based row_index to index the original data with, the row itself, and the column's prop rather than the column object.

Usage

.el_table_event_shapes()

Value

A named list of JavaScript functions, one per event.

Derive el-table-column configs from data

Description

Derive el-table-column configs from data

Usage

.el_table_infer_columns(data)

Arguments

Value

A list of list(prop=, label=) configs.

Normalise the data/columns pair for el_table()

Description

The columns a user wrote and the columns inferred from the data are kept apart – columns and autoColumns in the Vue data, the template showing the first when there are any. A new data set then brings new inferred columns without touching written ones: update_el_table() given only data used to re-infer and send columns, which threw away every label, formatter and cell template the table was created with.

Usage

.el_table_prep(data = list(), columns = list())

Arguments

Value

A list: rows, columns (as written, possibly empty), auto (inferred from data) and cells (the templates lifted out of columns).

Keep a data.frame's row names as a column, when they mean something

Description

mtcars keeps its car names in the row names, and a table that drops them drops the one column saying what each row is. Automatic row names – 1 to n – say nothing, so they are left out unless asked for.

Usage

.el_table_rownames(data, rownames = NULL)

Arguments

Value

The data, with a rowname column first when kept.

Coerce table data to a list of rows

Description

Element Plus's el-table binds ⁠:data⁠ to an array of row objects. An R data.frame serialised as it stands comes out column-wise, ⁠{col: [...]}⁠, which the component silently renders as an empty table.

Usage

.el_table_rows(data)

Arguments

Details

Column names are sanitised because el-table-column's prop is resolved as a dotted path (getPropByPath), so a column literally named Sepal.Length would be looked up as row$Sepal$Length and come back empty.

Value

A list of named lists, one per row.

Align user-supplied column configs with sanitised data keys

Description

Align user-supplied column configs with sanitised data keys

Usage

.el_table_sanitize_columns(columns)

Arguments

Value

The same list with each prop sanitised.

Logical attributes of an Element tag, as Vue reads booleans

Description

Logical attributes of an Element tag, as Vue reads booleans

Usage

.el_tag_args(args)

Arguments

Value

The arguments, TRUE as a bare attribute and FALSE bound.

Tags in Vue data, as the HTML they stand for

Description

A field of a component's data travels as JSON, where a tag – an item's content = tags$b("x"), a column's header – would arrive as its serialised object, and show as that, or as ⁠[object Object]⁠. Every tag and tag list found in the data is rendered to its HTML string instead, which is what a v-html field reads; a field shown as text shows the markup rather than an object.

Usage

.el_tags_as_html(x)

Arguments

Value

x, with tags replaced by strings.

Element's variables for a theme, decided when the page is drawn

Description

When theme is the page's own Bootstrap theme – el_page() gives it to the page, a bslib page function was given the same one – Element's colours follow Bootstrap's CSS variables, so a theme changed while the app runs reaches them. Any other theme, or one drawn outside a page that has it, is written out as it stands.

Usage

.el_theme_tag(theme)

Arguments

Value

A tag function giving the dependency, or NULL.

Element Plus's variables, set for a theme

Description

Element Plus's variables, set for a theme

Usage

.el_themed_dependency(vars, live = FALSE)

Arguments

Value

An htmlDependency holding the ⁠<style>⁠, or NULL when nothing changes.

Build either time picker

Description

Build either time picker

Usage

.el_time_widget(
  tag,
  ns_id,
  init,
  fields,
  fn,
  events,
  on,
  width,
  slots,
  form_item
)

Arguments

Value

A Shiny UI element.

Keep only the fields an entry actually sets

Description

A ⁠v-for⁠ binding reading a missing property gets undefined, which is what makes Element fall back to a prop's default. Filling the gaps with NA would send JSON null instead, and null is a value: an entry without placement then matched neither ⁠placement === 'top'⁠ nor 'bottom', so its timestamp rendered nowhere at all.

Usage

.el_timeline_items(items)

Arguments

Value

The entries with unknown and empty fields dropped.

Normalise transfer items

Description

Element reads key, label and disabled off each item, so a data.frame is turned into one object per row.

Usage

.el_transfer_data(data)

Arguments

Value

A list of items.

What each tree event reports

Description

Element hands tree events the node's data, its internal TreeNode – which points at its parent and children – and sometimes the component. Each is shaped into a named list of the node's data, its key and its level.

Usage

.el_tree_event_shapes()

Value

A named list of JavaScript functions, one per event.

A tree's field map, as Element Plus's props

Description

Element replaces its field map whole rather than merging it, so the fields not given are filled in with Element's own – left out, disabled would no longer disable a node.

Usage

.el_tree_props(props)

Arguments

Value

The full map.

The id a UI function gives its component

Description

A UI function does not namespace its id, any more than shiny::textInput() does: inside a module the caller writes ns("name"). Namespacing from the default reactive domain, as every component once did, namespaced twice whenever UI was built inside a module's server – renderUI() – turning ns("name") into "mod-mod-name", an input that never reported and said nothing about it.

Usage

.el_ui_id(id, session = NULL)

Arguments

Details

A session given explicitly is still honoured, with a warning, for code written against the old behaviour.

Value

The id the component uses.

Props an update function was given, as the component's fields

Description

⁠update_el_<name>()⁠ takes ⁠el_<name>()⁠'s arguments under the same names. Each sets the component's field of that name in camelCase (table_layout -> tableLayout) – the field the prop is bound to, NA standing for Element's default – or the field rename names. An argument the UI function does not have, or one that cannot change once drawn (skip), is an error; enumerated ones are checked as the UI function checks them.

Usage

.el_update_props(fn, dots, skip = character(), rename = character())

Arguments

Value

A named list: field -> value.

Let go of an upload job a failed or aborted file left behind

Description

Shiny keeps an upload job until uploadEnd finishes it, and finishing one with files still to come is an error. A batch with a failed or aborted file is sent again as a new job, so the old one would wait in the session until it ended, with whatever part of a file reached its directory. The browser names it here and it is removed: dropped from the session's upload jobs and its directory deleted. Shiny offers no public way to do this, so the session's upload context is reached into; should that change, the job is left as before, to go when the session does, and a warning says so once per session. test-el_upload.R checks that the installed Shiny still has every internal used here.

Usage

.el_upload_abandon(job_id, session)

Arguments

Value

Whether the job was found and removed, invisibly.

JavaScript that pushes a batch of files through Shiny's upload channel

Description

Element calls http-request once per file, but Shiny's protocol is per-batch: uploadInit opens a job for a set of files, each is POSTed to the job's URL, and uploadEnd sets the input to that job's files. Running the protocol per file would make each upload overwrite the last.

Usage

.el_upload_js(ns_id)

Arguments

Details

Element's uploadFiles() starts every file in one synchronous loop, so the calls are collected and flushed from a microtask, by which point the whole batch is present. Then, as Shiny's own fileInput() does:

• Files are POSTed one after another. Shiny's job takes each POST as the next file in its list, so two in flight at once could land under each other's names.

• A file is Element's "success" only once uploadEnd has accepted the batch: until then nothing has reached ⁠input$<id>⁠.

• A job cannot finish with a file missing – Shiny stops it as "stopped prematurely". So when a file fails, or is aborted with Element's abort(), that file is marked failed (or left, if aborted) and the rest of the batch is sent again as a fresh job. The interrupted job is named to the server, which lets it go (.el_upload_abandon()).

Each call returns an object with abort(), which Element keeps per file: it stops that file's request if it is in flight and drops it from the batch otherwise.

Value

A JS() object for the http-request prop.

The scripts every Vue component needs

Description

jQuery, Vue, the generic bridge (shiny-vue.js: mounting, the Shiny input binding, serialising values, forwarding events), Element Plus and Element's side of the bridge (el-events.js), in load order. Every component carries Element Plus, as Shiny's inputs carry selectize and htmlwidgets their libraries, so it works on any page; htmltools keeps one copy, the first, so a page that loads Element from the CDN (use_element(offline = FALSE) before its components) keeps that one. What belongs to the page – its theme, locale, global config, the feedback handlers – stays with use_element() and el_page().

Usage

.el_vue_dependencies()

Value

A list of htmlDependency objects.

Vue, as bundled with the package

Description

Vue 3, the global build with the template compiler, from inst/vue3: components are compiled in the browser from their x-template. The development build keeps Vue's warnings (⁠[Vue warn]⁠), which the production build strips. It is versioned one step above the production build, so on a page holding both – el_page(dev = TRUE) beside components that bring the default – htmltools keeps the development one.

Usage

.el_vue_dependency(dev = .vue_dev())

Arguments

Value

An htmlDependency object.

An icon inside a component's template

Description

Where Vue compiles the markup – a menu, a dropdown, a slot – an icon is Element Plus's own ⁠<el-icon>⁠ holding the icon component. A tag is passed through.

Usage

.el_vue_icon(x)

Arguments

Value

Markup.

Serialise a component's Vue options for the page

Description

JSON with NA and NULL as null and single values unboxed – with the paths of every JS() listed in evals, so the bridge can turn their source back into functions. ⁠</⁠ is escaped, or a header_html holding ⁠</b>⁠ would end the script element early.

Usage

.el_vue_json(spec)

Arguments

Value

The JSON, as a single string.

A component holding other UI, as one Vue instance

Description

For Element Plus's containers – affix, space, scrollbar, watermark and the like – whose content is arbitrary UI: each child that is a component of this package is folded into the container's instance (.el_absorb()), the rest is markup inside its template. The container's own fields are taken first, so a child's field of the same name is the one renamed.

Usage

.el_wrap_widget(
  tag,
  ns_id,
  children,
  props = NULL,
  events = NULL,
  attrs = list(),
  width = NULL,
  slots = NULL,
  data = list(),
  wrap = NULL,
  on = NULL
)

Arguments

Value

A Shiny UI element.

snake_case to camelCase

Description

snake_case to camelCase

Usage

.vue_camel(x)

Arguments

Value

The name in camelCase.

Stop unless session is a Shiny session

Description

Stop unless session is a Shiny session

Usage

.vue_check_session(session, fn = NULL)

Arguments

Value

session, invisibly.

The scripts the Vue layer needs

Description

jQuery, Vue and the bridge (shiny-vue.js).

Usage

.vue_dependencies()

Value

A list of htmlDependency objects.

Whether to load Vue's development build

Description

options(shiny.vue.dev = TRUE), or shiny.element.dev as before.

Usage

.vue_dev()

Value

TRUE or FALSE.

The .edit of an update: one list field changed in place

Description

The .edit of an update: one list field changed in place

Usage

.vue_edit(insert, replace, delete, at, key)

Arguments

Value

NULL, or list(op, field, rows, at, key).

Forward a component's events to Shiny inputs

Description

Events carry different arguments each, some of them DOM nodes or native events that cannot be serialised. Rather than write a handler per event, each one is bound to a generated method that hands its arguments to shinyVue.emit() (see inst/js/shiny-vue.js), which drops what cannot travel and sets ⁠input$<id>_<event>⁠.

Usage

.vue_event_bindings(
  ns_id,
  events,
  on = NULL,
  shapes = list(),
  throttle = character(),
  bound = character()
)

Arguments

Value

A list with attrs (to merge into the tag) and methods (to merge into the Vue options).

The events forwarded: those on by default and those asked for

Description

The events forwarded: those on by default and those asked for

Usage

.vue_events_check(
  asked,
  known,
  default = character(),
  what = "the component",
  see = NULL
)

Arguments

Value

The events, kebab-case.

A host: the element a component mounts on, carrying its template and spec

Description

A host: the element a component mounts on, carrying its template and spec

Usage

.vue_host(id, template, spec, dependencies = list(), islands = NULL)

Arguments

Value

A tag with its dependencies.

Shiny UI in a template, taken out of it: islands

Description

Vue compiles a template and owns the elements it draws: it drops ⁠<script>⁠s, and re-creates what ⁠v-if⁠ and ⁠v-for⁠ show, so a Shiny input in a template loses its binding when Vue draws it again, an htmlwidget its data, a component of its own (a host) its template. Such UI is taken out: rendered beside the template, as Shiny renders it, in a hidden holder, and the template gets ⁠<shiny-island name="k">⁠ in its place, which moves the UI in while Vue shows it and back out – suspended, its state kept – when Vue removes it. Scripts and styles found loose in the template go to the holder too.

Usage

.vue_islands(template, components = TRUE)

Arguments

Details

An island is a tag with a Shiny input's, output's or htmlwidget's class, a component of its own (data-shiny-vue), a conditionalPanel() (⁠data-display-if⁠), or a tag marked data-shiny-island.

Value

A list: template, with placeholders; holder, a tag or NULL.

Handlers of one event, run in turn

Description

Handlers of one event, run in turn

Usage

.vue_join_handlers(key, handlers)

Arguments

Value

One arrow function calling each, in order.

jQuery, which the bridge's scripts are written against

Description

A Shiny page always has it; a page without Shiny – R Markdown, a saved file – may not. jquerylib's, under the name Shiny's own uses, so a Shiny page still loads one copy.

Usage

.vue_jquery_dependency()

Value

An htmlDependency object.

Paths of the JS() values in a nested list, for the browser to revive

Description

Paths of the JS() values in a nested list, for the browser to revive

Usage

.vue_js_paths(x)

Arguments

Value

Dot-separated paths, dots inside names escaped.

A component's spec as the JSON its host carries

Description

A component's spec as the JSON its host carries

Usage

.vue_json(spec)

Arguments

Value

The JSON, as a single string, safe inside a ⁠<script>⁠.

One event's handlers given more than once on a tag, as one

Description

A component's own handler of an event – ⁠@change="handleChange"⁠ – and the one forwarding it or the user's on can land on its tag together: htmltools would join them into one attribute, "handleChange svOn1", which Vue cannot compile, and the component would not mount.

Usage

.vue_merge_handlers(attribs)

Arguments

Value

The attributes, each ⁠@<event>⁠ once.

A mounted hook reporting fields as Shiny inputs

Description

Sends each field once the socket is connected (a send before is dropped), and again after every update (⁠_svReport⁠), as Shiny's own update*Input() reports the new value.

Usage

.vue_mounted_report(bindings)

Arguments

Value

A JS() function, with the bindings as its vue_report attribute.

Add on handlers to a tag, beside any it already listens with

Description

A tag carries one ⁠@<event>⁠: where the component already listens to that event – one it forwards, or handles itself – both run, its own first.

Usage

.vue_on_attach(tag, on)

Arguments

Value

The tag.

Handlers of the user's own, as on

Description

Each becomes a method the component's tag listens with: ⁠@<event>⁠. The handler is called with report first – report(name, value) sets ⁠input$<id>_<name>⁠ – then the event's own arguments, and this the Vue instance.

Usage

.vue_on_bindings(ns_id, on)

Arguments

Value

A list with attrs and methods.

Vue's option names from the R spelling

Description

A snake_case spelling of one of Vue's multi-word options becomes Vue's (before_unmount -> beforeUnmount); every other name is left exactly as written. Two spellings of one option with different values are an error.

Usage

.vue_option_aliases(opts)

Arguments

Value

The list, named as Vue names its options.

What an output sends: its markup, or the data that changed

Description

A render is made in two steps. .vue_output_whole() is the output as it stands, the same for every session – what bindCache() keeps; .vue_output_send() compares it with what this session's page last got and sends the markup or the changed fields. A cached render runs only the second step (cacheReadHook), so caching and sending only what changed go together.

Usage

.vue_output_value(session, name, tags)

Arguments

Value

list(html =, deps =), or list(patch = list(host =, fields =)) with each changed field as JSON text; carrying the whole as attribute vue_whole, for the cache.

A session's queue of messages for the components

Description

One per session, in its userData, which a module's session shares with the session it belongs to – so messages from both keep their order.

Usage

.vue_queue(session)

Arguments

Value

An environment, or NULL for a session that cannot hold one until the flush.

A value restored from a bookmark, an array kept an array

Description

A value restored from a bookmark, an array kept an array

Usage

.vue_restore(id, default)

Arguments

Value

The restored value, or default.

A data.frame as rows, as ⁠v-for⁠ walks it and table components take it

Description

Factors become strings; a dot in a name becomes an underscore, since a template expression cannot name a.b. A data.frame further in – a row's list of rows, a cell of a list column – is rows too, and a list column's cell is its value, not a list of one; NA is null.

Usage

.vue_rows(data)

Arguments

Details

The rows are written by jsonlite, as JSON kept verbatim (class json): its dataframe = "rows" is one vectorised pass, where a list of row lists took jsonlite seconds for a table-v2's ten thousand rows. A data.frame holding tags or JS() in a list column is turned into row lists instead, so they are rendered and revived as anywhere else.

Value

The rows: JSON of class json, or a list of row lists.

Send a message to the components, with the flush

Description

Shiny's own update*Input() queue their messages and send them with the flush, after the outputs it recalculated (sendInputMessage()), as DT's and leaflet's proxies do (deferUntilFlush). Updates and method calls do the same: queued per session and sent once the flush is done, so a component re-rendered and updated in one observer is updated after it is drawn. A flush is requested, for a call from outside one – a later() callback. flush_vue() sends what is queued at once; a session without onFlushed() (a test's mock) is sent to at once.

Usage

.vue_send(session, type, msg, immediate = FALSE)

Arguments

Value

NULL, invisibly.

Send what is queued, in order

Description

Send what is queued, in order

Usage

.vue_send_queued(session)

Arguments

Value

NULL, invisibly.

Send fields to a component: the shinyVueUpdate message

Description

Send fields to a component: the shinyVueUpdate message

Usage

.vue_send_update(session, msg, immediate = FALSE)

Arguments

Value

NULL, invisibly.

The .set of an update: values by path

Description

"items[3].done" is the field items, its third element (2 from 0 in the browser), its done.

Usage

.vue_set_paths(set)

Arguments

Value

A list of list(path, value).

Tags inside a list rendered to HTML strings

Description

Tags inside a list rendered to HTML strings

Usage

.vue_tags_as_html(x)

Arguments

Value

x, with every tag in it rendered.

The use of a component as the bridge reads it

Description

The use of a component as the bridge reads it

Usage

.vue_use(use)

Arguments

Value

A list of names and list(name =, options =).

Vue, as bundled with the package

Description

Vue 3, the global build with the template compiler, from inst/vue3: components are compiled in the browser from their x-template. The development build keeps Vue's warnings (⁠[Vue warn]⁠), which the production build strips. It is versioned one step above the production build, so on a page holding both, htmltools keeps the development one.

Usage

.vue_vue_dependency(dev = .vue_dev())

Arguments

Details

The development build is in the package's sources but not in what is built from them for CRAN, to keep the package small: installed from CRAN, it is loaded from the unpkg CDN, the same build unminified.

Value

An htmlDependency object.

Mark a string as JavaScript

Description

A prop that takes a function – a table's formatter, a tree's filter_node_method, a date picker's shortcuts – takes JavaScript source marked with JS(), which the page evaluates rather than passing on as text. It is the same mark htmlwidgets::JS() makes, so either works, and so does DT::JS().

Usage

JS(...)

Arguments

Value

The source, classed "JS_EVAL".

Examples

JS("function(row, column, value) { return value.toFixed(2); }")

Call a method of an Element component

Description

update_el_table() and the other ⁠update_el_*()⁠ functions assign into the Vue instance's data, which reaches a component's props. Element also documents methods – clearSelection(), setCheckedKeys(), validate() – which are functions on the component and cannot be reached that way. call_el() invokes one: it is call_vue() with Element's references to table rows, upload files and tree nodes.

Usage

call_el(
  session = shiny::getDefaultReactiveDomain(),
  id,
  method,
  args = list(),
  result = TRUE,
  component = NULL
)

Arguments

Details

A method that returns something reports it as ⁠input$<id>_<method>⁠, with the method name in snake_case, matching how events are reported: getCheckedKeys arrives as ⁠input$<id>_get_checked_keys⁠. The input is set with event priority, so asking twice and getting the same answer still fires an observeEvent() the second time.

A method that returns nothing reports TRUE, so an observeEvent() can still tell that it ran. Pass result = FALSE to send nothing back.

Each component's methods are listed in its own help page, under "Element methods".

Value

Called for its side effect; returns NULL invisibly.

Examples

if (interactive()) {
  library(shiny)
  library(shiny.element)

  ui <- el_page(
    el_tree(
      "tree",
      show_checkbox = TRUE,
      node_key = "id",
      checked = "apple",
      default_expand_all = TRUE,
      data = list(list(
        id = "fruit",
        label = "Fruit",
        children = list(
          list(id = "apple", label = "Apple"),
          list(id = "pear", label = "Pear")
        )
      ))
    ),
    el_button("clear", "Clear the ticks"),
    el_button("ask", "Which are ticked?"),
    verbatimTextOutput("answer")
  )

  server <- function(input, output, session) {
    # A command: setCheckedKeys() with an empty set
    observeEvent(input$clear, {
      call_el(session, "tree", "setCheckedKeys", list(list()))
    })

    # A method with a return value answers asynchronously
    observeEvent(input$ask, {
      call_el(session, "tree", "getCheckedKeys")
    })
    output$answer <- renderPrint(input$tree_get_checked_keys)
  }

  shinyApp(ui, server)
}

Call a method of a Vue component from the server

Description

update_vue() assigns data; a method is a function, reached with this. The method is looked up on the component the template renders – a library table's clearSelection(), a child component's own – or, with component, on the first component of that name under the id.

Usage

call_vue(
  session = shiny::getDefaultReactiveDomain(),
  id,
  method,
  args = list(),
  result = TRUE,
  component = NULL
)

Arguments

Details

A method that returns something reports it as ⁠input$<id>_<method>⁠, the method name in snake_case; one that returns nothing reports TRUE. The input has event priority, so the same answer twice still fires an observeEvent(). A promise reports what it resolves to.

Value

Called for its side effect; returns NULL invisibly.

See Also

update_vue().

Examples

if (interactive()) {
  # inside a server function
  observeEvent(input$reset, call_vue(id = "form", method = "resetFields"))
}

Convert a data.frame with custom value/label columns to Element-UI Cascader options list

Description

Convert a data.frame with custom value/label columns to Element-UI Cascader options list

Usage

df_to_cascader_options(df, value_cols, label_cols = NULL)

Arguments

Value

Nested list for cascader options

Examples

df <- data.frame(
  province = c("Zhejiang", "Zhejiang", "Jiangsu"),
  city = c("Hangzhou", "Ningbo", "Nanjing"),
  stringsAsFactors = FALSE
)
df_to_cascader_options(df, c("province", "city"))

# Separate value and label columns
df$province_label <- paste(df$province, "Province")
df_to_cascader_options(df, c("province", "city"), c("province_label", NA))

Build tree data from a data frame

Description

Turns hierarchical columns into the nested node lists el_tree() expects, one level per column. Keys are built by joining a row's values down to that level, so a label repeated under different parents still gets a unique key.

Usage

df_to_tree_data(df, cols, sep = "/")

Arguments

Value

A list of nodes.

Examples

df <- data.frame(
  region = c("North", "North", "South"),
  city = c("Leeds", "York", "Bath"),
  stringsAsFactors = FALSE
)
df_to_tree_data(df, c("region", "city"))

Element Plus tags, for markup inside a component

Description

A tag generator for every Element tag, as tags$p is for HTML: el$button(type = "primary", "Go") writes ⁠<el-button type="primary">⁠. Nothing more – no Vue instance, no Shiny input, no id.

Usage

el

Details

An ⁠<el-*>⁠ tag becomes an Element component only when a Vue instance compiles it, so these belong where one already does:

• the markup of el_widget(), when building a component of your own;

• a template() or a component's slots;

• a table column's cell in el_table();

• the trigger of a wrapper – el_tooltip(), el_popover(), el_popconfirm().

Anywhere else – the top level of a page, or inside the markup-only containers (el_tabs(), el_collapse(), el_dialog(), el_drawer(), el_row(), el_container()) – nothing compiles them and they show as bare text; the browser console says so. There, use the component functions: el_button(), el_tag() and the rest.

A logical attribute is a Vue boolean: el$button(link = TRUE) writes ⁠<el-button link>⁠ and plain = FALSE writes ⁠:plain="false"⁠ – as text, link="TRUE", Element Plus would refuse it.

Mounting a Vue instance over such markup automatically is deliberately not done: it would rebuild every component and Shiny input inside it, leaving them on screen but disconnected from the server.

Value

A named list of tag-generating functions, one per Element Plus tag.

Examples

names(el)

# As a wrapper's trigger, compiled by the tooltip's own instance
el_tooltip("hint", el$button(type = "primary", "Hover me"), content = "Help")

# In a table cell, once per row
el_table(
  "tasks",
  data = data.frame(task = c("Draft", "Review"), done = c(TRUE, FALSE)),
  columns = list(
    list(prop = "task", label = "Task"),
    list(
      label = "State",
      cell = el$tag(
        ":type" = "scope.row.done ? 'success' : 'info'",
        "{{ scope.row.done ? 'done' : 'open' }}"
      )
    )
  )
)

# As the markup of a component of your own
el_widget(
  "me",
  markup = el$avatar(":size" = "size", "{{ initials }}"),
  data = list(size = 48, initials = "KY")
)

Element Plus Affix

Description

Content that stays fixed to the top or bottom of the viewport once scrolled to it.

Usage

el_affix(
  ...,
  id = NULL,
  offset = NULL,
  position = NULL,
  target = NULL,
  z_index = NULL,
  teleported = NULL,
  append_to = NULL,
  width = NULL,
  slots = NULL,
  events = NULL,
  on = NULL
)

update_el_affix(
  session = shiny::getDefaultReactiveDomain(),
  id,
  offset = NULL,
  position = NULL,
  z_index = NULL,
  target = NULL,
  teleported = NULL,
  append_to = NULL
)

Arguments

Value

A Shiny UI element.

Shiny inputs

The same list as el_events("el_affix"), which says how an event's arguments travel.

Element methods

Callable with call_el(): update(), updateRoot().

Updating from the server

update_el_affix() changes the component from the server: every argument of el_affix() that can change once it is drawn, under the same name. One left NULL stays as it is; NA returns it to Element's default.

update_el_affix() is called for its side effect and returns NULL invisibly.

Examples

el_affix(el_button("top", "Stays on top"), offset = 120)

Element Plus Alert

Description

An inline alert banner with optional close button. Fires a Shiny input when the user closes it.

Usage

el_alert(
  id = NULL,
  title = "",
  description = NULL,
  type = "info",
  closable = TRUE,
  close_text = "",
  show_icon = FALSE,
  center = FALSE,
  effect = "light",
  width = NULL,
  slots = NULL,
  on = NULL,
  session = NULL
)

update_el_alert(
  session = shiny::getDefaultReactiveDomain(),
  id,
  title = NULL,
  type = NULL,
  description = NULL,
  closable = NULL,
  close_text = NULL,
  show_icon = NULL,
  center = NULL,
  effect = NULL
)

Arguments

Value

An htmltools tagList with a Vue-managed alert component.

Shiny inputs

The same list as el_events("el_alert"), which says how an event's arguments travel.

Updating from the server

Server-side update for el_alert().

Every other argument of el_alert() 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_alert() is called for its side effect and returns NULL invisibly.

Examples

el_alert("al1", "Operation successful", type = "success", show_icon = TRUE)
el_alert("al2", "Warning!", description = "Please review.", type = "warning")
if (interactive()) {
  # inside a server function
  observeEvent(input$go, {
    update_el_alert(session, "hint", title = "Saved", type = "success")
  })
}

Element Plus Anchor

Description

Links to sections of the page, the one in view marked as the page scrolls.

Usage

el_anchor(
  id = NULL,
  links = list(),
  container = NULL,
  offset = NULL,
  bound = NULL,
  duration = NULL,
  marker = NULL,
  type = NULL,
  direction = NULL,
  select_scroll_top = NULL,
  width = NULL,
  slots = NULL,
  events = NULL,
  on = NULL
)

update_el_anchor(
  session = shiny::getDefaultReactiveDomain(),
  id,
  offset = NULL,
  bound = NULL,
  duration = NULL,
  marker = NULL,
  type = NULL,
  direction = NULL,
  select_scroll_top = NULL,
  container = NULL
)

Arguments

Value

A Shiny UI element.

Shiny inputs

The same list as el_events("el_anchor"), which says how an event's arguments travel.

Element methods

Callable with call_el(): scrollTo(href).

Updating from the server

update_el_anchor() changes the component from the server: every argument of el_anchor() that can change once it is drawn, under the same name. One left NULL stays as it is; NA returns it to Element's default.

update_el_anchor() is called for its side effect and returns NULL invisibly.

Examples

el_anchor(
  "toc",
  links = list(
    list(title = "Basic usage", href = "#basic"),
    list(
      title = "API",
      href = "#api",
      children = list(
        list(title = "Attributes", href = "#attributes")
      )
    )
  )
)

A link of el_anchor()

Description

Element Plus's el-anchor-link, for el_anchor(links =).

Usage

el_anchor_link(title, href, ...)

Arguments

Value

A link, for el_anchor(links =).

See Also

Other items: el_breadcrumb_item(), el_carousel_item(), el_collapse_item(), el_descriptions_item(), el_dropdown_item(), el_menu_item(), el_option(), el_skeleton_item(), el_step(), el_tab_pane(), el_table_column(), el_table_v2_column(), el_timeline_item(), el_tour_step()

Examples

el_anchor(
  "an",
  links = list(
    el_anchor_link("Basic Usage", "#basic-usage"),
    el_anchor_link(
      "API",
      "#api",
      el_anchor_link("Attributes", "#attributes"),
      el_anchor_link("Events", "#events")
    )
  )
)

Element Plus Aside

Description

Element Plus Aside

Usage

el_aside(..., width = "300px", style = NULL, class = NULL)

Arguments

Value

A Shiny UI element.

Examples

el_aside("Navigation")
el_aside(width = "200px", el_radio_group("nav", choices = c(Home = "h")))

Element Plus Autocomplete

Description

A text input that suggests as you type.

Usage

el_autocomplete(
  id = NULL,
  value = "",
  suggestions = NULL,
  remote = FALSE,
  fetch_suggestions = NULL,
  placeholder = NULL,
  clearable = NULL,
  disabled = NULL,
  value_key = NULL,
  debounce = NULL,
  placement = NULL,
  trigger_on_focus = NULL,
  select_when_unmatched = NULL,
  highlight_first_item = NULL,
  hide_loading = NULL,
  icon = NULL,
  prefix_icon = NULL,
  suffix_icon = NULL,
  label = NULL,
  name = NULL,
  popper_class = NULL,
  label_position = c("top", "left", "right"),
  label_width = NULL,
  label_suffix = NULL,
  required = FALSE,
  error = NULL,
  show_message = TRUE,
  inline_message = FALSE,
  append_to = NULL,
  aria_label = NULL,
  fit_input_width = NULL,
  loop_navigation = NULL,
  popper_options = NULL,
  popper_style = NULL,
  show_arrow = NULL,
  teleported = NULL,
  width = NULL,
  slots = NULL,
  events = NULL,
  on = NULL,
  session = NULL
)

update_el_autocomplete(
  session = shiny::getDefaultReactiveDomain(),
  id,
  value = NULL,
  suggestions = NULL,
  placeholder = NULL,
  disabled = NULL,
  label = NULL,
  error = NULL,
  clearable = NULL,
  value_key = NULL,
  debounce = NULL,
  placement = NULL,
  trigger_on_focus = NULL,
  select_when_unmatched = NULL,
  highlight_first_item = NULL,
  hide_loading = NULL,
  icon = NULL,
  prefix_icon = NULL,
  suffix_icon = NULL,
  name = NULL,
  popper_class = NULL,
  append_to = NULL,
  aria_label = NULL,
  fit_input_width = NULL,
  loop_navigation = NULL,
  popper_options = NULL,
  popper_style = NULL,
  show_arrow = NULL,
  teleported = NULL
)

Arguments

Value

A Shiny UI element.

Shiny inputs

The same list as el_events("el_autocomplete"), which says how an event's arguments travel.

Element methods

Callable with call_el():

• focus() – focus the input

Updating from the server

Server-side update for el_autocomplete().

Every other argument of el_autocomplete() 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_autocomplete() is called for its side effect and returns NULL invisibly.

Examples

el_autocomplete("city", suggestions = c("Beijing", "Shanghai", "Shenzhen"))

el_autocomplete(
  "city",
  suggestions = c("Beijing", "Shanghai"),
  placeholder = "Where to?",
  clearable = TRUE,
  width = 260
)
if (interactive()) {
  # inside a server function
  observeEvent(input$country, {
    update_el_autocomplete(
      session,
      "city",
      suggestions = cities_of(input$country)
    )
  })
}

Element Plus Avatar

Description

A user avatar, from an image, an icon, or text.

Usage

el_avatar(
  id = NULL,
  content = NULL,
  src = NULL,
  icon = NULL,
  size = NULL,
  shape = NULL,
  fit = NULL,
  src_set = NULL,
  alt = NULL,
  width = NULL,
  class = NULL,
  style = NULL,
  slots = NULL,
  events = NULL,
  on = NULL,
  session = NULL
)

update_el_avatar(
  session = shiny::getDefaultReactiveDomain(),
  id,
  content = NULL,
  src = NULL,
  icon = NULL,
  size = NULL,
  shape = NULL,
  fit = NULL,
  src_set = NULL,
  alt = NULL
)

Arguments

Value

A Shiny UI element.

Shiny inputs

The same list as el_events("el_avatar"), which says how an event's arguments travel.

Updating from the server

Server-side update for el_avatar().

Every other argument of el_avatar() 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_avatar() is called for its side effect and returns NULL invisibly.

Examples

el_avatar("me", src = "https://example.org/face.png")
el_avatar("initials", content = "KY", shape = "square", size = 40)
el_avatar("anon", icon = "el-icon-user-solid")
if (interactive()) {
  # inside a server function
  observeEvent(input$sign_in, {
    update_el_avatar(session, "me", src = user_photo())
  })
}

Element Plus Avatar Group

Description

Avatars overlapping in a row, the overflow collapsed into a count.

Usage

el_avatar_group(
  ...,
  id = NULL,
  size = NULL,
  shape = NULL,
  collapse_avatars = NULL,
  collapse_avatars_tooltip = NULL,
  max_collapse_avatars = NULL,
  effect = NULL,
  placement = NULL,
  popper_class = NULL,
  popper_style = NULL,
  collapse_class = NULL,
  collapse_style = NULL,
  width = NULL,
  slots = NULL,
  on = NULL
)

update_el_avatar_group(
  session = shiny::getDefaultReactiveDomain(),
  id,
  size = NULL,
  shape = NULL,
  collapse_avatars = NULL,
  collapse_avatars_tooltip = NULL,
  max_collapse_avatars = NULL,
  effect = NULL,
  placement = NULL,
  popper_class = NULL,
  popper_style = NULL,
  collapse_class = NULL,
  collapse_style = NULL
)

Arguments

Value

A Shiny UI element.

Shiny inputs

None: it reports nothing.

Updating from the server

update_el_avatar_group() changes the component from the server: every argument of el_avatar_group() that can change once it is drawn, under the same name. One left NULL stays as it is; NA returns it to Element's default.

update_el_avatar_group() is called for its side effect and returns NULL invisibly.

Examples

el_avatar_group(
  el_avatar(src = "https://example.com/a.png"),
  el_avatar("B"),
  collapse_avatars = TRUE
)

Element Plus Back to Top

Description

A button that appears once the page has been scrolled down, and returns it to the top when clicked.

Usage

el_backtop(
  id = NULL,
  content = NULL,
  target = NULL,
  visibility_height = NULL,
  right = NULL,
  bottom = NULL,
  width = NULL,
  slots = NULL,
  events = NULL,
  on = NULL,
  session = NULL
)

update_el_backtop(
  session = shiny::getDefaultReactiveDomain(),
  id,
  visibility_height = NULL,
  right = NULL,
  bottom = NULL,
  target = NULL
)

Arguments

Value

A Shiny UI element.

Shiny inputs

The same list as el_events("el_backtop"), which says how an event's arguments travel.

Updating from the server

Server-side update for el_backtop().

Every other argument of el_backtop() 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_backtop() is called for its side effect and returns NULL invisibly.

Examples

el_backtop("top")
el_backtop("top", visibility_height = 100, right = 20, bottom = 20)

# Scrolling a panel rather than the page
el_backtop("panel_top", target = "#report")
if (interactive()) {
  # inside a server function
  observeEvent(input$compact, {
    update_el_backtop(session, "top", right = 10, bottom = 10)
  })
}

Element Plus Badge

Description

Wraps any content with a numeric badge or red dot in the top-right corner. When used without content, renders a standalone badge element.

Usage

el_badge(
  ...,
  value = NULL,
  max = NULL,
  is_dot = FALSE,
  hidden = FALSE,
  type = NULL,
  id = NULL,
  show_zero = TRUE,
  color = NULL,
  offset = NULL,
  badge_style = NULL,
  badge_class = NULL,
  on = NULL
)

update_el_badge(
  session = shiny::getDefaultReactiveDomain(),
  id,
  value = NULL,
  max = NULL,
  is_dot = NULL,
  hidden = NULL,
  type = NULL
)

Arguments

Value

An htmltools tag, or with an id a Shiny UI element.

Updating from the server

Server-side update for an el_badge() given an id.

update_el_badge() is called for its side effect and returns NULL invisibly.

Examples

el_badge(el_button("btn1", "Messages"), value = 5)
el_badge(el_button("btn2", "Alerts"), value = 200, max = 99)
el_badge(el_button("btn3", "Updates"), is_dot = TRUE)

# Updated from the server: update_el_badge(session, "unread", value = 7)
el_badge(el_button("inbox", "Inbox"), value = 3, id = "unread")
if (interactive()) {
  # inside a server function
  observe(update_el_badge(
    session,
    "unread",
    value = unread_count(),
    hidden = unread_count() == 0
  ))
}

Element Plus Breadcrumb

Description

A trail of links showing where a page sits.

Usage

el_breadcrumb(
  id = NULL,
  items = list(),
  separator = NULL,
  separator_icon = NULL,
  width = NULL,
  slots = NULL,
  on = NULL,
  session = NULL
)

update_el_breadcrumb(
  session = shiny::getDefaultReactiveDomain(),
  id,
  items = NULL,
  separator = NULL,
  separator_icon = NULL
)

Arguments

Value

A Shiny UI element.

Shiny inputs

The same list as el_events("el_breadcrumb"), which says how an event's arguments travel.

Steps without a to are reported too, so a breadcrumb can drive navigation inside a Shiny app without any routing.

Updating from the server

Server-side update for el_breadcrumb().

Every other argument of el_breadcrumb() 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_breadcrumb() is called for its side effect and returns NULL invisibly.

Examples

el_breadcrumb(
  "trail",
  items = list(
    list(label = "Home"),
    list(label = "Reports"),
    list(label = "March")
  )
)

# An arrow instead of a slash
el_breadcrumb(
  "trail",
  items = list(list(label = "Home"), list(label = "Detail")),
  separator_icon = "ArrowRight"
)
if (interactive()) {
  # inside a server function
  observeEvent(input$open_detail, {
    update_el_breadcrumb(
      session,
      "trail",
      items = list(
        list(label = "Home"),
        list(label = "Detail")
      )
    )
  })
}

A step of el_breadcrumb()

Description

Element Plus's el-breadcrumb-item, for el_breadcrumb(items =).

Usage

el_breadcrumb_item(label, to = NULL, replace = NULL)

Arguments

Value

A step, for el_breadcrumb(items =).

See Also

Other items: el_anchor_link(), el_carousel_item(), el_collapse_item(), el_descriptions_item(), el_dropdown_item(), el_menu_item(), el_option(), el_skeleton_item(), el_step(), el_tab_pane(), el_table_column(), el_table_v2_column(), el_timeline_item(), el_tour_step()

Examples

el_breadcrumb(
  "bc",
  items = list(
    el_breadcrumb_item("Home", to = "/"),
    el_breadcrumb_item("Promotion list")
  )
)

Element Plus Button with Vue Instance

Description

Creates an Element Plus button with Vue instance, supporting all Element Plus button variants including plain, round, circle, and loading states.

Usage

el_button(
  id = NULL,
  label = "Button",
  type = NULL,
  size = NULL,
  plain = NULL,
  round = NULL,
  circle = FALSE,
  loading = FALSE,
  task = FALSE,
  disabled = FALSE,
  icon = NULL,
  native_type = "button",
  autofocus = FALSE,
  auto_insert_space = NULL,
  bg = NULL,
  color = NULL,
  dark = NULL,
  dashed = NULL,
  link = NULL,
  loading_icon = NULL,
  tag = NULL,
  text = NULL,
  class = NULL,
  style = NULL,
  width = NULL,
  slots = NULL,
  on = NULL,
  session = NULL
)

update_el_button(
  session = shiny::getDefaultReactiveDomain(),
  id,
  label = NULL,
  type = NULL,
  size = NULL,
  plain = NULL,
  round = NULL,
  loading = NULL,
  disabled = NULL,
  circle = NULL,
  icon = NULL,
  autofocus = NULL,
  auto_insert_space = NULL,
  bg = NULL,
  color = NULL,
  dark = NULL,
  dashed = NULL,
  link = NULL,
  loading_icon = NULL,
  tag = NULL,
  text = NULL
)

Arguments

Value

An htmltools tagList with a Vue-managed button component.

Shiny inputs

The same list as el_events("el_button"), which says how an event's arguments travel.

Counted as shiny::actionButton() counts: 0 on load, and only while neither disabled nor loading is TRUE. It carries the same class, so observeEvent() and req() treat 0 as not yet clicked.

Updating from the server

Server-side update for el_button(). Supports all visual states including size, plain, round, and loading.

Every other argument of el_button() 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_button() is called for its side effect and returns NULL invisibly.

Examples

# Basic usage
el_button("btn_primary", "Primary", type = "primary")

# Shiny app example
if (interactive()) {
  library(shiny)
  library(shiny.element)
  ui <- el_page(
    el_button("btn1", "Primary", type = "primary"),
    verbatimTextOutput("count")
  )
  server <- function(input, output, session) {
    output$count <- renderPrint(input$btn1)
  }
  shinyApp(ui, server)
}
if (interactive()) {
  # inside a server function
  observeEvent(input$go, {
    update_el_button(session, "save", loading = TRUE)
  })
}

Element Plus Button Group

Description

Buttons joined into one bar, as Element's el-button-group draws them: shared borders, rounded only at the ends. Each el_button() inside keeps reporting its own clicks as ⁠input$<its id>⁠.

Usage

el_button_group(
  ...,
  id = NULL,
  size = NULL,
  type = NULL,
  direction = NULL,
  width = NULL,
  on = NULL
)

update_el_button_group(
  session = shiny::getDefaultReactiveDomain(),
  id,
  size = NULL,
  type = NULL,
  direction = NULL
)

Arguments

Details

The buttons are folded into the group's Vue instance rather than nested (see el_tooltip()): Element styles the group through its direct children, which a button with a host of its own would not be. So update_el_button() cannot reach them; set their fields with update_vue() on the group's id.

Value

A Shiny UI element.

Updating from the server

update_el_button_group() changes the component from the server: every argument of el_button_group() that can change once it is drawn, under the same name. One left NULL stays as it is; NA returns it to Element's default.

update_el_button_group() is called for its side effect and returns NULL invisibly.

Examples

el_button_group(
  el_button("prev", "Previous", icon = "ArrowLeft", type = "primary"),
  el_button("next", "Next", type = "primary")
)

Element Plus Calendar

Description

A month of days to pick one from, or a range of weeks to show – and, with events, a month planner: each day shows its events, which the user can add, edit, delete and drag to another day (editable). Days show times, groups (calendars) and a "+N more" beyond visible_event_count; the dialog and the popovers take Element's components of your own through slots.

Usage

el_calendar(
  id = NULL,
  value = NULL,
  range = 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,
  controller_type = NULL,
  formatter = NULL,
  width = NULL,
  slots = NULL,
  session = NULL,
  events = NULL,
  editable = FALSE,
  event_labels = NULL,
  calendars = NULL,
  visible_event_count = NULL,
  use_detail_popup = FALSE,
  first_day_of_week = NULL,
  workweek = FALSE
)

update_el_calendar(
  session = shiny::getDefaultReactiveDomain(),
  id,
  value = NULL,
  range = NULL,
  label = NULL,
  error = NULL,
  controller_type = NULL,
  formatter = NULL,
  events = NULL,
  insert = NULL,
  replace = NULL,
  delete = NULL,
  editable = NULL,
  event_labels = NULL,
  calendars = NULL,
  visible_event_count = NULL,
  use_detail_popup = NULL,
  first_day_of_week = NULL,
  workweek = NULL
)

Arguments

Details

The server owns the events, as toastui's calendar has it: what the user does arrives as a request – ⁠input$<id>_add⁠, ⁠_update⁠, ⁠_delete⁠ – and the calendar changes when the server answers with update_el_calendar() (insert, replace, delete, or all of them with events). So the server can check a change, give a new event its id from a database, or refuse. Without Shiny – a static page – the calendar applies the user's changes itself.

Value

A Shiny UI element.

Shiny inputs

The requests change nothing by themselves: answer them with update_el_calendar(), as the example does.

Updating from the server

Server-side update for el_calendar(): the selected day, the range, and every other argument that can change once the calendar is drawn, under the same name. One left NULL stays as it is; NA returns a prop to Element's default.

events replaces all the events; insert, replace and delete change a few, found by id, and send only those – one of the four per call. calendars replaces the groups: an isVisible = FALSE hides a group's events, as toastui's cal_proxy_toggle() does.

update_el_calendar() is called for its side effect and returns NULL invisibly.

Examples

# The default day cell
el_calendar("cal")

# Your own, with whatever Element hands the template
el_calendar(
  "cal",
  slots = list(
    dateCell = template(
      htmltools::HTML("<p>{{ data.day.slice(8) }}</p>"),
      slot = "dateCell",
      scope = "{date, data}"
    )
  )
)
# Basic usage
el_calendar(id = "calendar1", value = Sys.Date())

# With date range
el_calendar(id = "calendar2", range = c("2025-01-01", "2025-01-31"))

# A planner whose events the server keeps, rendered as an output: each
# request changes them, and the calendar is rendered again -- patched,
# only the events sent
if (interactive()) {
  library(shiny)
  library(shiny.element)
  ui <- el_page(el_calendar_output("plan"))
  server <- function(input, output, session) {
    events <- reactiveVal(data.frame(
      id = 1:2,
      date = Sys.Date() + c(0, 3),
      title = c("Standup", "Review"),
      type = c("primary", "warning")
    ))
    output$plan <- render_el_calendar(
      el_calendar(events = events(), editable = TRUE)
    )
    observeEvent(input$plan_add, {
      new <- input$plan_add
      events(rbind(
        events(),
        data.frame(
          id = max(events()$id) + 1L,
          date = new$date,
          title = new$title,
          type = new$type
        )
      ))
    })
    observeEvent(input$plan_update, {
      d <- events()
      i <- d$id == input$plan_update$event$id
      for (k in intersect(names(input$plan_update$changes), names(d))) {
        d[[k]][i] <- input$plan_update$changes[[k]]
      }
      events(d)
    })
    observeEvent(input$plan_delete, {
      events(events()[events()$id != input$plan_delete$id, ])
    })
  }
  shinyApp(ui, server)
}
if (interactive()) {
  # inside a server function
  observeEvent(input$go, {
    update_el_calendar(session, "cal", value = "2026-06-01")
  })
  update_el_calendar(session, "cal", controller_type = "select")
}

The events a calendar shows

Description

What the browser holds, as R: the events last rendered with render_el_calendar() or sent with update_el_calendar(), with every event update_el_calendar() has since inserted, replaced or deleted. The user's requests (⁠input$<id>_add⁠, ...) are not in it until the server answers them. A reactive read.

Usage

el_calendar_events(session = shiny::getDefaultReactiveDomain(), id)

Arguments

Value

The events, as given; NULL for a calendar the server has not rendered or updated.

See Also

render_el_calendar(), update_el_calendar().

Examples

if (interactive()) {
  library(shiny)
  ui <- el_page(el_calendar_output("plan"), verbatimTextOutput("n"))
  server <- function(input, output, session) {
    output$plan <- render_el_calendar(el_calendar(
      events = data.frame(id = 1, date = Sys.Date(), title = "Review")
    ))
    # the events the calendar shows, read back as R
    output$n <- renderText(nrow(el_calendar_events(id = "plan")))
  }
  shinyApp(ui, server)
}

A calendar as a Shiny output

Description

The calendar of an app whose events the server reads – from a database, a folder, a computation – as toastui's calendarOutput() and renderCalendar(): the page holds el_calendar_output(), the server renders el_calendar() into it with its events. Rendering again with new events patches the calendar in place: the month shown and an open dialog stay, and only what changed is sent.

Usage

el_calendar_output(outputId, width = "100%", loading = TRUE)

render_el_calendar(expr, env = parent.frame(), quoted = FALSE)

Arguments

Details

The output's id is the calendar's: ⁠input$<id>⁠ is the day picked and ⁠input$<id>_click⁠, ⁠_dates⁠, ⁠_add⁠, ⁠_update⁠, ⁠_delete⁠ are as for el_calendar(); update_el_calendar() reaches the calendar by it, and el_calendar_events() reads the events it shows.

Value

el_calendar_output(), a tag; render_el_calendar(), a render function.

See Also

el_calendar(), update_el_calendar(), el_calendar_events().

Examples

if (interactive()) {
  library(shiny)
  archive <- data.frame(
    date = Sys.Date() - c(9, 6, 2),
    title = c("", "", "Validated"),
    body = c("Raw data", "Archive", "Validated data"),
    color = c("lightgrey", "#EED5B7", "#E9C46B")
  )
  ui <- el_page(el_calendar_output("snapshot"), verbatimTextOutput("picked"))
  server <- function(input, output, session) {
    output$snapshot <- render_el_calendar(
      el_calendar(value = max(archive$date), events = archive)
    )
    output$picked <- renderPrint(input$snapshot_click$date)
  }
  shinyApp(ui, server)
}

Element Plus Card

Description

A card container with optional header and body. Supports always, hover, and never shadow modes.

Usage

el_card(
  ...,
  header = NULL,
  body_style = NULL,
  shadow = NULL,
  footer = NULL,
  header_class = NULL,
  body_class = NULL,
  footer_class = NULL,
  class = NULL,
  style = NULL
)

Arguments

Value

An htmltools tag.

Examples

el_card(shiny::tags$p("Card body text."), header = "My Card")
el_card(shiny::tags$p("No shadow."), shadow = "never")

Element Plus Carousel

Description

A slideshow of items, horizontal or vertical.

Usage

el_carousel(
  id = NULL,
  items = list(),
  height = "300px",
  initial_index = 0,
  autoplay = TRUE,
  interval = 3000,
  trigger = "hover",
  indicator_position = NULL,
  arrow = "hover",
  type = NULL,
  loop = TRUE,
  direction = "horizontal",
  card_scale = NULL,
  motion_blur = NULL,
  pause_on_hover = NULL,
  width = NULL,
  slots = NULL,
  on = NULL,
  session = NULL
)

update_el_carousel(
  session = shiny::getDefaultReactiveDomain(),
  id,
  active = NULL,
  autoplay = NULL,
  interval = NULL,
  height = NULL,
  initial_index = NULL,
  trigger = NULL,
  indicator_position = NULL,
  arrow = NULL,
  loop = NULL,
  direction = NULL
)

Arguments

Value

A Shiny UI element.

Shiny inputs

The same list as el_events("el_carousel"), which says how an event's arguments travel.

Element methods

Callable with call_el():

• next() – Switch to the next slide

• prev() – Switch to the previous slide

• setActiveItem() – Manually switch slide

Updating from the server

update_el_carousel() changes the component from the server.

Every other argument of el_carousel() 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_carousel() is called for its side effect and returns NULL invisibly.

Examples

el_carousel(
  id = "banner",
  height = "200px",
  items = list(
    list(name = "one", content = shiny::tags$h3("First slide")),
    list(name = "two", content = shiny::tags$h3("Second slide")),
    list(name = "three", content = shiny::tags$h3("Third slide"))
  )
)

# Card layout, switching on click rather than hover
el_carousel(
  id = "cards",
  type = "card",
  trigger = "click",
  height = "180px",
  items = lapply(1:4, function(i) list(content = paste("Card", i)))
)
if (interactive()) {
  # inside a server function
  observeEvent(input$go, {
    update_el_carousel(session, "banner", active = 2)
  })
}

A slide of el_carousel()

Description

Element Plus's el-carousel-item, for el_carousel(items =).

Usage

el_carousel_item(..., name = NULL, label = NULL, style = NULL, class = NULL)

Arguments

Value

A slide, for el_carousel(items =).

See Also

Other items: el_anchor_link(), el_breadcrumb_item(), el_collapse_item(), el_descriptions_item(), el_dropdown_item(), el_menu_item(), el_option(), el_skeleton_item(), el_step(), el_tab_pane(), el_table_column(), el_table_v2_column(), el_timeline_item(), el_tour_step()

Examples

el_carousel(
  "car",
  items = list(
    el_carousel_item(htmltools::tags$h3("1"), name = "first"),
    el_carousel_item(htmltools::tags$h3("2"), name = "second")
  )
)

Element Plus Cascader

Description

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

Value

A Shiny UI element.

Shiny inputs

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.

Element methods

Callable with call_el():

• getCheckedNodes() – Get an array of currently selected node

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"))
  })
}

Element Plus Cascader Panel

Description

The panel of an el_cascader() on its own, always open: nested options in side-by-side columns, for when there is room to show them rather than tuck them into a dropdown.

Usage

el_cascader_panel(
  id = NULL,
  options = list(),
  value = NULL,
  props = 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,
  height = NULL,
  item_size = NULL,
  virtual_scroll = NULL,
  width = NULL,
  slots = NULL,
  level_inputs = NULL,
  events = NULL,
  on = NULL,
  session = NULL
)

update_el_cascader_panel(
  session = shiny::getDefaultReactiveDomain(),
  id,
  value = NULL,
  options = NULL,
  label = NULL,
  error = NULL,
  props = NULL,
  height = NULL,
  item_size = NULL,
  virtual_scroll = NULL
)

Arguments

Value

A Shiny UI element.

Shiny inputs

The same list as el_events("el_cascader_panel"), which says how an event's arguments travel.

With level_inputs, each level of the path is an input too, as for el_cascader().

Element methods

Callable with call_el():

• getCheckedNodes() – the selected options

• clearCheckedNodes() – clear the selection

Updating from the server

Server-side update for el_cascader_panel().

Every other argument of el_cascader_panel() 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_panel() is called for its side effect and returns NULL invisibly.

Examples

regions <- list(
  list(
    value = "asia",
    label = "Asia",
    children = list(
      list(value = "cn", label = "China"),
      list(value = "jp", label = "Japan")
    )
  ),
  list(
    value = "europe",
    label = "Europe",
    children = list(
      list(value = "fr", label = "France")
    )
  )
)
el_cascader_panel("where", options = regions, value = c("asia", "jp"))

# Several at once
el_cascader_panel("where", options = regions, props = list(multiple = TRUE))
if (interactive()) {
  # inside a server function
  observeEvent(
    input$reset,
    update_el_cascader_panel(session, "where", value = list())
  )
}

Element Plus Check Tag

Description

A tag that toggles on and off when clicked, as a checkbox does.

Usage

el_check_tag(
  id,
  label,
  value = FALSE,
  disabled = NULL,
  type = NULL,
  width = NULL,
  on = NULL
)

update_el_check_tag(
  session = shiny::getDefaultReactiveDomain(),
  id,
  value = NULL,
  label = NULL,
  disabled = NULL,
  type = NULL
)

Arguments

Value

A Shiny UI element.

Shiny inputs

The same list as el_events("el_check_tag"), which says how an event's arguments travel.

Updating from the server

update_el_check_tag() changes the component from the server.

Every other argument of el_check_tag() 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_check_tag() is called for its side effect and returns NULL invisibly.

Examples

el_check_tag("pinned", "Pinned", value = TRUE)
el_check_tag("urgent", "Urgent", type = "danger")
if (interactive()) {
  # inside a server function
  observeEvent(
    input$clear,
    update_el_check_tag(session, "pinned", value = FALSE)
  )
}