Upload files by clicking or drag-and-drop.
Basic Usage
Customize upload button type and text using slot. Set
limit and on-exceed to limit the maximum
number of uploads allowed and specify method when the limit is exceeded.
Plus, you can abort removing a file in the before-remove
hook.
action posts the files to a URL with Element’s own
upload – here upstream’s mock service, as its example does. With no
action they go through Shiny’s own upload channel, and
input$<id> is the data frame fileInput()
gives – name, size, type,
datapath. limit caps the number of files;
on_exceed hears when there are more.
el_upload(
"docs",
action = "https://run.mocky.io/v3/9d059bf9-4660-45f2-925d-ce80ad6c4d15",
button_label = "Click to upload",
multiple = TRUE,
limit = 3,
tip = "jpg/png files with a size less than 500KB.",
file_list = list(
list(
name = "element-plus-logo.svg",
url = "https://element-plus.org/images/element-plus-logo.svg"
),
list(
name = "element-plus-logo2.svg",
url = "https://element-plus.org/images/element-plus-logo.svg"
)
),
on_preview = JS("function(uploadFile) { console.log(uploadFile); }"),
on_remove = JS(
"function(file, uploadFiles) { console.log(file, uploadFiles); }"
),
before_remove = JS(
"function(uploadFile) {",
" return ElementPlus.ElMessageBox.confirm('Cancel the transfer of ' + uploadFile.name + ' ?')",
" .then(function() { return true; }, function() { return false; });",
"}"
),
on_exceed = JS(
"function(files, uploadFiles) {",
" ElementPlus.ElMessage.warning('The limit is 3, you selected ' + files.length +",
" ' files this time, add up to ' + (files.length + uploadFiles.length) + ' totally');",
"}"
)
)Cover Previous File
Set limit and on-exceed to automatically
replace the previous file when select a new file.
With limit = 1, a new file covers the old one:
on_exceed clears the list and starts the new file, through
the upload’s own methods – $find(id), as upstream’s
ref. The button sends it, with submit().
el_upload(
"cover",
action = "https://run.mocky.io/v3/9d059bf9-4660-45f2-925d-ce80ad6c4d15",
limit = 1,
auto_upload = FALSE,
button_label = "select file",
tip = "limit 1 file, new file will cover the old file",
on_exceed = v_bind(paste(
"(files) => { const upload = $find('cover'); upload.clearFiles();",
"const file = files[0]; file.uid = ElementPlus.genFileId();",
"upload.handleStart(file); }"
))
)
el_button(
"cover_submit",
"upload to server",
type = "success",
on = list(click = v_on("$find('cover').submit()"))
)User Avatar
Use before-upload hook to limit the upload file format
and size.
One picture, no list: the slot draws the box, a JS()
hook checks the file before it goes.
tagList(
tags$style(
".avatar-uploader .el-upload { border: 1px dashed var(--el-border-color);",
" border-radius: 6px; width: 178px; height: 178px; display: flex;",
" align-items: center; justify-content: center; font-size: 28px; color: #8c939d; }"
),
tags$div(
class = "avatar-uploader",
el_upload(
"avatar",
show_file_list = FALSE,
accept = "image/*",
before_upload = JS(
"function(file) {",
" if (file.size / 1024 / 1024 > 2) {",
" ElementPlus.ElMessage.error('Avatar picture size can not exceed 2MB!');",
" return false;",
" }",
" return true;",
"}"
),
slots = list(default = el_icon("Plus"))
)
)
)Photo Wall
Use list-type to change the fileList style.
list_type = "picture-card": each file a card with its
thumbnail. A card’s preview button calls on_preview, which
puts the file in a store that a dialog follows – as upstream’s
dialogImageUrl and dialogVisible.
food <- "https://fuss10.elemecdn.com/3/63/4e7f3a15429bfda99bce42a18cdd1jpeg.jpeg"
plant <- "https://element-plus.org/images/plant-1.png"
vue_store("photo_preview", state = list(url = "", open = FALSE))
el_upload(
"photos",
action = "https://run.mocky.io/v3/9d059bf9-4660-45f2-925d-ce80ad6c4d15",
list_type = "picture-card",
file_list = list(
list(name = "food.jpeg", url = food),
list(name = "plant-1.png", url = plant),
list(name = "food.jpeg", url = food)
),
on_preview = v_bind(paste(
"(uploadFile) => { $vueStore.photo_preview.url = uploadFile.url;",
"$vueStore.photo_preview.open = true; }"
)),
on_remove = JS(
"function(uploadFile, uploadFiles) { console.log(uploadFile, uploadFiles); }"
),
slots = list(default = el_icon("Plus"))
)
el_dialog(
"photo_dialog",
visible = v_model("$vueStore.photo_preview.open"),
content = vue_app(
"photo_img",
tags$img(
style = "width: 100%",
`:src` = "$vueStore.photo_preview.url",
alt = "Preview Image"
)
)
)Custom Thumbnail
Use scoped-slot to change default thumbnail
template.
The file slot, scoped with file, draws each
card, with buttons of its own: zoom shows the file in a dialog that
follows a store, as upstream’s; download and delete write it to the
console.
vue_store("thumb_preview", state = list(url = "", open = FALSE))
el_upload(
"thumbs",
action = "https://run.mocky.io/v3/9d059bf9-4660-45f2-925d-ce80ad6c4d15",
list_type = "picture-card",
auto_upload = FALSE,
file_list = list(list(
name = "food.jpeg",
url = "https://fuss10.elemecdn.com/3/63/4e7f3a15429bfda99bce42a18cdd1jpeg.jpeg"
)),
slots = list(
default = el_icon("Plus"),
file = template(
slot = "file",
scope = "{ file }",
tags$div(
tags$img(
class = "el-upload-list__item-thumbnail",
`:src` = "file.url",
alt = ""
),
tags$span(
class = "el-upload-list__item-actions",
tags$span(
class = "el-upload-list__item-preview",
v_on(
click = "$vueStore.thumb_preview.url = file.url; $vueStore.thumb_preview.open = true"
),
el_icon("ZoomIn")
),
tags$span(
class = "el-upload-list__item-delete",
v_on(click = "console.log(file)"),
el_icon("Download")
),
tags$span(
class = "el-upload-list__item-delete",
v_on(click = "console.log(file)"),
el_icon("Delete")
)
)
)
)
)
)
el_dialog(
"thumb_dialog",
visible = v_model("$vueStore.thumb_preview.open"),
content = vue_app(
"thumb_img",
tags$img(
style = "width: 100%",
`:src` = "$vueStore.thumb_preview.url",
alt = "Preview Image"
)
)
)File List with Thumbnail
el_upload(
"pics",
list_type = "picture",
button_label = "Click to upload",
tip = "jpg/png files with a size less than 500kb",
accept = "image/*",
file_list = list(list(
name = "food.jpeg",
url = "https://fuss10.elemecdn.com/3/63/4e7f3a15429bfda99bce42a18cdd1jpeg.jpeg"
))
)File List Control
Use on-change hook function to control upload file
list.
on_change sees the list change; keeping only the last
three files is a line of JavaScript.
el_upload(
"latest",
button_label = "Click to upload",
tip = "jpg/png files with a size less than 500kb",
on_change = JS(
"function(file, fileList) { if (fileList.length > 3) fileList.splice(0, fileList.length - 3); }"
)
)Drag to Upload
You can drag your file to a certain area to upload it.
el_upload(
"dropped",
drag = TRUE,
multiple = TRUE,
button_label = "Drop file here or click to upload",
tip = "jpg/png files with a size less than 500kb"
)Upload Directory
Enable folder upload via the directory prop.
After enabling it, only folders can be selected, and after selecting a folder, the files within the folder will be flattened.
directory = TRUE picks a folder, and uploads every file
in it; here dropped or chosen in the drag area.
el_upload(
"folder",
drag = TRUE,
directory = TRUE,
multiple = TRUE,
slots = list(
default = tagList(
el_icon("UploadFilled", class = "el-icon--upload"),
tags$div(
class = "el-upload__text",
"Drop directory here or ",
tags$em("click to upload")
)
)
)
)Manual Upload
auto_upload = FALSE keeps the files until
submit() sends them: from the browser,
$find(id).submit(), as upstream’s ref; from
the server, call_el().
el_upload(
"queued",
action = "https://run.mocky.io/v3/9d059bf9-4660-45f2-925d-ce80ad6c4d15",
auto_upload = FALSE,
button_label = "select file",
tip = "jpg/png files with a size less than 500kb"
)
el_button(
"send",
"upload to server",
type = "success",
on = list(click = v_on("$find('queued').submit()"))
)API
Element Plus’s tables, and beside each entry where it is in R.
Attributes
| Element | In R | Description | Type | Accepted | Default |
|---|---|---|---|---|---|
action |
action |
request URL. | 1 | # | |
headers |
headers |
request headers. |
2Headers \\| Record<string, any>
|
— | |
multiple |
multiple |
whether uploading multiple files is permitted. | 3 | false | |
data |
data |
additions options of request. support Awaitable data
and Function since v2.3.13. |
4Record<string, any> \\| Awaitable<Record<string, any>>
/ 5(rawFile: UploadRawFile) => Awaitable<Record<string, any>>
|
{} | |
with-credentials |
with_credentials |
whether cookies are sent. | 6 | false | |
show-file-list |
show_file_list |
whether to show the uploaded file list. | 7 | true | |
drag |
drag |
whether to activate drag and drop mode. | 8 | false | |
accept |
accept |
accepted file
types, will not work when thumbnail-mode === true. |
9 | ’’ | |
crossorigin |
crossorigin |
native attribute crossorigin. |
10'' \\| 'anonymous' \\| 'use-credentials'
|
— | |
on-preview |
on_preview |
hook function when clicking the uploaded files. |
11(uploadFile: UploadFile) => void
|
— | |
on-remove |
on_remove |
hook function when files are removed. |
12(uploadFile: UploadFile, uploadFiles: UploadFiles) => void
|
— | |
on-success |
input$<id> |
hook function when uploaded successfully. |
13(response: any, uploadFile: UploadFile, uploadFiles: UploadFiles) => void
|
— | |
on-error |
input$<id>_error |
hook function when some errors occurs. |
14(error: Error, uploadFile: UploadFile, uploadFiles: UploadFiles) => void
|
— | |
on-progress |
on_progress |
hook function when some progress occurs. |
15(evt: UploadProgressEvent, uploadFile: UploadFile, uploadFiles: UploadFiles) => void
|
— | |
on-change |
on_change |
hook function when select file or upload file success or upload file fail. |
16(uploadFile: UploadFile, uploadFiles: UploadFiles) => void
|
— | |
on-exceed |
on_exceed |
hook function when limit is exceeded. |
17(files: File[], uploadFiles: UploadUserFile[]) => void
|
— | |
before-upload |
before_upload |
hook function before uploading with the file to be uploaded as its
parameter. If false is returned or a Promise
is returned and then is rejected, uploading will be aborted. |
18(rawFile: UploadRawFile) => Awaitable<void \\| undefined \\| null \\| boolean \\| File \\| Blob>
|
— | |
before-remove |
before_remove |
hook function before removing a file with the file and file list as
its parameters. If false is returned or a
Promise is returned and then is rejected, removing will be
aborted. |
19(uploadFile: UploadFile, uploadFiles: UploadFiles) => Awaitable<boolean>
|
— | |
file-list |
file_list |
default uploaded files. |
20UploadUserFile[]
|
[] | |
list-type |
list_type |
type of file list. |
21'text' \\| 'picture' \\| 'picture-card'
|
text | |
auto-upload |
auto_upload |
whether to auto upload file. | 22 | true | |
http-request |
(the Shiny upload) |
override default xhr behavior, allowing you to implement your own upload-file’s request. |
23(options: UploadRequestOptions) => XMLHttpRequest \\| Promise<unknown>
|
ajaxUpload see | |
disabled |
disabled |
whether to disable upload. | 24 | false | |
limit |
limit |
maximum number of uploads allowed. | 25 | — | |
directory |
directory |
whether to support uploading directory. After enabling it, only folders can be selected, and after selecting a folder, the files within the folder will be flattened. | 26 | false |
Slots
| Element | In R | Description |
|---|---|---|
default |
default content | customize default content. |
trigger |
slots = list(trigger = ) |
content which triggers file dialog. |
tip |
slots = list(tip = ) |
content of tips. |
file |
slots = list(file = ) |
content of thumbnail template. |
Exposes
| Element | In R | Description |
|---|---|---|
abort |
call_el(session, id, "abort") |
cancel upload request. When a file is specified, abort
the corresponding pending upload; when no file is specified, abort all
pending uploads. |
submit |
call_el(session, id, "submit") |
upload the file list manually. |
clearFiles |
call_el(session, id, "clearFiles") |
clear the file list (this method is not supported in the
before-upload hook). |
handleStart |
call_el(session, id, "handleStart") |
select the file manually. |
handleRemove |
call_el(session, id, "handleRemove") |
remove the file manually. file and rawFile
has been merged. rawFile will be removed in
v2.2.0. |