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.

Usage

<script setup lang="ts">
import { VFilePicker } from '@vonage/vivid-api-vue';
</script>

<template>
  <VFilePicker label="Pick Files"> Drag & Drop or click to upload only one file </VFilePicker>
</template>

import { registerFilePicker } from '@vonage/vivid-api';

registerFilePicker('your-prefix');

<script type="module">
  import { registerFilePicker } from '@vonage/vivid-api';
  registerFilePicker('your-prefix');
</script>

<your-prefix-file-picker label="Pick Files"> Drag & Drop or click to upload only one file </your-prefix-file-picker>

Single File

Use the single-file attribute to allow only a single file. Subsequent file uploads will replace the current file.

Max Files

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.

<script setup lang="ts">
import { VFilePicker } from '@vonage/vivid-api-vue';
</script>

<template>
  <VFilePicker helper-text="Maximum of 2 files" max-files="2"> Drag & Drop or click to upload </VFilePicker>
</template>

Max Files Exceeded Error

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

<script setup lang="ts">
import { VFilePicker } from '@vonage/vivid-api-vue';
</script>

<template>
  <VFilePicker max-files-exceeded-error="Only 2 files allowed" helper-text="Maximum of 2 files" max-files="2"> Drag & Drop or click to upload </VFilePicker>
</template>

Max File Size

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.

<script setup lang="ts">
import { VFilePicker } from '@vonage/vivid-api-vue';
</script>

<template>
  <VFilePicker helper-text="Max file size is 0.1MB" max-file-size="0.1"> Drag & Drop or click to upload </VFilePicker>
</template>

File Too Big Error

Use the file-too-big-error attribute provide a custom error message to override the default localized message. You can use the strings {{filesize}} and {{maxFilesize}} in the message to give more information.

Note: localisation will need to be handled at the application level.

<script setup lang="ts">
import { VFilePicker } from '@vonage/vivid-api-vue';
</script>

<template>
  <VFilePicker file-too-big-error="File too large ({{filesize}} MiB). The maximum file size is {{maxFilesize}} MiB." helper-text="Max file size is 0.1MB" max-file-size="0.1"> Drag & Drop or click to upload </VFilePicker>
</template>

<vwc-file-picker file-too-big-error="File too large ({{filesize}} MiB). The maximum file size is {{maxFilesize}} MiB." helper-text="Max file size is 0.1MB" max-file-size="0.1">
  {' '}
  Drag & Drop or click to upload{' '}
</vwc-file-picker>

Accept

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.

<script setup lang="ts">
import { VFilePicker } from '@vonage/vivid-api-vue';
</script>

<template>
  <VFilePicker helper-text=".jpg, .jpeg types only" accept=".jpg, .jpeg"> Drag & Drop or click to upload </VFilePicker>
</template>

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.

<script setup lang="ts">
import { VFilePicker } from '@vonage/vivid-api-vue';
</script>

<template>
  <VFilePicker invalid-file-type-error="This file is not a .jpg or .jpeg" helper-text=".jpg, .jpeg types only" accept=".jpg, .jpeg"> Drag & Drop or click to upload </VFilePicker>
</template>

Block-Size

When setting block-size or max-block-size on the file-picker the list of the added files will have auto scroll.

Files & Rejected Files

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.

<script setup lang="ts">
import { VFilePicker, VButton, VLayout, VCard, VNote } from '@vonage/vivid-api-vue';
import { useTemplateRef, onMounted } from 'vue';

const filePickerRef = useTemplateRef('file-picker');
const noteRef = useTemplateRef('note');

const changeEvent = (event: CustomEvent) => {
const target = event.target;
noteRef.value.$el.headline = `files: ${target.files.length}, rejectedfiles: ${target.rejectedFiles.length}`;
};

function generateFile(fileName, sizeMb, type = 'text/plain') {
const sizeInBytes = sizeMb * 1024 * 1024;
const content = 'x'.repeat(sizeInBytes);
const blob = new Blob([content], { type });
return new File([blob], fileName, { type });
}

function simulateDrop(file) {
const dataTransfer = new DataTransfer();
dataTransfer.items.add(file);

    const dropEvent = new DragEvent('drop', {
      dataTransfer,
      bubbles: true,
      cancelable: true,
    });

    const vwcFilePicker = filePickerRef.value.$el;

    if (vwcFilePicker && vwcFilePicker.shadowRoot) {
      console.log(vwcFilePicker.shadowRoot);
      const dropzoneEl = vwcFilePicker.shadowRoot?.querySelector('.control');
      dropzoneEl.dispatchEvent(dropEvent);
    }

}

onMounted(() => {
const dummyFile1 = generateFile('dummy-image.jpg', 2, 'image/jpeg');
const dummyFile2 = generateFile('dummy-txt.jpg', 1, 'text/plain');

    const vwcFilePicker = filePickerRef.value;
    if (vwcFilePicker && vwcFilePicker.shadowRoot) {
      console.log('ele');
    }

    simulateDrop(dummyFile1);
    simulateDrop(dummyFile2);

});

