Transfer • shiny.element

Basic usage

Data is passed to Transfer via the data attribute. The data needs to be an object array, and each object should have these attributes: key being the identification of the data item, label being the displayed text, and disabled indicating if the data item is disabled. Items inside the target list are in sync with the variable binding to v-model, and the value of that variable is an array of target item keys. So, if you don’t want the target list be initially empty, you can initialize the v-model with an array.

data is a data frame of key and label (and disabled), and input$<id> the keys on the right.

items <- data.frame(
  key = 1:15,
  label = paste("Option", 1:15),
  disabled = 1:15 %% 4 == 0
)
el_transfer("basic", data = items)

Filterable

You can search and filter data items.

Set the filterable attribute to true to enable filter mode. By default, if the data item label contains the search keyword, it will be included in the search result. Also, you can implement you own filter method with the filter-method attribute. It takes a method and passes search keyword and each data item to it whenever the keyword changes. For a certain data item, if the method returns true, it will be included in the result list.

filter_method searches the states by their initials.

states <- c(
  "California",
  "Illinois",
  "Maryland",
  "Texas",
  "Florida",
  "Colorado",
  "Connecticut "
)
el_transfer(
  "states",
  data = data.frame(
    label = states,
    key = seq_along(states) - 1,
    initial = c("CA", "IL", "MD", "TX", "FL", "CO", "CT")
  ),
  filterable = TRUE,
  filter_method = JS(
    "function(query, item) { return item.initial.toLowerCase().includes(query.toLowerCase()); }"
  ),
  filter_placeholder = "State Abbreviations"
)

Customizable

You can customize list titles, button texts, render function for data items, checking status texts in list footer and list footer contents.

Use titles, button-texts, render-content and format to respectively customize list titles, button texts, render function for data items, checking status texts in list header. Plus, you can also use scoped slot to customize data items. For list footer contents, two named slots are provided: left-footer and right-footer. Plus, if you want some items initially checked, you can use left-default-checked and right-default-checked. Finally, this example demonstrate the change event. Note that this demo can’t run in JSFiddle because it doesn’t support JSX syntax. In a real project, render-content will work if relevant dependencies are correctly configured.

The first draws each item with render_content, a function given h; the second with the default slot, scoped with option. Both relabel the panels and buttons, start with items checked, and put a button in each footer.

items <- data.frame(
  key = 1:15,
  label = paste("Option", 1:15),
  disabled = 1:15 %% 4 == 0
)
custom <- function(id, ...) {
  tags$div(
    style = "text-align: center",
    el_transfer(
      id,
      data = items,
      value = 1,
      filterable = TRUE,
      left_default_checked = c(2, 3),
      right_default_checked = 1,
      titles = c("Source", "Target"),
      button_texts = c("To left", "To right"),
      format = list(noChecked = "${total}", hasChecked = "${checked}/${total}"),
      ...
    )
  )
}
footers <- function(side) {
  el_button(label = "Operation", size = "small", class = "transfer-footer")
}
tagList(
  tags$style(
    ".transfer-footer { margin-left: 15px; padding: 6px 5px; }
     #custom_render .el-transfer, #custom_slot .el-transfer {
       text-align: left; display: inline-block; }"
  ),
  tags$p(
    style = "text-align: center; margin: 0 0 20px",
    "Customize data items using render-content"
  ),
  custom(
    "custom_render",
    render_content = JS(
      "function(h, option) { return h('span', null, option.label); }"
    ),
    slots = list(`left-footer` = footers(), `right-footer` = footers())
  ),
  tags$p(
    style = "text-align: center; margin: 50px 0 20px",
    "Customize data items using scoped slot"
  ),
  custom(
    "custom_slot",
    slots = list(
      default = template(
        tags$span("{{ option.key }} - {{ option.label }}"),
        scope = "{ option }"
      ),
      `left-footer` = footers(),
      `right-footer` = footers()
    )
  )
)

Customize data items using render-content

Customize data items using scoped slot

Custom empty content

You can customize the content when the list is empty or when no filtering results are found.

Use left-empty and right-empty slots to customize the empty content for each panel.

The left-empty and right-empty slots draw an empty list: the right one at the start.

