File Picker
The file picker component enables users to select files either by opening a file selection dialog or by using drag-and-drop functionality.
import { registerFilePicker } from '@vonage/vivid';
registerFilePicker('your-prefix');
Use the single-file attribute to allow only a single file. Subsequent file uploads will replace the current file.
Use the max-files attribute to define how many files this file picker handles. By default, the file picker handles an unlimited number of files.
If the user tries to upload more files than the maximum number of files, the file picker displays the extra files with an error message.
Don't use this for single file uploads (with max-files="1"). Use the single-file attribute instead.
Use the max-files-exceeded-error attribute to provide a custom error message to override the default localized message.
Note: localisation will need to be handled at the application level.
- Type:
string
Use the max-file-size attribute to define the maximum file size (in megabytes) for each file.
The default max-file size is 256mb
If the user tries to upload a file that exceeds the maximum file size, the file picker displays an error message.
Use the file-too-big-error attribute provide a custom error message to override the default localized message. You can use the strings and in the message to give more information.
Note: localisation will need to be handled at the application level.
Use the accept attribute to define a list of allowed file extensions or MIME types.
Some examples of valid values are:
"image/*"- all image types"image/png"or".png"- only png images"image/jpeg, image/png"or".jpg, .jpeg, .png"- only jpg and png images
If the user tries to upload a file that does not match the accepted files, the File Picker displays an error message.
Invalid File Type Error
Use the invalid-file-type-error attribute to provide a custom error message to override the default localized message.
Note: localisation will need to be handled at the application level.
When setting block-size or max-block-size on the file-picker the list of the added files will have auto scroll.
Files files (Read-only)
Rejected Files rejectedFiles (Read-only)
Use files or rejectedFiles to access the list of files that have been added to the File Picker and passed or failed validation checks.
Use the default slot to set the content of the file picker.
The helper-text slot allows you to use rich content as the File Picker's helper text.
The contextual-help slot allows you to add the Contextual Help component next to the label.
Each added file in the preview list has a default background-color of --vvd-color-canvas (#fff in light theme, #000 in dark).
If needed, the background of the item can be changed using the --file-picker-list-item-background-color CSS variable.
| Property | Type | Default | Description |
|---|---|---|---|
| accept | string |
Defines a list of allowed file extensions or MIME types | |
| disabled | boolean |
Sets the element's disabled state. A disabled element will not be included during form submission. | |
| errorText | string |
Provides a custom error message. Any current error state will be overridden. | |
| fileTooBigError | string |
Custom error message shown when a file exceeds the maximum file size | |
| helperText | string |
Provides additional information to help the user enter the correct information. To add HTML to the helper text, use the helper-text slot instead. | |
| initialValue | string |
The default value of the element. This value sets the `value` property only when the `value` property has not been explicitly set. | |
| invalidFileTypeError | string |
Custom error message shown when a file does not match the accepted types | |
| label | string |
The label for the form element. | |
| maxFileSize | number |
Maximum allowed file size per file | |
| maxFiles | number |
Limits how many files can be selected; additional files will be rejected | |
| maxFilesExceededError | string |
Custom error message shown when more than the allowed number of files are selected | |
| name | string |
The name of the element. This element's value will be surfaced during form submission under the provided name. | |
| required | boolean |
Require the field to be completed prior to form submission. | |
| singleFile | boolean |
Allows only a single file; subsequent uploads replace the current file | |
| size | 'normal' | 'expanded' |
Sets the display size of the input element | |
| value | string |
The current value of the element. |
| Property | Type | Default | Description |
|---|---|---|---|
| accept | string |
Defines a list of allowed file extensions or MIME types | |
| disabled | boolean |
Sets the element's disabled state. A disabled element will not be included during form submission. | |
| error-text | string |
Provides a custom error message. Any current error state will be overridden. | |
| file-too-big-error | string |
Custom error message shown when a file exceeds the maximum file size | |
| helper-text | string |
Provides additional information to help the user enter the correct information. To add HTML to the helper text, use the helper-text slot instead. | |
| value | string |
The default value of the element. This value sets the `value` property only when the `value` property has not been explicitly set. | |
| invalid-file-type-error | string |
Custom error message shown when a file does not match the accepted types | |
| label | string |
The label for the form element. | |
| max-file-size | number |
Maximum allowed file size per file | |
| max-files | number |
Limits how many files can be selected; additional files will be rejected | |
| max-files-exceeded-error | string |
Custom error message shown when more than the allowed number of files are selected | |
| name | string |
The name of the element. This element's value will be surfaced during form submission under the provided name. | |
| required | boolean |
Require the field to be completed prior to form submission. | |
| single-file | boolean |
Allows only a single file; subsequent uploads replace the current file | |
| size | 'normal' | 'expanded' |
Sets the display size of the input element | |
| current-value | string |
The current value of the element. |
| Name | Description |
|---|---|
| contextual-help | Slot for the contextual-help component, displayed next to the label. |
| helper-text | Describes how to use the file-picker. Alternative to the `helper-text` attribute. |
| Name | Description |
|---|---|
| contextual-help | Slot for the contextual-help component, displayed next to the label. |
| helper-text | Describes how to use the file-picker. Alternative to the `helper-text` attribute. |
| Event | Type | Description |
|---|---|---|
| change | CustomEvent<undefined> |
Emitted when files are added or removed. |
| Name | Type | Description |
|---|---|---|
| change | CustomEvent<undefined> |
Emitted when files are added or removed. |
| Name | Params | Returns | Description |
|---|---|---|---|
| checkValidity |
boolean
|
Return the current validity of the element. | |
| removeAllFiles |
void
|
Removes all files from the File Picker. | |
| reportValidity |
boolean
|
Return the current validity of the element. If false, fires an invalid event at the element. |