</script>

<template>
  <form method="post" enctype="multipart/form-data" @submit.prevent="() => {}">
    <VLayout>
      <VCard>
        <VLayout slot="main" gutters="small">
          <VFilePicker name="files" label="Pick files" max-file-size="1" max-files-exceeded-error="Only 2 files allowed" helper-text="Maximum of 2 files" max-files="2" @change="changeEvent" required ref="file-picker"> Drag & Drop or click to upload</VFilePicker>
          <div class="buttons">
            <VButton label="Reset" type="reset" appearance="outlined"></VButton>
            <VButton label="Submit" appearance="filled" type="submit"></VButton>
          </div>
        </VLayout>
      </VCard>
      <VCard>
        <VLayout slot="main" gutters="small">
          <VNote headline="..." ref="note"></VNote>
        </VLayout>
      </VCard>
    </VLayout>
  </form>
</template>

<form method="post" enctype="multipart/form-data">
  <vwc-layout>
    <vwc-card>
      <vwc-layout slot="main" gutters="small">
        <vwc-file-picker name="files" label="Pick files" max-file-size="1" max-files-exceeded-error="Only 2 files allowed" helper-text="Maximum of 2 files" max-files="2" required> Drag & Drop or click to upload </vwc-file-picker>
        <div class="buttons">
          <vwc-button label="Reset" type="reset" appearance="outlined"></vwc-button>
          <vwc-button label="Submit" appearance="filled" type="submit"></vwc-button>
        </div>
      </vwc-layout>
    </vwc-card>
    <vwc-card>
      <vwc-layout slot="main" gutters="small">
        <vwc-note headline="..."></vwc-note>
      </vwc-layout>
    </vwc-card>
  </vwc-layout>
</form>
<script>
  window.addEventListener('load', function () {
    document.querySelector('vwc-file-picker').addEventListener('change', (e) => {
      const note = document.querySelector('vwc-note');
      note.headline = `files: ${event.target.files.length}, rejectedfiles: ${event.target.rejectedFiles.length}`;
    });

      document.querySelector('form').addEventListener('submit', (e) => {
        e.preventDefault();
      });

      function generateFile(fileName, sizeMb, type = 'text/plain') {
        const sizeInBytes = sizeMb * 1024 * 1024;
        const content = 'x'.repeat(sizeInBytes);
        const blob = new Blob([content], { type });
        return new File([blob], fileName, { type });
      }

      function simulateDrop(file) {
        const dataTransfer = new DataTransfer();
        dataTransfer.items.add(file);

        const dropEvent = new DragEvent('drop', {
          dataTransfer,
          bubbles: true,
          cancelable: true,
        });

        const vwcFilePicker = document.querySelector('vwc-file-picker');
        const dropzoneEl = vwcFilePicker.shadowRoot.querySelector('.control');
        dropzoneEl.dispatchEvent(dropEvent);
      }

      const dummyFile1 = generateFile('dummy-image.jpg', 2, 'image/jpeg');
      const dummyFile2 = generateFile('dummy-txt.jpg', 1, 'text/plain');

      simulateDrop(dummyFile1);
      simulateDrop(dummyFile2);
    });

</script>

Slots

Default

Use the default slot to set the content of the file picker.

<script setup lang="ts">
import { VFilePicker } from '@vonage/vivid-api-vue';
</script>

<template>
  <VFilePicker label="Label">
    {' '}
    Drag & Drop or <strong>Click</strong> to upload{' '}
  </VFilePicker>
</template>

<style scoped>
span {
  white-space: pre-wrap;
}
</style>

Helper-Text

The helper-text slot allows you to use rich content as the File Picker’s helper text.

<script setup lang="ts">
import { VFilePicker } from '@vonage/vivid-api-vue';
</script>

<template>
  <VFilePicker>
    Drag & Drop the .csv file here or click to upload
    <span slot="helper-text">Max file size is 0.1MB. <a href="#">Learn how export your data to .csv</a></span>
  </VFilePicker>
</template>

<vwc-file-picker>
  Drag & Drop the .csv file here or click to upload
  <span slot="helper-text">
    Max file size is 0.1MB. <a href="#">Learn how export your data to .csv</a>
  </span>
</vwc-file-picker>

Contextual Help

The contextual-help slot allows you to add the Contextual Help component next to the label.

<script setup lang="ts">
import { VFilePicker, VContextualHelp } from '@vonage/vivid-api-vue';
</script>

<template>
  <VFilePicker label="Upload file">
    Drag & Drop the .csv file here or click to upload
    <VContextualHelp slot="contextual-help">Max file size is 0.1MB.</VContextualHelp>
  </VFilePicker>
</template>

CSS Variables

file-picker-list-item-background-color

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.

API Reference

Properties

Property	Type	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	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.

Slots

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.

Events

Name	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.

Methods

Name	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.