items <- data.frame(
  key = 1:15,
  label = paste("Option", 1:15),
  disabled = 1:15 %% 4 == 0
)
el_transfer(
  "empty",
  data = items,
  slots = list(
    `left-empty` = el_empty(
      "empty_left",
      image_size = 60,
      description = "No data"
    ),
    `right-empty` = el_empty(
      "empty_right",
      image_size = 60,
      description = "No data"
    )
  )
)

Prop aliases

By default, Transfer looks for key, label and disabled in a data item. If your data items have different key names, you can use the props attribute to define aliases.

The data items in this example do not have keys or labels, instead they have values and descs. So you need to set aliases for key and label.

Items whose fields are named otherwise: props says which is which.

items <- data.frame(
  value = 1:15,
  desc = paste("Option", 1:15),
  disabled = 1:15 %% 4 == 0
)
el_transfer(
  "aliases",
  data = items,
  props = list(key = "value", label = "desc")
)

Virtual Scroll

When dealing with large amounts of data, you can enable virtual scrolling to improve performance.

Set virtual-scroll to true to enable virtual scrolling. You can also customize the item height with item-size. Default item size is 30px.

virtual_scroll draws only the rows in view, for long lists.

items <- data.frame(
  key = 1:2000,
  label = paste("Option", 1:2000),
  disabled = 1:2000 %% 4 == 0
)
el_transfer("virtual", data = items, virtual_scroll = TRUE, item_size = 30)

API

Element Plus’s tables, and beside each entry where it is in R.

Transfer Attributes

Element	In R	Description	Type	Default
`model-value`	`value`; `input$<id>`	binding value	¹`Array<string \\\| number>`	[]
`data`	`data`	data source	²`Record<string, any>[]`	[]
`filterable`	`filterable`	whether Transfer is filterable	³	false
`filter-placeholder`	`filter_placeholder`	placeholder for the filter input	⁴	—
`filter-method`	`filter_method`	custom filter method	⁵`(query: string, item: Record<string, any>) => boolean`	—
`target-order`	`target_order`	order strategy for elements in the target list. If set to `original`, the elements will keep the same order as the data source. If set to `push`, the newly added elements will be pushed to the bottom. If set to `unshift`, the newly added elements will be inserted on the top	⁶`'original' \\\| 'push' \\\| 'unshift'`	original
`titles`	`titles`	custom list titles	⁷`[string, string]`	[]
`button-texts`	`button_texts`	custom button texts	⁸`[string, string]`	[]
`render-content`	`render_content`	custom render function for data items	⁹`renderContent`	—
`format`	`format`	texts for checking status in list header	¹⁰`TransferFormat`	{}
`props`	`props`	prop aliases for data source	¹¹`TransferPropsAlias`	—
`left-default-checked`	`left_default_checked`	key array of initially checked data items of the left list	¹²`Array<string \\\| number>`	[]
`right-default-checked`	`right_default_checked`	key array of initially checked data items of the right list	¹³`Array<string \\\| number>`	[]
`validate-event`	`validate_event`	whether to trigger form validation	¹⁴	true
`virtual-scroll`	`virtual_scroll`	whether to enable virtual scrolling	¹⁵	false
`item-size`	`item_size`	item height for virtual scrolling	¹⁶	30

Transfer Events

Element	In R	Description
`change`	`input$<id>_change`	triggers when data items change in the right list
`left-check-change`	`input$<id>_left_check_change`	triggers when end user changes the checked state of any data item in the left list
`right-check-change`	`input$<id>_right_check_change`	triggers when end user changes the checked state of any data item in the right list

Transfer Slots

Element	In R	Description
`default`	default content	Custom content for data items.
`left-footer`	`slots = list(left-footer = )`	content of left list footer
`right-footer`	`slots = list(right-footer = )`	content of right list footer
`left-empty`	`slots = list(left-empty = )`	content when left panel is empty or when no data matches the filter
`right-empty`	`slots = list(right-empty = )`	content when right panel is empty or when no data matches the filter

Transfer Exposes

Element	In R	Description
`clearQuery`	`call_el(session, id, "clearQuery")`	clear the filter keyword of a certain panel