FileUpload ​

The VFileUpload component is a form element that allows users to select and upload a file. It can be used with different themes, including a basic input field, a button, an image, or a dropzone.

Usage ​

Basic Usage ​

You can use it in your template as follows. This will render a basic file input field with the label "Label". The v-model directive is used to bind the value of the file input to the value variable, which can be a ref or a computed value.

Themes ​

The VFileUpload component supports several themes that can be applied using the theme prop. Here are some examples of how to use each theme:

Button Theme ​

This will render a file input field as a button, with the label "Label" displayed on the button.

Image Theme ​

This will render a file input field as an image, with the label "Label" displayed on the image.

Image Theme Full Width ​

This will render a file input field as a full-width image, with the label "Label" displayed on the image.

Dropzone Theme ​

This will render a file input field as a dropzone, with the label "Label" displayed on the dropzone.

Validation ​

You can use the VFileUpload component with form validation by using a validation library such as vee-validate. Here's an example of how to use the FileUpload component with vee-validate:

Initial Error ​

You can also specify initial errors for the VFileUpload component by providing an initialErrors object to the useForm hook:

Initial Values ​

You can also specify initial values for the VFileUpload component by providing an initialValues object to the useForm hook:

Props ​

Types ​

export type FileValue =
  | string
  | Record<string, any>
  | File
  | FileList
  | File[]
  | null;

export type FileValue =
  | string
  | Record<string, any>
  | File
  | FileList
  | File[]
  | null;

Events ​

The VFileUpload component emits several events that you can listen to and handle in your application.

update:modelValue ​

This event is emitted when the value of the file input is updated. It passes the new value as an argument.

Type:

(event: 'update:modelValue', value: FileValue): void

(event: 'update:modelValue', value: FileValue): void

Example:

<script setup lang="ts">
const onChange = (val: FileValue) => {
  console.log(val);
};
</script>

<template>
  <VFileUpload @update:modelValue="onChange" />
</template>

<script setup lang="ts">
const onChange = (val: FileValue) => {
  console.log(val);
};
</script>

<template>
  <VFileUpload @update:modelValue="onChange" />
</template>

change ​

This event is emitted when the value of the file input is changed. It passes the new value as an argument.

Type:

(event: 'change', value: FileValue): void

(event: 'change', value: FileValue): void

Example:

<script setup lang="ts">
const onChange = (val: FileValue) => {
  console.log(val);
};
</script>

<template>
  <VFileUpload @change="onChange" />
</template>

<script setup lang="ts">
const onChange = (val: FileValue) => {
  console.log(val);
};
</script>

<template>
  <VFileUpload @change="onChange" />
</template>

blur ​

This event is emitted when the file input loses focus. It passes the event object as an argument.

Type:

(event: 'blur', e: Event): void

(event: 'blur', e: Event): void

Example:

<script setup lang="ts">
const onBlur = (e: Event) => {
  console.log(e);
};
</script>

<template>
  <VFileUpload @blur="onBlur" />
</template>

<script setup lang="ts">
const onBlur = (e: Event) => {
  console.log(e);
};
</script>

<template>
  <VFileUpload @blur="onBlur" />
</template>

removed ​

This event is emitted when a file is removed from the file input.

Type:

(event: 'removed'): void

(event: 'removed'): void

Example:

<script setup lang="ts">
const onRemoved = () => {
  console.log('Removed!');
};
</script>

<template>
  <VFileUpload @removed="onRemoved" />
</template>

<script setup lang="ts">
const onRemoved = () => {
  console.log('Removed!');
};
</script>

<template>
  <VFileUpload @removed="onRemoved" />
</template>

Slots ​

The VFileUpload component has two slots that you can use to customize its content.

hint ​

Use the hint slot to add a hint or a description to the file input.

<template>
  <VFileUpload>
    <template #hint> Max 10MB. </template>
  </VFileUpload>
</template>

<template>
  <VFileUpload>
    <template #hint> Max 10MB. </template>
  </VFileUpload>
</template>

filename ​

Use the filename slot to customize displayed filename text

<template>
  <VFileUpload>
    <template #filename> A file has been chosen. </template>
  </VFileUpload>
</template>

<template>
  <VFileUpload>
    <template #filename> A file has been chosen. </template>
  </VFileUpload>
</template>

error ​

Use the error slot to customize the error message displayed when the file input has an error. The slot receives an object with the following properties:

• error: a boolean indicating whether the file input has an error
• errorMessages: an array of error messages
• field: the name of the field

Type:

type ErrorProps = {
  error: boolean;
  errorMessages: string[];
  field: string;
};

type ErrorProps = {
  error: boolean;
  errorMessages: string[];
  field: string;
};

Example:

<template>
  <VFileUpload>
    <template #error="{error, errorMessages, field}">
      <span class="text-red-500 text-xs">{{ errorMessages[0] }}</span>
    </template>
  </VFileUpload>
</template>

<template>
  <VFileUpload>
    <template #error="{error, errorMessages, field}">
      <span class="text-red-500 text-xs">{{ errorMessages[0] }}</span>
    </template>
  </VFileUpload>
</template>

CSS Variables ​

None

Standalone Installation ​

You can also install the FileUpload component individually via @morpheme/forms package:

npm i @morpheme/forms

npm i @morpheme/forms

<script setup lang="ts">
import {ref} from 'vue';
import {VFileUpload} from '@morpheme/forms';

const value = ref();
</script>

<template>
  <VFileUpload v-model="value" />
</template>

<script setup lang="ts">
import {ref} from 'vue';
import {VFileUpload} from '@morpheme/forms';

const value = ref();
</script>

<template>
  <VFileUpload v-model="value" />
</template>

Storybook ​

View Storybook documentation here.